mirror of
https://github.com/CatalaLang/catala.git
synced 2024-11-09 22:16:10 +03:00
f1e44619e0
This leverages the embedded lexer already used for HTML output, and uses the LaTeX pygments backend to colorise code directly, without the need for `minted`.
138 lines
4.4 KiB
Markdown
138 lines
4.4 KiB
Markdown
# 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 . --target dev-build-context -t catala
|
|
|
|
Finally, start a shell inside a new container created from the newly built image:
|
|
|
|
docker run -it --name catala catala
|
|
|
|
### 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.13.0. To switch to OCaml 4.13.0.,
|
|
just use:
|
|
|
|
opam switch 4.13.0
|
|
|
|
If you get a `No switch 4.13.0 is currently installed` error message, follow
|
|
the hint and enter `opam switch create 4.13.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`). The Makefile rules will use it automatically when building the syntax
|
|
cheat-sheet, for example, but if you need to otherwise colorise Catala code, or
|
|
use generated Python code, 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
|
|
|
|
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 website.
|
|
|
|
./generate_website_assets.sh <path-to-catala-website>/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.
|
|
|
|
## Syntax highlighting
|
|
|
|
See the [dedicated `README.md`](./syntax_highlighting/README.md).
|