INSTALL.rst 4.54 KB
Newer Older
louiz’'s avatar
louiz’ committed
1 2 3
INSTALL
=======

4
tl;dr
louiz’'s avatar
louiz’ committed
5
-----
6

louiz’'s avatar
louiz’ committed
7
  cmake . && make && ./biboumi
8 9 10

If that didn’t work, read on.

11
Dependencies
louiz’'s avatar
louiz’ committed
12
------------
louiz’'s avatar
louiz’ committed
13 14 15

Build and runtime dependencies:

louiz’'s avatar
louiz’ committed
16
Tools:
louiz’'s avatar
louiz’ committed
17
~~~~~~
louiz’'s avatar
louiz’ committed
18 19 20

- A C++14 compiler (clang >= 3.4 or gcc >= 4.9 for example)
- CMake
21
- pandoc (optional) to build the man page
22

louiz’'s avatar
louiz’ committed
23
Libraries:
louiz’'s avatar
louiz’ committed
24
~~~~~~~~~~
25

louiz’'s avatar
louiz’ committed
26
expat_
louiz’'s avatar
louiz’ committed
27
 Used to parse XML from the XMPP server.
28

louiz’'s avatar
louiz’ committed
29
libiconv_
louiz’'s avatar
louiz’ committed
30 31
 Encoding from anything into UTF-8

louiz’'s avatar
louiz’ committed
32
libuuid_
33 34
 Generate unique IDs

35
sqlite3_ or libpq_
36 37 38 39
 Provides a way to store various options and messages archives in a
 database. Each user of the gateway can store their own values (for
 example their prefered port, or their IRC password). Without this
 dependency, many interesting features are missing.
40

louiz’'s avatar
louiz’ committed
41
libidn_ (optional, but recommended)
42 43 44
 Provides the stringprep functionality. Without it, JIDs for IRC users are
 not provided.

louiz’'s avatar
louiz’ committed
45
udns_ (optional, but recommended)
46 47 48 49
 Asynchronously resolve domain names. This offers better reactivity and
 performances when connecting to a big number of IRC servers at the same
 time.

louiz’'s avatar
louiz’ committed
50
libbotan_ 2.x (optional)
51 52 53
 Provides TLS support. Without it, IRC connections are all made in
 plain-text mode.

54 55 56
gcrypt_ (mandatory only if botan is absent)
 Provides the SHA-1 hash function, for the case where Botan is absent.

louiz’'s avatar
louiz’ committed
57
systemd_ (optional)
58 59
 Provides the support for a systemd service of Type=notify. This is useful only
 if you are packaging biboumi in a distribution with Systemd.
60

louiz’'s avatar
louiz’ committed
61

62
Configure
louiz’'s avatar
louiz’ committed
63
---------
louiz’'s avatar
louiz’ committed
64

65 66
Configure the build system using cmake, there are many solutions to do that,
the simplest is to just run
louiz’'s avatar
louiz’ committed
67

louiz’'s avatar
louiz’ committed
68
  cmake .
louiz’'s avatar
louiz’ committed
69

70 71 72 73 74 75
in the current directory.

The default build type is "Debug", if you want to build a release version,
set the CMAKE_BUILD_TYPE variable to "release", by running this command
instead:

76
    cmake . -DCMAKE_BUILD_TYPE=release -DCMAKE_INSTALL_PREFIX=/usr
louiz’'s avatar
louiz’ committed
77

78 79
You can also configure many parameters of the build (like customize CFLAGS,
the install path, choose the compiler, or enabling some options like the
80
POLLER to use), using the ncurses interface of ccmake:
louiz’'s avatar
louiz’ committed
81

82
    ccmake .
louiz’'s avatar
louiz’ committed
83 84 85 86 87

In ccmake, first use 'c' to configure the build system, edit the values you
need and finaly use 'g' to generate the Makefiles to build the system and
quit ccmake.

88
You can also configure these options using a -D command line flag.
louiz’'s avatar
louiz’ committed
89

90
The list of available options:
louiz’'s avatar
louiz’ committed
91

