# Building Liquidsoap

## Forewords

Installing liquidsoap can be a difficult task. The software relies on an 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 details 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-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 compiling 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.

## Environment variables

When compiling Liquidsoap from source, certain environment variables can be set to control the build process and customize the build configuration. Here’s a brief overview of the relevant environment variables and their purposes:

- `IS_SNAPSHOT`: Set this variable to indicate whether you are building a snapshot version of Liquidsoap. It affects the version suffix and whether the Git commit is displayed.
- `LIQ_GIT_SHA`: Override Git commit hash (SHA) if the build system cannot automatically extract it from the repository.
- `LIQ_VERSION`: Override the displayed version of Liquidsoap.
- `LIQUIDSOAP_ENABLE_BUILD_CONFIG`: Determines whether the build configuration details are displayed during the build process.
- `LIQUIDSOAP_BUILD_TARGET`: Controls the runtime lookup paths for Liquidsoap components.
  - Set to `default`: Uses paths detected in the OPAM switch directory.
  - Set to `standalone`: Uses paths relative to the binary location, ideal for self-contained deployments.
  - Set to `posix`: Configures paths to standard system directories.

## 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!