# Eliom's Distillery

The easiest way to initialize, compile, and run an Ocsigen/Eliom project is to use `eliom-distillery`.

`eliom-distillery` is self-documenting (refer to `eliom-distillery -help` and the generated `README`), but here is a bit of information on how to work with it.

### Project Initialization

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

```shell
$ 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](https://github.com/ocsigen/ocsigen-dune-rules). The server side of the application is an [Eliom module](./configuration.md) (library `<name>`). It runs either:

- in your own executable (`dune exec <name>`), which links Ocsigen Server statically and needs [no configuration file](./configuration.md#no_config_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:

```shell
$ 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:

```shell
$ 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`](./../eliom.server/Eliom-App.md#val-run)), the server detects the capabilities of the browser and sends the appropriate version (see [WebAssembly](./configuration.md#wasm)).

### 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

```shell
$ 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).