92 93
- POLLER: lets you select the poller used by biboumi, at
  compile-time. Possible values are:
louiz’'s avatar
louiz’ committed
94 95 96 97

  - EPOLL: use the Linux-specific epoll(7). This is the default on Linux.
  - POLL: use the standard poll(2). This is the default value on all non-Linux
    platforms.
louiz’'s avatar
louiz’ committed
98

99
- WITH_BOTAN and WITHOUT_BOTAN: The first force the usage of the Botan library,
louiz’'s avatar
louiz’ committed
100 101 102 103
  if it is not found, the configuration process will fail. The second will
  make the build process ignore the Botan library, it will not be used even
  if it's available on the system.  If none of these option is specified, the
  library will be used if available and will be ignored otherwise.
104

105
- WITH_LIBIDN and WITHOUT_LIBIDN: Just like the WITH(OUT)_BOTAN options, but
louiz’'s avatar
louiz’ committed
106
  for the IDN library
louiz’'s avatar
louiz’ committed
107

108 109
- WITH_SYSTEMD and WITHOUT_SYSTEMD: Just like the other WITH(OUT)_* options,
  but for the Systemd library
110

111
Example:
112

louiz’'s avatar
louiz’ committed
113 114
  cmake . -DCMAKE_BUILD_TYPE=release -DCMAKE_INSTALL_PREFIX=/usr
  -DWITH_BOTAN=1 -DWITHOUT_SYSTEMD=1
115

116 117
This command will configure the project to build a release, with TLS enabled
(using Botan) but without using Systemd (even if available on the system).
118

louiz’'s avatar
louiz’ committed
119

120
Build
louiz’'s avatar
louiz’ committed
121
-----
122 123 124 125
Once you’ve configured everything using cmake, build the software:

To build the biboumi binary:

louiz’'s avatar
louiz’ committed
126
  make
louiz’'s avatar
louiz’ committed
127 128


129
Install
louiz’'s avatar
louiz’ committed
130 131
-------
And then, optionaly, Install the software system-wide
louiz’'s avatar
louiz’ committed
132

louiz’'s avatar
louiz’ committed
133
  make install
louiz’'s avatar
louiz’ committed
134 135


136
Testing
louiz’'s avatar
louiz’ committed
137
-------
138 139
You can run the test suite with

louiz’'s avatar
louiz’ committed
140
  make check
141 142 143 144 145 146

This project uses the Catch unit test framework, it will be automatically
fetched with cmake, by cloning the github repository.

You can also check the overall code coverage of this test suite by running

louiz’'s avatar
louiz’ committed
147
  make coverage
148 149 150 151

This requires gcov and lcov to be installed.


152
Run
louiz’'s avatar
louiz’ committed
153
---
louiz’'s avatar
louiz’ committed
154
Run the software using the `biboumi` binary.  Read the documentation (the
louiz’'s avatar
louiz’ committed
155
man page biboumi(1) or the `biboumi.1.rst`_ file) for more information on how
louiz’'s avatar
louiz’ committed
156
to use biboumi.
louiz’'s avatar
louiz’ committed
157 158 159 160 161 162

.. _expat: http://expat.sourceforge.net/
.. _libiconv: http://www.gnu.org/software/libiconv/
.. _libuuid: http://sourceforge.net/projects/libuuid/
.. _libidn: http://www.gnu.org/software/libidn/
.. _libbotan: http://botan.randombit.net/
louiz’'s avatar
louiz’ committed
163
.. _udns: http://www.corpit.ru/mjt/udns.html
164
.. _sqlite3: https://sqlite.org
louiz’'s avatar
louiz’ committed
165 166
.. _systemd: https://www.freedesktop.org/wiki/Software/systemd/
.. _biboumi.1.rst: doc/biboumi.1.rst
167
.. _gcrypt: https://www.gnu.org/software/libgcrypt/
louiz’'s avatar
louiz’ committed
168
.. _libpq: https://www.postgresql.org/docs/current/static/libpq.html