Building Hydrogen from Source (macOS)

When it comes to macOS the term building is a little bit ambiguous. It can refer to either configuring, compiling, and installing the software on your own or to ask a package management programme, like MacPorts, Homebrew, or Fink, to perform all of this steps for you. The latter, which will be called installing from now on, is much faster and convenient but, on the other hand, does not allow you access the most recent, cutting edge versions of Hydrogen.

How to install Hydrogen on macOS

[Tested on macOS Mojave (10.14)]

Install the macOS Xcode Developer tools for your system (https://developer.apple.com/xcode/downloads/) as well as the corresponding the command line tools. This step sets up various compilers and language support in macOS necessary for your package management software to compile the Hydrogen source code and all its dependencies.

xcode-select --install

Download and install your favorite package managing programme. If you have no horse this race (yet), we would recommend using MacPorts.
Open a terminal and install Hydrogen (sudo will ask for your administrative password) with MacPorts (installs version 1.0.0-beta1)

sudo port install hydrogen

or Homebrew

brew install hydrogen

Further options

With MacPorts you also have some additional variants available. They compile the source code with some further libraries and enable additional features (but also use up a little bit more storage on your hard drive).

Enable debugging in the resulting binary:

sudo port install hydrogen +debug

Enable support for the JACK audio server:

sudo port install hydrogen +jack

Enable support for manipulating the RDF files describing LADSPA plugins. Note, this will only take effect if LADSPA support is properly installed on your system.

sudo port install hydrogen +lrdf

Starting Hydrogen

After the build has finished there should be now a Hydrogen application bundle located at e.g /Applications/MacPorts. You can start Hydrogen by double-clicking the file. If you want to use the command line, start it using

$ /Applications/MacPorts/hydrogen.app/Contents/MacOS/hydrogen

How to build Hydrogen from source

Another option is to retrieve the source code from GitHub and build Hydrogen on your own. The configuration and building itself is straight forward and will be outlined in the next lines of code. But in order to do so you have to ensure all dependencies have to be installed beforehand. This will topic will be covered in the next sections.

git clone https://github.com/hydrogen-music/hydrogen.git
cd hydrogen
mkdir build
cd build
cmake ..
make

If you intend to get involved in the development of Hydrogen, we would recommend you to use the build.sh script for more convenience (see INSTALL.md).

Installing all required dependencies

Unfortunately we do not have a dedicated Mac expert in our team right now and can only provide setups for selected versions of macOS using selected package managers. If you feel suited for this task, just edit/fix this wiki page and empower other Mac users to run the latest Hydrogen versions as well.

Please note that these different options are not mutually exclusive. It's probably worth trying some of them if you have problems with the build process.

macOS Mojave 10.14 with MacPorts

For macOS 10.14 this version is the only one the author was able to get running.

sudo port install cmake libsndfile jack cppunit libarchive qwt-qt5 qt5-qtxmlpatterns liblo liblrdf rubberband

cmake ..
make

macOS Catalina 10.15.4 with Homebrew (update to Sierra instructions below)

Still partly broken! (Could not build with CoreAudio and CoreMIDI support)

The H2 binary doesn't seem to work with JACK2 and qjackctl if these are installed from the "official" binaries. See #840 for the encountered problem.

Therefore, it appears necessary to build all three (hydrogen, jackd (JACK2) and qjackctl) from source. Proceed in this order (2 is optional but highly useful):

build jackd from source (Building jack was relatively straightforward, just clone and execute ./waf configure and ./waf build. I had to install aften before it worked with brew install aften, generally just check your prerequisites according to any warnings from ./waf configure.)
build qjackctl from source (see here)
build hydrogen

Building hydrogen as described below for "Sierra" works mostly, but needs some tweaks (at least for me):

The paths for building can be included in build.sh (somewhere near the top) for convenience, please be sure to modify for your actual version of Qt.

export Qt5XmlPatterns_DIR=/usr/local/Cellar/qt/5.14.1/lib/cmake/Qt5XmlPatterns
export Qt5Xml_DIR=/usr/local/Cellar/qt/5.14.1/lib/cmake/Qt5Xml
export Qt5Widgets_DIR=/usr/local/Cellar/qt/5.14.1/lib/cmake/Qt5Widgets
export Qt5LinguistTools_DIR=/usr/local/Cellar/qt/5.14.1/lib/cmake/Qt5LinguistTools
export LIBSNDFILE_PATH=/usr/local/opt/libsndfile/include
export CMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk
export SDKROOT=${CMAKE_OSX_SYSROOT}
export PATH="/usr/local/Cellar/jack/0.125.0_2/bin:/usr/local/opt/libarchive/bin:/usr/local/opt/libsndfile/include:$PATH"
export LIBARCHIVE_INCLUDE_DIRS=/usr/local/opt/libarchive/lib/pkgconfig:/usr/local/opt/libarchive/lib:/usr/local/opt/libarchive/include

Continue as per "Sierra" instructions with ./build.sh r && ./build.sh m, but be sure to update all paths related to your self-built installation of jack.

If (like ppenguin in #840) your hydrogen doesn't have CoreAudio you can just connect its audio out channels to e.g. your DAW (like Ardour) which takes care of playing it. Through JackMidi you can also just use hydrogen as a midi-generator and connect its output to a MIDI-in on your DAW and play the MIDI notes on your DAW e.g. using an AU/VST like MD drummer.

macOS Sierra 10.12.6 with Homebrew

(Contributed via #657)

brew install cmake
brew install jack
brew install tar
brew install libtar
brew install libarchive
brew install libsndfile
brew install qt

export Qt5XmlPatterns_DIR=/usr/local/opt/qt/lib/cmake/Qt5XmlPatterns
export Qt5Xml_DIR=/usr/local/opt/qt/lib/cmake/Qt5Xml
export Qt5Widgets_DIR=/usr/local/opt/qt/lib/cmake/Qt5Widgets
export Qt5LinguistTools_DIR=/usr/local/opt/qt/lib/cmake/Qt5LinguistTools
export LIBSNDFILE_PATH=/usr/local/opt/libsndfile/include
export CMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.13.sdk
export SDKROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.13.sdk
export PATH="/usr/local/Cellar/jack/0.125.0_2/bin:/usr/local/opt/libarchive/bin:/usr/local/opt/libsndfile/include:$PATH"
export LIBARCHIVE_INCLUDE_DIRS=/usr/local/opt/libarchive/lib/pkgconfig:/usr/local/opt/libarchive/lib:/usr/local/opt/libarchive/include

./build.sh r && ./build.sh m

At this point failures to compile,

./src/core/include/hydrogen/basics/sample.h:27:10: fatal error: 'sndfile.h' file not found

So:

cp /usr/local/opt/libsndfile/include/sndfile.hh ./src/core/include/hydrogen/sndfile.hh
cp /usr/local/opt/libsndfile/include/sndfile.h ./src/core/include/hydrogen/sndfile.h

vi ./src/core/include/hydrogen/basics/sample.h # change include
#include <hydrogen/sndfile.h>
:wq

At this point still fails to compile,

./build.sh m

./src/core/include/hydrogen/IO/JackAudioDriver.h:34:10: fatal error: 'jack/jack.h' file not found

So:

vi ./build/CMakeCache.txt # and change these:
PC_JACK_jack_INCLUDEDIR:INTERNAL=/usr/local/Cellar/jack/0.125.0_2/include
PC_JACK_jack_LIBDIR:INTERNAL=/usr/local/Cellar/jack/0.125.0_2/lib
:wq

vi ./build/src/gui/CMakeFiles/hydrogen.dir/flags.make # and add missing jack include
CXX_INCLUDES = -I/usr/local/Cellar/jack/0.125.0_2/include  #...
:wq

Finally this worked:

./build.sh m
open hydrogen.app

macOS 10.10 using Homebrew

sudo ln -s /usr/local /opt/local
brew update
brew install qt5 libarchive libsndfile jack pulseaudio cppunit
export CMAKE_PREFIX_PATH="$(brew --prefix qt5)"
export PKG_CONFIG_PATH="$(brew --prefix libarchive)/lib/pkgconfig"
mkdir build && cd build && cmake -DWANT_LASH=1 -DWANT_LRDF=1 -DWANT_RUBBERBAND=1 .. && make

For reference you might also take a look into the older versions of this page:

! WARNING : the following content of this page is out of date. It is only here for archival..

but involves some preparation. Three methods are described on this page:

1. Building everything with MacPorts .

Advantage: by far the easiest way

Disadvantage: does not result in the most up to date Hydrogen version

2. Building partly with MacPorts, and partly by hand

Advantage: results in the most up to date Hydrogen version from SVN

Disadvantage: a bit more difficult and time-consuming

3. Building partly with Fink, and partly by hand

Advantage: results in the most up to date Hydrogen version from SVN

Disadvantage: a bit more difficult and time-consuming

(NOTE: Method 2 and 3 are almost the same. Both MacPorts and Fink are a way to build, install and manage open source software on Mac Os X. Both have thousands of open source software packages available. MacPorts uses a BSD style package management. Fink uses a Debian Linux style package management. Neither one is 'better' than the other. MacPorts tends to be a little quicker in updating packages, Fink has a little more packages available. Fink also has a small number of pre-built packages available, which may be more convenient for starters.)

Method 1. Building everything with MacPorts

Preparing your system

Install the macOS Xcode Developer tools for your system (https://developer.apple.com/xcode/downloads/). Be sure to choose Unix tools as well when installing.
Download and install MacPorts from https://www.macports.org/install.php;
(Optional) Download and install a graphical frontend to MacPorts, for instance PortAuthority or Porticus.

Building Hydrogen with MacPorts

In PortAuthority search for "hydrogen", select with mouse, choose "installations > Install a Port" from menu. If you don't have PortAuthority, open a terminal and install hydrogen with sudo port install hydrogen (sudo will ask for your administrative password).
Compiling will now start. This is basically it. MacPorts will now find all dependencies, compile all, and finally install Hydrogen in /Applications/MacPorts/. It takes several hours to complete on a fast Mac.

Method 2. Building partly with MacPorts and partly by hand

The following procedure involves two parts:

A. Setting up the necessary build environment using MacPorts (read point 1-3 under 'method 1' on how to set up MacPorts)

B. Building Hydrogen by hand.

(NOTE: All commands are indicated with a $. Just copy-paste the command into the Terminal without the $)

A. Setting up the necessary build environment using MacPorts

Build the following applications with MacPorts: qt4-mac flac libsndfile jack liblrdf libarchive scons. Either via a graphical frontend, or at the command line:

$ sudo port install qt4-mac flac libsndfile jack liblrdf libarchive scons This may take several hours to complete on a fast Mac.

B. Building Hydrogen by hand

Open the macosx Terminal application. First you must set the build environment

$ export QTDIR=/opt/local/libexec/qt4-mac
and set executable paths

$ export PATH="/usr/bin:/bin:/usr/sbin:/sbin:/usr/X11R6/bin:/usr/local/bin:/usr/local/sbin:/opt/local/bin:/opt/local/sbin:/opt/local/libexec/qt4-mac/bin"

(NOTE: you can set these values permanently in ~/.profile or ~/.bashrc)

Download the Hydrogen sources from the trunk branch

$ svn co http://svn.assembla.com/svn/hydrogen/trunk
Move into the build directory

$ cd trunk
Build with scons (variables can be set with =1 and unset with =0): (I am assuming you want to build with jack. Get Jack from http://jackosx.com/ and install first.)

$ scons alsa=0 coreaudio=1 coremidi=1 flac=1 jack=1 lash=0 libarchive=1 lrdf=1 oss=0 portaudio=0 portmidi=0 bundle=1

If you don't care for an application bundle and want to run Hydrogen directly from the build directory, set bundle=0. If you set bundle=1 you can make a nice app bundle and dmg package by doing the following:

Create *.app directory structure

$ mkdir Hydrogen.app ; mkdir Hydrogen.app/Contents ; mkdir Hydrogen.app/Contents/MacOS ; mkdir Hydrogen.app/Contents/Resources
Copy necessary files into the application bundle (in case of scons bundle=1)

$ cp -R ./data ./plugins ./Hydrogen.app/Contents/Resources/ ; cp ./macos/Hydrogen.icns ./Hydrogen.app/Contents/Resources/ ; cp ./macos/Info.plist ./Hydrogen.app/Contents/

or if bundle=0

$ cp -R ./data ./Hydrogen.app/Contents/MacOS/ ; cp -R ./plugins ./Hydrogen.app/Contents/Resources/ ; cp ./macos/Hydrogen.icns ./Hydrogen.app/Contents/Resources/ ; cp ./macos/Info.plist ./Hydrogen.app/Contents/

Copy binary into bundle

$ cp hydrogen Hydrogen.app/Contents/MacOS/Hydrogen
Build a self-contained *.app bundle

$ /opt/local/libexec/qt4-mac/bin/macdeployqt Hydrogen.app
Rename binary and copy launch script, and make executable

$ mv Hydrogen.app/Contents/MacOS/Hydrogen Hydrogen.app/Contents/MacOS/Hydrogen-bin ; cp macos/hydrogen.sh Hydrogen.app/Contents/MacOS/Hydrogen ; chmod 770 ./Hydrogen.app/Contents/MacOS/Hydrogen
Throw away bundled jack lib and symlink to system's installed framework

$ rm -f Hydrogen.app/Contents/Frameworks/libjack.0.dylib ; ln -s /Library/Frameworks/Jackmp.framework/Jackmp Hydrogen.app/Contents/Frameworks/libjack.0.dylib
Finalize the packaging and make a dmg package

/opt/local/libexec/qt4-mac/bin/macdeployqt Hydrogen.app -dmg You can check whether the dependencies of the executable have been built-in

$ otool -L Hydrogen.app/Contents/MacOS/Hydrogen-bin

It should only list paths that are ubiquitously present on all mac systems (/System/Library/Frameworks/ and /usr/lib/) and paths built into the Hydrogen application bundle (@executable_path/../Frameworks/)

You are now ready to use and/or redistribute Hydrogen (under certain conditions, see license file COPYING)!

Method 3. Building partly with Fink, and partly by hand

The following procedure involves two parts:

A. Setting up the necessary build environment using Fink

B. Building Hydrogen by hand.

(NOTE: All commands are indicated with a $. Just copy-paste the command into the Terminal without the $)

A. Setting up the necessary build environment using Fink

Setting up Fink entails downloading a version for your system. A graphical front-end to Fink is FinkCommander.

Build the following applications with Fink: jack flac libtar libsndfile openssl liblrdf scons. Either via a graphical frontend, or at the command line:

$ sudo fink install qt4-mac flac libsndfile jack liblrdf libarchive scons

This may take several hours to complete on a fast Mac.

B. Building Hydrogen by hand

Open the macosx Terminal application. First you must set the build environment

$ export QTDIR=/sw/lib/qt4-mac

And set executable paths

$ export PATH="/usr/bin:/bin:/usr/sbin:/sbin:/usr/X11R6/bin:/sw/bin:/sw/sbin:/usr/local/bin:/usr/local/sbin:"

(NOTE: you can set these values permanently in ~/.profile or ~/.bashrc)

Download the Hydrogen sources from the trunk branch

$ svn co http://svn.assembla.com/svn/hydrogen/trunk

Move into the build directory

$ cd trunk 6) Open the Sconstruct file in the build directory with a texteditor, and modify as follows at line 88 and further (this is to make sure scons uses the dependencies compiled with Fink):

    if sys.platform == "darwin":

#	ldflags.append( '-L/opt/local/lib' )
    ldflags.append( '-L/usr/local/lib' )
    ldflags.append( '-L/sw/lib' )
	
#   includes.append( '/opt/local/include' )
    includes.append( '/usr/local/include/jack' )
    includes.append( '/sw/include' )

In features.pri you may have to replace lines 18-24 with:

LIBS += /sw/lib/libFLAC.dylib LIBS += /sw/lib/libFLAC++.dylib LIBS += /usr/local/lib/libjack.dylib LIBS += /sw/lib/libtar.dylib LIBS += /sw/lib/libpng.dylib LIBS += /sw/lib/libsndfile.dylib
Build with scons (variables can be set with =1 and unset with =0 ) (I am assuming you want to build with jack. Get Jack from http://jackosx.com/ and install first.)

$ scons alsa=0 coreaudio=1 coremidi=1 flac=1 jack=1 lash=0 libarchive=1 lrdf=1 oss=0 portaudio=0 portmidi=0 bundle=1

If you don't care for an application bundle and want to run Hydrogen directly from the build directory, set bundle=0. If you set bundle=1 you can make a nice app bundle and dmg package by doing the following:

Create *.app directory structure

$ mkdir Hydrogen.app ; mkdir Hydrogen.app/Contents ; mkdir Hydrogen.app/Contents/MacOS ; mkdir Hydrogen.app/Contents/Resources

Copy necessary files into the application bundle (in case of scons bundle=1)

$ cp -R ./data ./plugins ./Hydrogen.app/Contents/Resources/ ; cp ./macos/Hydrogen.icns ./Hydrogen.app/Contents/Resources/ ; cp ./macos/Info.plist ./Hydrogen.app/Contents/

or if bundle=0

$ cp -R ./data ./Hydrogen.app/Contents/MacOS/ ; cp -R ./plugins ./Hydrogen.app/Contents/Resources/ ; cp ./macos/Hydrogen.icns ./Hydrogen.app/Contents/Resources/ ; cp ./macos/Info.plist ./Hydrogen.app/Contents/

Copy binary into bundle

$ cp hydrogen Hydrogen.app/Contents/MacOS/Hydrogen

Build a self-contained *.app bundle

$ /sw/lib/qt4-mac/bin/macdeployqt Hydrogen.app

Rename binary and copy launch script, and make executable

$ mv Hydrogen.app/Contents/MacOS/Hydrogen Hydrogen.app/Contents/MacOS/Hydrogen-bin ; cp macos/hydrogen.sh Hydrogen.app/Contents/MacOS/Hydrogen ; chmod 770 ./Hydrogen.app/Contents/MacOS/Hydrogen

Throw away bundled jack lib and symlink to system's installed framework

$ rm -f Hydrogen.app/Contents/Frameworks/libjack.0.dylib ; ln -s /Library/Frameworks/Jackmp.framework/Jackmp Hydrogen.app/Contents/Frameworks/libjack.0.dylib

Finalize the packaging and make a dmg package

/sw/lib/qt4-mac/bin/macdeployqt Hydrogen.app -dmg You can check whether the dependencies of the executable have been built-in using otool :

$ otool -L Hydrogen.app/Contents/MacOS/Hydrogen-bin