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 . -t catala

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

    docker run -it -v $PWD:$PWD -w $PWD --name catala catala bash

### With nix

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

Once [nix is installed](https://nixos.org/manual/nix/stable/#ch-installing-binary),
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](https://opam.ocaml.org/doc/Install.html).

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

    opam switch 4.12.0

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

## Dependencies

Next, install all the OCaml packages that Catala depend on, as well as some
git submodules, with

    make dependencies

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

Other features for generation of files and literate programming also require
the following executables to be present

    man2html virtualenv python3 rsync colordiff pygmentize

please install them if they're not here. On a Debian distribution, this can be
done with

    sudo apt install python3-dev python3-setuptools python3-pygments man2html rsync colordiff
    sudo python3 -m pip install --upgrade pip
    sudo python3 -m pip install virtualenv

On ArchLinux :

    sudo pacman -S python-virtualenv man2html rsync colordiff

## 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 `man2html` 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](https://eeyo.io/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.