1# Install Ulfius
2
3- [Distribution packages](#distribution-packages)
4- [Pre-compiled packages](#pre-compiled-packages)
5- [Manual install](#manual-install)
6  - [Prerequisites](#prerequisites)
7  - [CMake - Multi architecture](#cmake---multi-architecture)
8  - [Good ol' Makefile](#good-ol-makefile)
9
10## Distribution packages
11
12[![Packaging status](https://repology.org/badge/vertical-allrepos/ulfius.svg)](https://repology.org/metapackage/ulfius)
13
14Ulfius is available in multiple distributions as official package. Check out your distribution documentation to install the package automatically.
15
16```shell
17$ # Example for Debian testing, install ulfius library with development files and uwsc
18$ sudo apt install libulfius-dev uwsc
19$ # Example for Debian testing, install uwsc only
20$ sudo apt install uwsc
21```
22
23## Pre-compiled packages
24
25You can install Ulfius with a pre-compiled package available in the [release pages](https://github.com/babelouest/ulfius/releases/latest/). `jansson`, `libmicrohttpd`, `gnutls`, `libcurl-gnutls` and `zlib` development files packages are required to install Ulfius. The packages files `ulfius-dev-full_*` contain the libraries `orcania`, `yder` and `ulfius`.
26
27For example, to install Ulfius with the `ulfius-dev-full_2.7.0_Debian_stretch_x86_64.tar.gz` package downloaded on the `releases` page, you must execute the following commands:
28
29```shell
30$ sudo apt install -y libmicrohttpd-dev libjansson-dev libcurl4-gnutls-dev libgnutls28-dev libgcrypt20-dev libsystemd-dev
31$ wget https://github.com/babelouest/ulfius/releases/download/v2.7.0/ulfius-dev-full_2.7.0_debian_buster_x86_64.tar.gz
32$ tar xf ulfius-dev-full_2.7.0_debian_buster_x86_64.tar.gz
33$ sudo dpkg -i liborcania-dev_2.1.1_Debian_stretch_x86_64.deb
34$ sudo dpkg -i libyder-dev_1.4.12_Debian_stretch_x86_64.deb
35$ sudo dpkg -i libulfius-dev_2.7.0_Debian_stretch_x86_64.deb
36```
37
38If there's no package available for your distribution, you can recompile it manually using `CMake` or `Makefile`.
39
40## Manual install
41
42### Prerequisites
43
44Ulfius requires the following dependencies.
45
46- libmicrohttpd (required), minimum 0.9.53 if you require Websockets support
47- libjansson (optional), minimum 2.4, required for json support
48- libgnutls, libgcrypt (optional), required for Websockets and https support
49- libcurl (optional), required to send http/smtp requests
50- libsystemd (optional), required for [Yder](https://github.com/babelouest/yder) to log messages in journald
51- zlib (optional), required for Websockets support
52
53Note: the build stacks require a compiler (`gcc` or `clang`), `make`, `cmake` (if using CMake build), and `pkg-config`.
54
55For example, to install all the external dependencies on Debian Stretch, run as root:
56
57```shell
58# apt install -y libmicrohttpd-dev libjansson-dev libcurl4-gnutls-dev libgnutls28-dev libgcrypt20-dev zlib1g-dev
59```
60
61### Good ol' Makefile
62
63Download Orcania, Yder and Ulfius source code from GitHub, compile and install Orcania, then Yder, then compile and install Ulfius:
64
65```shell
66$ git clone https://github.com/babelouest/orcania.git
67$ git clone https://github.com/babelouest/yder.git
68$ git clone https://github.com/babelouest/ulfius.git
69$ cd orcania/
70$ make && sudo make install
71$ cd ../yder/
72$ make && sudo make install
73$ cd ../ulfius/
74$ make && sudo make install
75```
76
77#### Disable Ulfius dependencies
78
79To disable libcurl functions, append the option `CURLFLAG=1` to the make command when you build Ulfius:
80
81```shell
82$ make CURLFLAG=1
83```
84
85If libcurl functions are disabled, `libcurl4-gnutls-dev` is no longer mandatory for install.
86
87To disable libjansson functions, append the option `JANSSONFLAG=1` to the make command when you build Ulfius and Orcania:
88
89```shell
90$ make JANSSONFLAG=1
91```
92
93If libjansson functions are disabled, `libjansson-dev` is no longer mandatory for install.
94
95To disable GNU TLS extensions (HTTPS client certificate support) and avoid installing libgnutls, append the option `GNUTLSFLAG=1` to the make command when you build Ulfius:
96
97```shell
98$ make GNUTLSFLAG=1
99```
100
101If GNU TLS extensions are disabled, `libgnutls-dev` is no longer mandatory for install. However, this will also disable websocket support, since it depends on libgnutls.
102
103To disable websocket implementation, append the option `WEBSOCKETFLAG=1` to the make command when you build Ulfius:
104
105```shell
106$ make WEBSOCKETFLAG=1
107```
108
109To disable Yder library (you will no longer have log messages available!), append the option `YDERFLAG=1` to the make command when you build Ulfius:
110
111```shell
112$ make YDERFLAG=1
113```
114
115To disable uwsc build, append the option `UWSCFLAG=1` to the make command when you build Ulfius:
116
117```shell
118$ make UWSCFLAG=1
119```
120
121To disable two or more libraries, append options, example:
122
123```shell
124$ make CURLFLAG=1 JANSSONFLAG=1
125```
126
127#### Install Ulfius as a static archive
128
129Install  Ulfius as a static archive, `libulfius.a`, use the make commands `make static*`:
130
131```shell
132$ cd src
133$ make static && sudo make static-install # or make DESTDIR=/tmp static-install if you want to install in `/tmp/lib`
134```
135
136#### Enable embedded systems flags
137
138To build Ulfius on [FreeRTOS](https://www.freertos.org/), append the option `FREERTOSFLAG=1` to the make command when you build Ulfius:
139
140```shell
141$ make FREERTOSFLAG=1
142```
143
144To build Ulfius with the [LWIP](https://savannah.nongnu.org/projects/lwip/) library, append the option `LWIPFLAG=1` to the make command when you build Ulfius:
145
146```shell
147$ make LWIPFLAG=1
148```
149
150Those two options are exclusive, you can't use them both at the same time.
151
152#### Installation directory
153
154By default, the shared libraries and the header files will be installed in the `/usr/local` location. To change this setting, you can modify the `DESTDIR` value in the `src/Makefile`, `lib/orcania/src/Makefile` and `lib/yder/src/Makefile` files.
155
156```shell
157$ make DESTDIR=/tmp install # to install ulfius in /tmp/lib for example
158```
159
160You can install Ulfius without root permission if your user has write access to `$(DESTDIR)`.
161A `ldconfig` command is executed at the end of the install, it will probably fail if you don't have root permission, but this is harmless.
162If you choose to install Ulfius in another directory, you must set your environment variable `LD_LIBRARY_PATH` properly.
163
164#### Install uwsc
165
166uwsc is a small command-line tool to connect to websocket services. To install uwsc only, you can use the `Makefile` in the `uwsc/` directory:
167
168```shell
169$ cd ulfius/uwsc
170$ make && sudo make install
171```
172
173This will compile and install uwsc in `/usr/local/bin`, to install it in another directory, you can change the value of `DESTDIR`.
174
175### CMake - Multi architecture
176
177You can build Ulfius library using CMake, example:
178
179```shell
180$ mkdir build
181$ cd build
182$ cmake ..
183$ make && sudo make install
184```
185
186The available options for CMake are:
187- `-DWITH_JANSSON=[on|off]` (default `on`): Build with Jansson dependency
188- `-DWITH_CURL=[on|off]` (default `on`): Build with libcurl dependency
189- `-DWITH_GNUTLS=[on|off]` (default `on`): Build with GNU TLS extensions (HTTPS client certificate support), requires GnuTLS library.
190- `-DWITH_WEBSOCKET=[on|off]` (default `on`): Build with websocket functions, not available for Windows, requires libmicrohttpd 0.9.53 minimum.
191- `-DWITH_JOURNALD=[on|off]` (default `on`): Build with journald (SystemD) support for logging
192- `-DWITH_YDER=[on|off]` (default `on`): Build with Yder library for logging messages
193- `-DBUILD_UWSC=[on|off]` (default `on`): Build uwsc
194- `-DBUILD_STATIC=[on|off]` (default `off`): Build the static archive in addition to the shared library
195- `-DBUILD_ULFIUS_TESTING=[on|off]` (default `off`): Build unit tests
196- `-DBUILD_ULFIUS_DOCUMENTATION=[on|off]` (default `off`): Build the documentation, doxygen is required
197- `-DINSTALL_HEADER=[on|off]` (default `on`): Install header file `ulfius.h`
198- `-DBUILD_RPM=[on|off]` (default `off`): Build RPM package when running `make package`
199- `-DCMAKE_BUILD_TYPE=[Debug|Release]` (default `Release`): Compile with debugging symbols or not
200