INSTALL.md 7.32 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
 * a POSIX system with a C compiler
16
 * on Linux, [Bubblewrap](https://github.com/projectatomic/bubblewrap)
Stephane Glondu's avatar
Stephane Glondu committed
17 18 19 20 21 22
 * [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/)
23
 * [Wget](https://www.gnu.org/software/wget/) or [curl](http://curl.haxx.se/)
24
 * [Zip](http://www.info-zip.org/Zip.html)
25
 * [Unzip](http://www.info-zip.org/UnZip.html)
Stephane Glondu's avatar
Stephane Glondu committed
26 27 28
 * [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/)
29
 * [GD-SecurityImage](https://metacpan.org/release/GD-SecurityImage)
30
 * [cracklib](http://sourceforge.net/projects/cracklib)
Stephane Glondu's avatar
Stephane Glondu committed
31 32 33 34 35

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:

36
    sudo apt install bubblewrap build-essential libgmp-dev libpcre3-dev pkg-config m4 libssl-dev libsqlite3-dev wget ca-certificates zip unzip aspcud libncurses-dev uuid-runtime zlib1g-dev libgd-securityimage-perl cracklib-runtime
Stephane Glondu's avatar
Stephane Glondu committed
37 38 39 40 41

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
42
choose the directory by setting the `BELENIOS_SYSROOT` environment
Stephane Glondu's avatar
Stephane Glondu committed
43
variable, or it will take `~/.belenios` by default. Just run:
44

45
    ./opam-bootstrap.sh
46

47
On a modern desktop system, this needs approximately 20 minutes and 2.6
Stephane Glondu's avatar
Stephane Glondu committed
48
gigabytes of disk space.
49 50 51 52 53 54

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

    make all

55 56
and you can skip the next two sections and go directly to the
_Documentation_ section.
57

58 59 60 61 62 63 64 65
You can also compile a debug version by using the `BELENIOS_DEBUG`
environment variable:

    BELENIOS_DEBUG=1 make all

Note that this version may introduce vulnerabilities and should not be
used in production!

66 67 68 69
To make sure everything went well, you can run tests:

    make check

Stephane Glondu's avatar
Stephane Glondu committed
70 71 72 73
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.

74 75 76 77 78 79 80 81 82 83 84 85
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/)
 * [Uuidm](http://erratique.ch/software/uuidm)
 * [Cryptokit](https://forge.ocamlcore.org/projects/cryptokit/)
 * [Atdgen](http://mjambon.com/atdgen)
 * [Yojson](http://mjambon.com/yojson.html)
86
 * [Cmdliner](http://erratique.ch/software/cmdliner)
87

88 89
With OPAM, these dependencies can be installed with the following
command:
90

91
    opam install atdgen zarith cryptokit uuidm cmdliner
92 93 94 95 96 97 98 99 100 101 102 103 104

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

105
The web server has the following additional dependencies:
106

107
 * [Calendar](http://calendar.forge.ocamlcore.org/)
Stephane Glondu's avatar
Stephane Glondu committed
108
 * [Eliom](http://ocsigen.org/eliom/)
109
 * [Csv](https://forge.ocamlcore.org/projects/csv/)
110

111 112
With OPAM, you can install them with:

113
    opam install calendar eliom csv
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136

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:

137
    sudo apt install markdown texlive-latex-extra texlive-fonts-recommended texlive-fonts-extra lmodern
138 139 140 141 142

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

    make doc
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 172 173 174 175
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
176
sources](http://opam.ocaml.org/doc/Install.html#FromSources).
177 178 179
Once OPAM is installed, follow the instructions in the _Command-line
tool_ section above.

180 181 182
Troubleshooting
---------------

183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207
### 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
208

Stephane Glondu's avatar
Stephane Glondu committed
209 210 211 212 213 214 215 216 217 218 219
### 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
220 221 222 223 224 225
### 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.