Building Liquidsoap

Forewords

Installing liquidsoap can be a difficult task. The software relies on a up-to date OCaml compiler, as well as a bunch of OCaml modules and, for most of them, corresponding C library dependencies.

Our recommended way of installing liquidsoap is via opam. opam can take care of installing the correct OCaml compiler, optional and required dependencies as well as system-specific package dependencies.

The opam method is described in details in the documentation. We recommend that any interested user head over to this link to install the software via opam.

The remainder of this document describes how to compile liquidsoap locally for developers.

Overview

Liquidsoap is compiled using dune, which is the most popular OCaml build system at the moment. dune is tightly integrated with opam so, even if you are installing from source using dune, opam remains an important tool.

Generally speaking, compiling from source may require the latest version of the liquidsoap code as well as its dependencies. Some of its dependencies are optional and can be ignored at first and some are not.

Keep in mind that, although opam is generally aware of required minimal version for dependencies, dune is not. If a dependency is outdated, dune compilation will simply fail, at which point your may have to figure out if you need to update a dependency.

Each branch of liquidsoap is compiled using github actions. When trying to build a specific branch, if the CI passes with it then, most likely, you are missing a dependency or it is not the latest version.

opam pinning

opam pinning is a mechanism to update opam with the latest version of a package, even before it is published to the official opam repository. This is the easiest way to update a dependency to its latest version.

You can pin directly from a local git repository checkout:

git clone https://github.com/savonet/ocaml-metadata.git
cd ocaml-metadata
opam pin -ny .

You can also pin directly using a git url:

opam pin -ny git+https://github.com/savonet/ocaml-cry

See opam pin --help for more defails about the available options.

Dependencies

The best way to figure out what dependencies are required or optional and their versions is to use the latest opam package. Since liquidsoap development is using dune and opam, the dependencies are kept in sync via the local liquidsoap opam package(s) and this serves as the de-facto list of dependencies and their versions.

First, you should pin the latest liquidsoap code:

opam pin -ny git+https://github.com/savonet/liquidsoap

Then, ask opam to list all the dependencies for liquidsoap:

opam info liquidsoap
opam info liquidsoap-core
opam info liquidsoa-lang

This should give you a (long!) list of all dependencies. Then, you can query opam to see what each dependency does. This is particularly useful for optional dependencies on liquidsoap-core which provide opt-in features. For instance opam info soundtouch will let you know that this package provides functions for changing pitch and timestretching audio data.

Lastly, there are two types of dependencies:

  • Dependencies maintained by us
  • Dependencies not maintained by us

For dependencies not maintained by us, most of the time, we rely on the latest published version. Very rarely should you have to fetch/pin the latest version of these dependencies.

For dependencies maintained by us, we may break their API during our development cycle and you maybe have to fetch/pin the latest version when compilign the latest liquidsoap code. You may also have to check out a specific branch when compiling liquidsoap from a specific development branch when the changes in the liquidsoap code are paired with changes in one of our dependencies. Typically, this happens a lof with the ffmpeg binding.

Compiling

Once you have all dependencies installed, you should be able to compile via:

dune build

If an error occurs, you may need to see if you need to update a dependency. Hopefully, with a short iteration of this cycle, you will end up with a successful build!

Once you have a successful build, you can also use the top-level liquidsoap script. This script builds the latest code and executes it right away. It works as if you were calling the liquidsoap binary after installing it:

./liquidsoap -h output.ao

From here, you can start changing code, testing script etc. Happy hacking!