------------------------------------------------------------------------------
                       H Y D R O G E N          Drum machine
------------------------------------------------------------------------------

BUILDING AND INSTALLING HYDROGEN
================================

Content:

1. [System Requirements](#system-requirements)
2. [Binary Packages](#binary-packages)
3. [Build and Install from Source](#build-and-install-from-source)
4. [Build an AppImage](#build-an-appimage)
5. [Generate the Documentation](#generate-the-documentation)


## System Requirements

Hydrogen is supported on the following operating systems:

  * Linux/Unix/BSD
  * Mac OS X
  * Windows

## Binary Packages

### Mac OS X and Windows

Hydrogen can be downloaded as a binary package, source distribution,
or you can check out the current development version.

Binary packages can be accessed on the project's Github page:

- [https://github.com/hydrogen-music/hydrogen/releases](https://github.com/hydrogen-music/hydrogen/releases)

If you are interested in older versions or installers, you can check
out the Hydrogen home page:

- [http://www.hydrogen-music.org/](http://www.hydrogen-music.org/)

To get the latest version with the latest features on **Mac OS X**,
you can install Hydrogen using **Mac Ports**.

- [Installing on Mac OS X with MacPorts](https://github.com/hydrogen-music/hydrogen/wiki/Building-Hydrogen-from-source-(MAC-OSX)#method-1-building-everything-with-macports
)

### Linux

Please check your package management system for the package called
_hydrogen_. In **Debian (GNU/Linux)**-based distributions this can be
done with `apt`

``` bash
$ sudo apt-get install hydrogen
```

## Build and Install from Source

### Mac OS X

If you intend to build Hydrogen from source on Mac OS X, please read
the relevant wiki pages for more information:

- [Building Hydrogen from source on Mac OS X](https://github.com/hydrogen-music/hydrogen/wiki/Building-Hydrogen-from-Source-(macOS))
  
### Windows

For building Hydrogen on Windows, please check out the following wiki
page:

- [Packaging Hydrogen for Windows](https://github.com/hydrogen-music/hydrogen/wiki/Packaging-for-Windows)

as well as our native build scripts in the [windows](windows/) folder.

### Linux

#### Prerequisites

The source code for the current development version can be checked out
via git:

``` bash
$ git clone git://github.com/hydrogen-music/hydrogen.git
```

In order to build Hydrogen from source, you will need the following
libraries and development header files installed on your system:

##### Required

- Qt 6 or Qt 5
- GNU g++ compiler (>=4.0, 3.x might work)
- cmake (>=3.5)
- libsndfile >=1.0.18
- zlib and libtar *OR* libarchive

##### Optional Support

- liblo for OSC (Open Sound Control)
- NSM (Non Session Manager)
- liblrdf for LADSPA plugins
- librubberband2 (Rubberband support is experimental)

Currently it is recommended that you disable the rubberband config
option (done by default) to ensure backwards compatibility with songs
created under 0.9.5 which use rubberband. Install the `rubberband-cli`
package beside `librubberband2`. Rubberband works properly even if
this option is disabled. If available, Hydrogen locates the installed
`rubberband-cli` binary.

##### Packages Required on Debian-based Systems

In order to build Hydrogen on Debian-based Systems, you can use the
following command to install all basic and some optional requirements.

``` bash
$ sudo apt-get install cmake qt6-base-dev qt6-base-dev-tools qt6-tools-dev \
  qt6-tools-dev-tools qt6-svg-dev libarchive-dev libsndfile1-dev           \
  libasound2-dev liblo-dev libpulse-dev libcppunit-dev liblrdf0-dev        \
  librubberband-dev libjack-jackd2-dev
```


#### Building and Installing Hydrogen

After you have installed all the prerequisites, building and
installing will look like this:

``` bash
$ git clone git://github.com/hydrogen-music/hydrogen.git
$ cd hydrogen
$ mkdir build && cd build
$ cmake -DWANT_QT6:BOOL=ON ..
$ make && sudo make install
```

Note that we are in a transitional phase from Qt5 to Qt6 right now. You could
also install the Qt5 versions of the packages above and omit the
`-DWANT_QT6:BOOL=ON` option to build the application with Qt5 instead.

#### Running Hydrogen

Some common problems encountered by user building from source:

##### Command not found / wrong version

In case you get the error

> ... command not found: hydrogen

or the wrong version of Hydrogen is starting up, your shell is not able to find
the one you just installed (you can check using `which hydrogen`).

After installation, Hydrogen's binaries can be found in `/usr/local/bin`.
If this path is not in your `PATH` environment variable (you can check using
`echo $PATH`), you should add

```bash
export PATH=/usr/local/bin:$PATH
```

to your `$HOME/.profile` file (or .bashrc, .zshrc, or .xprofile in case you
prefer those) and run `source ~/.profile`.

##### Error loading shared libraries

If Hydrogen doesn't start, and you get a message similar to:

> … error while loading shared libraries: libhydrogen-core-1.X.X.so …

your OS could not find the shared library you just compiled and installed along
with the program itself.

Seems like your Linux distribution is more user than developer focused. This is
not a big problem. It just added `/usr/local/bin` to `$PATH` but not `/usr/local/lib`
to `$LD_LIBRARY_PATH`.

Installing your local build to `/usr/local` is more or less standard. `/usr` should be
used by your package manager. This allows you to manually compile and install custom
Hydrogen versions without messing with the system's one. We just have to tell the system
where to find all required pieces.

You could use the `/usr` installation prefix when building Hydrogen. But I would strongly
discourage that. Instead, you could do one of these:

- run `sudo ldconfig` and check whether this already fixes your issue
- open Hydrogen via the command line using `LD_LIBRARY_PATH=/usr/local/lib hydrogen`
- add `export LD_LIBRARY_PATH=/usr/local/lib:${LD_LIBRARY_PATH}` to your `$HOME/.profile`
- set a symlink as you mentioned from `/usr/local/lib/libhydrogen-core.1.X.X.so` to
  `/usr/lib/`

see [issue#677](https://github.com/hydrogen-music/hydrogen/issues/677) for further insights.

#### Build Script

Alternatively you could use our custom build script
[./build.sh](https://github.com/hydrogen-music/hydrogen/blob/main/build.sh). This
is the recommended way if you are actively developing new
features or bug fixes for Hydrogen (all characters in squared brackets
are optional and do not have to be included in the command).

| Command          | Functionality                                                     |
|------------------|-------------------------------------------------------------------|
| `r[m]`           | Remove all build, temporary, and cached files.                    |
| `c[lean]`        | Remove all cached files.                                          |
| `m[ake]`         | Launch the build process.                                         |
| `mm`             | Launch the build process using `ccache`.                          |
| `d[oc]`          | Build the documentation of Hydrogen.                              |
| `g[raph]`        | Draw the dependency graphs of the Hydrogen code using `graphviz`. |
| `h[elp]`         | Show all supported build options.                                 |
| `[e]x[ec]`       | Execute the Hydrogen binary.                                      |
| `t[est]`         | Run the unit tests.                                               |
| `p[kg]`          | Build a source package.                                           |
| `i[integration]` | Execute integration tests.                                        |
| `appimage`       | Build an AppImage.                                                |
| `z`              | Build Hydrogen using `ccache` and execute the resulting binary.   |

Using `ccache` to build Hydrogen, `./build.sh mm`, will result in a
compilation, which takes a little longer than the one with the usual
`make` command. But in all further runs, only the recently-modified
components will be recompiled. This can marginally speed up development.

Note: if you want to run the integration tests, you need to have both `JACK`
server and `Go` installed.

#### Additional Build Features and Uninstall

All the following `cmake` commands should be executed in a build
directory :

If you wish to configure features like **LADSPA plugins**,
or **debugging symbols**, get more information like this:

``` bash
$ cmake -L ..
```

For possible **make targets**:

``` bash
$ make help
```

To change the directory Hydrogen will be installed in, you have to
provide the `-DCMAKE_INSTALL_PREFIX` option during the configuration
of your custom build (the default path is */usr/local/*).

``` bash
$ cmake -DCMAKE_INSTALL_PREFIX=/opt/hydrogen ..
$ make && sudo make install
```

**Uninstalling** Hydrogen is done like this:

``` bash
$ sudo cmake uninstall
```

Note that `cmake` is a build system and not a package manager.  While
we make every effort to ensure that Hydrogen uninstalls cleanly, it is
not guaranteed.

`cmake` macros should detect the correct Qt settings and location of
your libraries, but sometimes it needs a little help.  If Hydrogen
fails to build, some environment variables could help it.

``` bash
$ QTDIR=/opt/lib/qt4 OSS_PATH="/usr/lib/oss/lib" OSS_INCLUDE="/usr/lib/oss/include" cmake ..
```

## Build an AppImage

For creating an _AppImage_ you have to install all required package as
described in the previous step. Then you can simply run the dedicated
build script command

``` bash
# ./build.sh appimage
```

This will download the latest toolchain required for AppImage
packaging (in case you haven't installed it yet) and creates a fresh
image in the _build-appimage_ folder.

To run it, ensure it's executable and call it from the console or open
it using double click.

## Generate the Documentation

Apart from the [official manuals and
tutorial](http://hydrogen-music.org/doc/), Hydrogen does also feature
an extended documentation of its code base.

After installing the requite `Doxygen` package

```bash
$ sudo apt-get install doxygen
```

run the following command

``` bash
$ ./build.sh d
```

It will produce two folders, *build/docs/html/* and *build/docs/latex*,
containing the documentation as HTML and LaTeX, respectively. The HTML
version is recommended since it provides a more friendly way to navigate
through the set of created files. You can view them using your
favorite browser, e.g.

``` bash
$ firefox build/docs/html/index.html
```
