catala/INSTALL.md

Installing the Catala compiler

Requirements

The Catala compiler is written using OCaml. To install OCaml on your machine and if you're running Linux ou MacOS, open a terminal and enter :

./install_opam.sh

This will install opam, the OCaml dependency manager and the base OCaml compiler. If you're on Windows, the simplest solution would be to use Cygwin or the Windows Subsystem for Linux. Catala has been tested with OCaml version 4.09.1. You can switch to this version by typing :

opam switch create 4.09.1

or

opam switch 4.09.1

if this version of OCaml is already installed. Next, install all the build dependencies with

make install-dependencies

This should ensure everything is set up for developping 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

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

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

On ArchLinux :

sudo pacman -S python-virtualenv man2html rsync

Installation

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.

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 from this repository's root directory

./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.

Opam package

If you want to install the library as an opam package, use the following command at the root of the repository:

opam install ./

You can then use the compiler with the catala command.

Usage

Use catala --help to get more information about the command line options available.

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

make pygments

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

The scripts set up a virtual environement in syntax_highlighting/fr/pygments/pygments/env or syntax_highlighting/en/pygments/pygments/env, which will contain the modified version of Pygments that has Catala support. If you want to hack something, it is possible to use this virtual environnement directly with

source syntax_highlighting/fr/pygments/pygments/env/bin/activate

or

source syntax_highlighting/en/pygments/pygments/env/bin/activate

The pigmentize executable, used for instance by the minted LaTeX package, will now point to the Catala-enabled version inside the virtual environment. This source setup is not necessary if you use the rules in the Makefile.