catala/INSTALL.md

Building and installing the Catala language

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:

docker build . --target dev-build-context -t catala

Finally, start a shell inside a new container created from the newly built image:

docker run -it --name catala catala

With nix

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

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

nix-shell

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

nix-build release.nix

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

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.13.0. To switch to OCaml 4.13.0., just use:

opam switch 4.13.0

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

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!

Warning: this 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 platform and 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 virtualenv python3 pip rsync colordiff pygmentize 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. Since the Catala compiler is not yet published to the opam repository, you can install a local version from this Git repository by using

opam install ./

To uninstall, use

opam unpin catala

Generating website 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

Then, use a helper script to copy them over to the assets directory of the Catala website.

./generate_website_assets.sh <path-to-catala-website>/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.

Syntax highlighting

The Catala language also comes with syntax highlighting to ease program development. The syntax highlighting is done with the Iro compiler that allows writing the syntax only once, and then export it to formats understood by various IDE. Currently, two syntax highlighting plugins are under version control.

Atom

To get Catala syntax highlighting in Atom, simply enter from the root of the repository, depending on the language you want to use :

make atom_fr

or

make atom_en

You can now reload Atom and check that you have syntax highlighting on any .catala file.

VSCode

To get Catala syntax highlighting in VSCode, simply enter from the root of the repository, depending on the language you want to use :

make vscode_fr

or

make vscode_en

You can now reload VSCode and check that you have syntax highlighting on any .catala file.

Pygments

Pygments is a Python-based versatile lexer for various programming languages. To use a version of Pygments augmented with the Catala plugin, simply enter

sudo make pygments

This will execute the script syntax_highlighting/fr/pygments/set_up_pygments.sh, syntax_highlighting/pl/pygments/set_up_pygments.sh and syntax_highlighting/en/pygments/set_up_pygments.sh.

The scripts patch your pigmentize executable, used for instance by the minted LaTeX package. It will now point to the Catala-enabled version with the appropriate catala_* lexer.