catala/INSTALL.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

155 lines
4.9 KiB
Markdown
Raw Normal View History

2020-12-14 12:59:15 +03:00
# Building and installing the Catala language
2020-06-02 11:26:30 +03:00
> 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.
2020-06-02 11:26:30 +03:00
## Requirements
2021-09-27 22:06:14 +03:00
### 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:
2021-09-27 22:06:14 +03:00
docker build . -t catala
2021-09-27 22:06:14 +03:00
(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:
2021-09-27 22:06:14 +03:00
2022-07-20 13:00:02 +03:00
docker run -it --name catala catala
2021-09-27 22:06:14 +03:00
The generated binaries will be in `~/catala/_build/install/default`. Get started
by running:
./_build/install/default/bin/catala --help
2023-12-05 15:44:01 +03:00
### 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),
2023-01-19 19:31:45 +03:00
with flakes enabled it is possible to enter a development shell:
2023-01-19 19:31:45 +03:00
nix develop
or to build the Catala compiler, documentation and runtime library:
2023-01-19 19:31:45 +03:00
nix build
2023-01-19 19:31:45 +03:00
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.
2023-01-19 19:31:45 +03:00
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.
2020-12-14 12:59:15 +03:00
2021-09-27 22:06:14 +03:00
## Dependencies
2022-07-20 13:00:02 +03:00
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
2020-06-02 11:26:30 +03:00
2020-12-21 20:15:53 +03:00
make dependencies
2020-06-02 11:26:30 +03:00
2021-05-22 23:55:41 +03:00
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:
2020-06-02 11:26:30 +03:00
. _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
2022-07-20 13:00:02 +03:00
instead execute `make dependencies-with-z3` prior to building the compiler.
2022-02-02 13:37:45 +03:00
Other features of the Catala repository also require the following executables
2022-07-20 13:00:02 +03:00
to be present. On debian, arch or apline-based distributions, the above command
should already take care of them.
2020-06-02 11:26:30 +03:00
groff python3 pip rsync colordiff nodejs npm
2020-06-02 11:26:30 +03:00
2020-12-14 12:59:15 +03:00
## Build
2020-06-02 11:26:30 +03:00
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.
2020-12-14 12:59:15 +03:00
## 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:
2020-12-14 12:59:15 +03:00
opam install ./
2021-03-02 20:27:39 +03:00
To uninstall, use
opam remove ./
2020-06-02 11:26:30 +03:00
### Generating website assets
#### Updating [`@catala-lang/catala-web-assets`](https://www.npmjs.com/package/@catala-lang/catala-web-assets)
2020-06-02 11:26:30 +03:00
The Catala website features assets generated by the Catala compiler. They are
needed to build the website. To produce them, run
2020-12-14 12:59:15 +03:00
make website-assets.tar
2020-12-14 12:59:15 +03:00
Then, get the base [`catala-web-assets`](https://github.com/CatalaLang/catala-web-assets)
repository, and untar the generated file within the `assets/` subdirectory:
2020-06-02 11:26:30 +03:00
tar xf website-assets.tar -C <path-to-catala-web-assets>/assets
2020-06-02 11:26:30 +03:00
> You will need the `groff` executable to generate the HTML versions of the man
pages.
2020-06-02 11:26:30 +03:00
## Syntax highlighting
2022-09-20 11:50:43 +03:00
See the [dedicated `README.md`](./syntax_highlighting/README.md).