# 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 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
```
Templates "app.lib" and "app.exe" create a simple client-server app project (Dune-based build system, configuration file and main service). The first one builds a library that you can dynamically load in ocsigenserver using a configuration file. The second builds a static executable without configuration file.

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.exe [-target-directory <dir>]
```
This creates a project named `<name>` from the `"app.exe"` 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.


### 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 (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 absolute paths (that is, `export ELIOM_DISTILLERY_PATH=/usr/lib/template1:/usr/local/lib/template2`).

A template's name is its directory basename (`template1` and `template2` for the preceding example). 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 previous 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.exe`, `app.lib`, `basic.ppx` and `os.pgocaml`.