catala/INSTALL.md

Building and installing the Catala language

Hint: you can find pre-built nightly binaries on this page. The following will guide you through compiling and installing from source.

Requirements

With Docker

The Catala compiler is written using OCaml. The repository provides a Dockerfile to build a Docker image with all the dependencies required to build the Catala compiler.

Start by installing Docker: https://docs.docker.com/get-docker/

Then build the Docker image. From the root of this repository, run:

docker build . -t catala

(Note: this may take a while, since it will check all targets and run all tests.) Finally, start a shell inside a new container created from the newly built image:

docker run -it --name catala catala

The generated binaries will be in ~/catala/_build/install/default. Get started by running:

./_build/install/default/bin/catala --help

With opam

The Catala compiler is written using OCaml. First, you have to install opam, OCaml's distribution and package manager. Follow the instructions on the opam website.

Next, you will need to use the correct version of OCaml. Catala has been tested with OCaml compiler versions that are at least 4.14.0. To switch to OCaml 4.14.0, just use:

opam switch 4.14.0

If you get a No switch 4.14.0 is currently installed error message, follow the hint and enter opam switch create 4.14.0.

With nix (best effort)

Warning

Nix support for the Catala compiler is now on a "best effort" basis due to maintenance demands. Interested users are encouraged to contribute via pull requests.

The repository provides nix files to build or develop the catala compiler.

Once nix is installed, with flakes enabled it is possible to enter a development shell:

nix develop

or to build the Catala compiler, documentation and runtime library:

nix build

Dependencies not yet in nixpkgs (ubase and unionFind at the moment of writing) are hardcoded inside the .nix directory. The .nix/catala.nix should be compatible with nixpkgs, if it finds a maintainer.

To develop catala's compiler using vscode using ocaml's lsp, you can use the ocaml-platform extension with the following settings (inside the file .vscode/settings.json).

{
  "ocaml.sandbox": {
    "kind": "custom",
    "template": "nix develop --command $prog $args"
  },
}

The nix build is updated weekly by an automatic github action.

Dependencies

You can skip this step if you used the Docker option above, it is already taken care of.

Next, install all the packages that Catala depends on with

make dependencies

This should ensure everything is set up for developing on the Catala compiler!

The Python dependencies are installed inside a local virtual environment (venv). To use it, for example to run Python code generated by Catala, you should run the following command once in every new shell session:

. _python_venv/bin/activate

Warning: the make dependencies command does not include the z3 dependency required to enable the proof platform feature of Catala. If you wish to enable support for the Proof command of the Catala compiler, you should instead execute make dependencies-with-z3 prior to building the compiler.

Other features of the Catala repository also require the following executables to be present. On debian, arch or apline-based distributions, the above command should already take care of them.

groff python3 pip rsync colordiff nodejs npm

Build

The project is distributed as a Dune artifact. Use standard dune commands to build and install the library. Makefile aliases are here to help you: running

make build

builds the compiler from its OCaml sources.

Install

The installation of the Catala compiler is handled through opam. For the latest release, you can directly run

opam install catala

but if you are here you will probably prefer installing from the sources, which should be as easy as:

opam install ./

To uninstall, use

opam remove ./

Generating website assets

Updating @catala-lang/catala-web-assets

The Catala website features assets generated by the Catala compiler. They are needed to build the website. To produce them, simply run

make website-assets DUNE_PROFILE=release

Then, use a helper script to copy them over to the assets directory of the catala-web-assets repository.

./generate_website_assets.sh <path-to-catala-web-assets>/assets

You will need the groff executable to generate the HTML versions of the man pages, as well as the rsync executable to transfer files (preferred to cp) because it also works with a remote server.

Updating @catala-lang/french-law

When a new version of the french_law.js (see the dedicated README to generate the lib) needs to be published, you need to execute from the french_law/js directory, the following commands:

npm version patch -m "Patch message"
npm publish

Syntax highlighting

See the dedicated README.md.