{0 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.





{2 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.

{2 Compilation & Running:}

Read the README file provided with the template.

{2 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
]}

{2 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].
