mirror of
https://github.com/CatalaLang/catala.git
synced 2024-09-19 00:15:39 +03:00
155 lines
4.9 KiB
Markdown
155 lines
4.9 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 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`.
|
|
|
|
|
|
### 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](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.
|
|
|
|
|
|
## 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, run
|
|
|
|
make website-assets.tar
|
|
|
|
Then, get the base [`catala-web-assets`](https://github.com/CatalaLang/catala-web-assets)
|
|
repository, and untar the generated file within the `assets/` subdirectory:
|
|
|
|
tar xf website-assets.tar -C <path-to-catala-web-assets>/assets
|
|
|
|
> You will need the `groff` executable to generate the HTML versions of the man
|
|
pages.
|
|
|
|
## Syntax highlighting
|
|
|
|
See the [dedicated `README.md`](./syntax_highlighting/README.md).
|