summaryrefslogtreecommitdiff
path: root/INSTALL.md
diff options
context:
space:
mode:
Diffstat (limited to 'INSTALL.md')
-rw-r--r--INSTALL.md156
1 files changed, 156 insertions, 0 deletions
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..7709fe9
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,156 @@
+tl;dr
+=====
+
+ cmake . && make && ./biboumi
+
+If that didn’t work, read on.
+
+Dependencies
+============
+
+Build and runtime dependencies:
+
+Tools:
+
+- A C++14 compiler (clang >= 3.4 or gcc >= 4.9 for example)
+- CMake
+- ronn (optional) to build the man page
+
+Libraries:
+
+- expat
+ Used to parse XML from the XMPP server.
+ http://expat.sourceforge.net/
+
+- libiconv
+ Encoding from anything into UTF-8
+ http://www.gnu.org/software/libiconv/
+
+- libuuid
+ Generate unique IDs
+ http://sourceforge.net/projects/libuuid/
+
+- libidn (optional, but recommended)
+ Provides the stringprep functionality. Without it, JIDs for IRC users are
+ not provided.
+ http://www.gnu.org/software/libidn/
+
+- c-ares (optional, but recommended)
+ Asynchronously resolve domain names. This offers better reactivity and
+ performances when connecting to a big number of IRC servers at the same
+ time.
+ http://c-ares.haxx.se/
+
+- libbotan 1.11 (optional)
+ Provides TLS support. Without it, IRC connections are all made in
+ plain-text mode.
+ Other branches than the 1.11 are not supported.
+ http://botan.randombit.net/
+
+- litesql (optional)
+ Provides a way to store various options in a (sqlite3) database. Each user
+ of the gateway can store their own values (for example their prefered port,
+ or their IRC password).
+ http://git.louiz.org/litesql
+
+- systemd (optional)
+ Provides the support for a systemd service of Type=notify. This is useful only
+ if you are packaging biboumi in a distribution with Systemd.
+
+
+Configure
+=========
+
+Configure the build system using cmake, there are many solutions to do that,
+the simplest is to just run
+
+ cmake .
+
+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:
+
+ cmake . -DCMAKE_BUILD_TYPE=release -DCMAKE_INSTALL_PREFIX=/usr
+
+You can also configure many parameters of the build (like customize CFLAGS,
+the install path, choose the compiler, or enabling some options like the
+POLLER to use), using the ncurses interface of ccmake:
+
+ ccmake .
+
+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.
+
+You can also configure these options using a -D command line flag.
+
+The list of available options:
+
+- POLLER: lets you select the poller used by biboumi, at
+ compile-time. Possible values are:
+ 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.
+
+- WITH_BOTAN and WITHOUT_BOTAN: The first force the usage of the Botan library,
+ 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.
+
+- WITH_LIBIDN and WITHOUT_LIBIDN: Just like the WITH(OUT)_BOTAN options, but
+ for the IDN library
+
+- WITH_SYSTEMD and WITHOUT_SYSTEMD: Just like the other WITH(OUT)_* options,
+ but for the Systemd library
+
+Example:
+
+ cmake . -DCMAKE_BUILD_TYPE=release -DCMAKE_INSTALL_PREFIX \
+ -DWITH_BOTAN=1 -DWITHOUT_SYSTEMD=1
+
+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).
+
+
+Build
+=====
+
+- Once you’ve configured everything using cmake, build the project
+
+ make
+
+
+Install
+=======
+
+- And then, optionaly, Install the software system-wide
+
+ make install
+
+
+Testing
+=======
+
+You can run the test suite with
+
+ make check
+
+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
+
+ make coverage
+
+This requires gcov and lcov to be installed.
+
+
+Run
+===
+
+Run the software using the `biboumi` binary. Read the documentation (the
+man page biboumi(1) or the `biboumi.1.md` file) for more information on how
+to use biboumi.