catala/INSTALL.md

161 lines
5.3 KiB
Markdown

# Building and installing the Catala language
> Hint: you can find pre-built nightly binaries on [this
> page](https://catalalang.github.io/catala/). 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 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),
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](https://microsoft.github.io/language-server-protocol/), you can use the [ocaml-platform extension](https://marketplace.visualstudio.com/items?itemName=ocamllabs.ocaml-platform) with the following settings (inside the file `.vscode/settings.json`).
```json
{
"ocaml.sandbox": {
"kind": "custom",
"template": "nix develop --command $prog $args"
},
}
```
The nix build is updated weekly by an automatic github action.
### 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.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`.
## 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`](https://www.npmjs.com/package/@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`](https://github.com/CatalaLang/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`](https://www.npmjs.com/package/@catala-lang/french-law)
When a new version of the `french_law.js` (see the [dedicated
README](https://github.com/CatalaLang/catala/tree/master/french_law/js#generating-the-source-files)
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`](./syntax_highlighting/README.md).