INSTALL.md 7.58 KB
Newer Older
1 2 3
Belenios compilation instructions
=================================

4 5 6 7 8 9 10 11 12
The easy way
------------

Belenios is written in OCaml and has some dependencies towards
third-party OCaml libraries. The easiest and most portable way to
compile Belenios from source is to use
[OPAM](http://opam.ocamlpro.com/), which is a package manager for
OCaml projects.

Stephane Glondu's avatar
Stephane Glondu committed
13
The non-OCaml prerequisites are:
14

Stephane Glondu's avatar
Stephane Glondu committed
15 16 17 18 19 20 21
 * a POSIX system with a C compiler
 * [GMP](http://gmplib.org/)
 * [PCRE](http://www.pcre.org/)
 * [pkg-config](http://www.freedesktop.org/wiki/Software/pkg-config/)
 * [m4](https://www.gnu.org/software/m4/)
 * [SQLite3](https://www.sqlite.org/)
 * [OpenSSL](https://www.openssl.org/)
22
 * [Wget](https://www.gnu.org/software/wget/) or [curl](http://curl.haxx.se/)
23
 * [Unzip](http://www.info-zip.org/UnZip.html)
Stephane Glondu's avatar
Stephane Glondu committed
24 25 26
 * [aspcud](http://www.cs.uni-potsdam.de/wv/aspcud/) (optional)
 * [ncurses](http://invisible-island.net/ncurses/)
 * [uuidgen](https://www.kernel.org/pub/linux/utils/util-linux/)
Stephane Glondu's avatar
Stephane Glondu committed
27 28 29 30 31

These libraries and tools are pretty common, and might be directly part
of your operating system. On [Debian](http://www.debian.org/) and its
derivatives, they can be installed with the following command:

Stephane Glondu's avatar
Stephane Glondu committed
32
    apt-get install build-essential libgmp-dev libpcre3-dev pkg-config m4 libssl-dev libsqlite3-dev wget ca-certificates unzip aspcud libncurses-dev uuid-runtime
Stephane Glondu's avatar
Stephane Glondu committed
33 34 35 36 37

If you are unfamiliar with OCaml or OPAM, we provide an
`opam-bootstrap.sh` shell script that creates a whole, hopefully
self-contained, OCaml+OPAM install, and then installs all the
dependencies of Belenios, everything into a single directory. You can
Stephane Glondu's avatar
Stephane Glondu committed
38
choose the directory by setting the `BELENIOS_SYSROOT` environment
Stephane Glondu's avatar
Stephane Glondu committed
39
variable, or it will take `~/.belenios` by default. Just run:
40

41
    ./opam-bootstrap.sh
42 43 44 45 46 47 48 49 50

On a modern desktop system, this needs approximately 10 minutes and 1
gigabyte of disk space.

If everything goes successfully, follow the given instructions to
update your shell environment, then run:

    make all

51 52
and you can skip the next two sections and go directly to the
_Documentation_ section.
53

Stephane Glondu's avatar
Stephane Glondu committed
54 55 56 57
If you are familiar with OCaml, please read the `opam-bootstrap.sh`
shell script, or the following two sections to compile Belenios with
your existing OCaml installation.

58 59 60 61 62 63 64 65 66 67 68 69 70
Command-line tool
-----------------

To compile the command-line tool, you will need:

 * [OCaml](http://caml.inria.fr/)
 * [Findlib](http://projects.camlcity.org/projects/findlib.html)
 * [Zarith](https://forge.ocamlcore.org/projects/zarith/)
 * [Calendar](http://calendar.forge.ocamlcore.org/)
 * [Uuidm](http://erratique.ch/software/uuidm)
 * [Cryptokit](https://forge.ocamlcore.org/projects/cryptokit/)
 * [Atdgen](http://mjambon.com/atdgen)
 * [Yojson](http://mjambon.com/yojson.html)
71
 * [Cmdliner](http://erratique.ch/software/cmdliner)
72

73 74
With OPAM, these dependencies can be installed with the following
command:
75

76
    opam install atdgen zarith cryptokit uuidm calendar cmdliner
77 78 79 80 81 82 83 84 85 86 87 88 89

Once all the dependencies have been installed, the command-line tool
can be compiled with:

    make

It produces a single executable, `belenios-tool`, in the `_build/`
directory. You can install it in your `PATH` (which we will assume in
the guides), or refer to it with a full path.

Web server
----------

90
The web server has the following additional dependencies:
91

Stephane Glondu's avatar
Stephane Glondu committed
92
 * [Eliom](http://ocsigen.org/eliom/)
93
 * [Csv](https://forge.ocamlcore.org/projects/csv/)
94

95 96 97
With OPAM, you can install them with:

    opam install eliom csv
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120

Once all the dependencies have been installed, the Eliom module can be
compiled with:

    make all

It will produce a single Eliom module, `server.cma`, in the
`_build/src/web` directory. See `demo/ocsigenserver.conf.in` for an
ocsigenserver configuration template, and the _Server administrator's
guide_ for more information on how to use it.

Documentation
-------------

To generate HTML files from `.md` ones, you will need:

 * [Markdown](http://daringfireball.net/projects/markdown/)

Additionnaly, you will need LaTeX to compile the specification.

On Debian-based systems, you can install the dependencies needed to
compile the documentation with:

121
    sudo apt-get install markdown texlive
122 123 124 125 126

Once all the dependencies have been installed, the documentation can
be compiled with:

    make doc
127 128 129 130

Compilation using only official Debian packages
-----------------------------------------------

Stephane Glondu's avatar
Stephane Glondu committed
131
At the time of writing (05 Apr 2016), you need the development version
132 133 134 135 136
of Debian (or Ubuntu) to be able to compile Belenios using only
official Debian packages. On Ubuntu, you need to enable the "Universe"
repository. Instead of using OPAM, the dependencies of Belenios can
then be installed with:

137
    sudo apt-get install libatdgen-ocaml-dev libzarith-ocaml-dev libcryptokit-ocaml-dev libuuidm-ocaml-dev libcalendar-ocaml-dev libcmdliner-ocaml-dev
138 139
    sudo apt-get install ocsigenserver eliom libcsv-ocaml-dev

140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171
Compiling on Windows using Cygwin
---------------------------------

Windows is not yet a fully supported platform, but you can compile at
least the command-line tool on Windows + 32-bit
[Cygwin](http://cygwin.com/index.html). You might need the following
packages:

 * curl
 * dos2unix
 * flexdll
 * gcc-core
 * gcc-g++
 * git
 * gmp
 * libgmp-devel
 * libncursesw-devel
 * libpcre-devel
 * libsqlite3-devel
 * m4
 * make
 * ocaml
 * ocaml-base
 * ocaml-camlp4
 * ocaml-compiler-libs
 * openssh
 * patch
 * pkg-config
 * zlib-devel

With these packages installed, you should be able to install OPAM by
following its [installation instructions from
172
sources](http://opam.ocaml.org/doc/Install.html#FromSources).
173 174 175
Once OPAM is installed, follow the instructions in the _Command-line
tool_ section above.

176 177 178
Troubleshooting
---------------

179 180
### OCamlDuce incompatibility

181 182 183 184 185
OCamlDuce is an optional transitive dependency of Belenios, but
Belenios does not use it. If OCamlDuce was installed outside of OPAM
(e.g. via your system package manager), you may face issues. You can
work around them by uninstalling OCamlDuce and restarting the
installation procedure.
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211

### Missing sources

The instructions outlined in this document and in the
`opam-bootstrap.sh` script imply downloading files from third-party
servers. Sometimes, these servers can be down. For example, you can
get:

    =-=-= Installing ocamlnet.3.7.3 =-=-=
    ocamlnet.3.7.3 Downloading http://download.camlcity.org/download/ocamlnet-3.7.3.tar.gz
    [ERROR] http://download.camlcity.org/download/ocamlnet-3.7.3.tar.gz is not available

    ===== ERROR while installing ocamlnet.3.7.3 =====
    Could not get the source for ocamlnet.3.7.3.

This can be worked around with the following steps:

 * source the generated `env.sh` file (you must adapt it if you use an
   incompatible shell such as tcsh);
 * download the file from an alternate source (for example
   [Debian source packages](http://www.debian.org/distrib/packages));
 * run `opam pin <package-name> <path-to-file-download-above>` (in the
   example above, `<package-name>` would be `ocamlnet`);
 * resume the installation by running again the `opam install` command
   found in `opam-bootstrap.sh`;
 * follow the instructions given at the end of `opam-bootstrap.sh`.
Stephane Glondu's avatar
Stephane Glondu committed
212

Stephane Glondu's avatar
Stephane Glondu committed
213 214 215 216 217 218 219 220 221 222 223
### Errors while compiling ocsigenserver

If ocsigenserver fails to install because of a SSL-related error:

 * edit `opam-bootstrap.sh` by adding ` ssl=0.5.2` to the `opam
   install` call;
 * run `./opam-bootstrap.sh`.

An alternative could be to install aspcud before running
`opam-bootstrap.sh`.

Stephane Glondu's avatar
Stephane Glondu committed
224 225 226 227 228 229
### Errors while compiling Belenios itself

If you succeeded installing all dependencies, but you get errors while
compiling Belenios, maybe you installed an incompatible version of a
dependency. The `opam-bootstrap.sh` script is tuned to install only
compatible versions; you can have a look at it to get these versions.