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