Eliom's Distillery

Project Initialization

eliom-distillery creates projects from templates. To see all available templates, you can use

$ eliom-distillery -list-templates

Template "app" creates a simple client-server application project (Dune-based build system and main service), with build rules generated by ocsigen-dune-rules. The server side of the application is an Eliom module (library <name>). It runs either:

• in your own executable (dune exec <name>), which links Ocsigen Server statically and needs no configuration file: the paths (log directory, command pipe, static files and Ocsipersist database file) are set in app/main/main.ml;
• or with the ocsigenserver command (dune exec -- ocsigenserver -c <name>.conf), which loads it dynamically, as specified in the configuration file <name>.conf.

Alternatively, you might want to use the legacy "basic.ppx" template, with a Makefile-based build system.

To create your project, do:

$ eliom-distillery -name <name> -template app [-target-directory <dir>]

This creates a project named <name> from the "app" template in the directory <dir> or <name> by default. The project name should be a valid name for an OCaml compilation unit.

Compilation & Running

Read the README file provided with the template. For the app template, start by installing the opam packages that the project depends on:

$ opam install --deps-only .

dune build reports the libraries and tools that are missing, but not the packages that Ocsigen Server loads only when it starts, such as the storage backend given in the configuration file.

WebAssembly compilation

The template app builds both a JavaScript and a WebAssembly version of your client program. When WebAssembly is enabled (option <wasm enabled="true"/> of the configuration file, or ~enable_wasm:true for Eliom.App.run), the server detects the capabilities of the browser and sends the appropriate version (see WebAssembly).

Using other templates

If you want to start from a more complete or more specific template, you can get other templates from the internet, such as Ocsigen Start. You can either install these templates into Eliom's own directory (lib/eliom/templates/<name>, this is what their installer generally does), or, if doing so is not practical, you can use the ELIOM_DISTILLERY_PATH environment variable to point to your templates. This environment variable is a colon-separated list of directories containing templates (for example, export ELIOM_DISTILLERY_PATH=/usr/local/lib/mytemplates).

A template's name is the name of its directory: with /usr/local/lib/mytemplates/template1, if you want to create a new project based on template1, you can use

$ eliom-distillery -name example -template template1

Write other templates

You can also write your own templates and install them by using the previously described method.

By default, eliom-distillery copies all files in the template directory. If you want to ignore some files, you can list them in the special file .eliomignore.

For some templates, e.g., the one of Ocsigen Start, some project names are reserved to avoid conflicts. For a new template, you need to list all reserved project names in the special file .eliomreserve.

eliom-distillery also replaces %%%PROJECT_NAME%%% (resp. %%%MODULE_NAME%%%) by the project name (resp. by the project name with the first letter capitalized).

For examples, see pre-defined templates like app, basic.ppx and os (from Ocsigen Start).