From b32729fb8a5ff5cdbd6c94ad327a09aa19396389 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?louiz=E2=80=99?= Date: Tue, 8 Mar 2016 20:29:31 +0100 Subject: Convert README, INSTALL etc to markdown --- INSTALL | 163 ------------------------------------------- INSTALL.md | 156 +++++++++++++++++++++++++++++++++++++++++ README | 60 ---------------- README.md | 61 ++++++++++++++++ packaging/biboumi.spec.cmake | 2 +- 5 files changed, 218 insertions(+), 224 deletions(-) delete mode 100644 INSTALL create mode 100644 INSTALL.md delete mode 100644 README create mode 100644 README.md diff --git a/INSTALL b/INSTALL deleted file mode 100644 index dc0548b..0000000 --- a/INSTALL +++ /dev/null @@ -1,163 +0,0 @@ -============== - 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. 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. diff --git a/README b/README deleted file mode 100644 index 015ada7..0000000 --- a/README +++ /dev/null @@ -1,60 +0,0 @@ - _ _ _ _ -| |__ (_) |__ ___ _ _ _ __ ___ (_) -| '_ \| | '_ \ / _ \| | | | '_ ` _ \| | -| |_) | | |_) | (_) | |_| | | | | | | | -|_.__/|_|_.__/ \___/ \__,_|_| |_| |_|_| - -Homepage: http://biboumi.louiz.org - -Biboumi is an XMPP gateway that connects to IRC servers and translates -between the two protocols. It can be used to access IRC channels using any -XMPP client as if these channels were XMPP MUCs. - -It is written in modern C++14 and makes great efforts to have as little -dependencies and to be as simple as possible. - -The goal is to provide a way to access most of IRC features using any XMPP -client. It doesn’t however try to provide a complete mapping of the -features of both worlds simply because this is not useful and most probably -impossible. For example all IRC modes are not all translatable into an XMPP -features. Some of them are (like +m (mute) or +o (operator) modes), but -some others are IRC-specific. If IRC is the limiting factor (for example -you cannot have a non-ASCII nickname on IRC) then biboumi doesn’t try to -work around this issue: it just enforces the rules of the IRC server by -telling the user that he/she must choose an ASCII-only nickname. An -important goal is to keep the software (and its code) light and simple. - -================ - Install -================ -Refer to the INSTALL file. - -================ - Authors -================ -Florent Le Coz (louiz’) - -================= - Contact/Support -================= -XMPP ChatRoom: biboumi@muc.poez.io -Report a bug: https://dev.louiz.org/projects/biboumi/issues/new - -To contribute, the preferred way is to commit your changes on some -publicly-available git repository (your own, or github -(https://github.com/louiz/biboumi), or a fork on https://lab.louiz.org) and -to notify the developers with a ticket on the bug tracker -(https://dev.louiz.org/projects/biboumi/issues/new), a pull request on -github or a merge request on gitlab. - -Optionally you can come discuss your changes on the XMPP chat room, -beforehand. - -================= - Licence -================= -Biboumi is Free Software. -(learn more: http://www.gnu.org/philosophy/free-sw.html) - -Biboumi is released under the zlib license. -Please read the COPYING file for details. diff --git a/README.md b/README.md new file mode 100644 index 0000000..b8b5124 --- /dev/null +++ b/README.md @@ -0,0 +1,61 @@ +Biboumi +======= + +Biboumi is an XMPP gateway that connects to IRC servers and translates +between the two protocols. It can be used to access IRC channels using any +XMPP client as if these channels were XMPP MUCs. + +It is written in modern C++14 and makes great efforts to have as little +dependencies and to be as simple as possible. + +The goal is to provide a way to access most of IRC features using any XMPP +client. It doesn’t however try to provide a complete mapping of the +features of both worlds simply because this is not useful and most probably +impossible. For example all IRC modes are not all translatable into an XMPP +features. Some of them are (like +m (mute) or +o (operator) modes), but +some others are IRC-specific. If IRC is the limiting factor (for example +you cannot have a non-ASCII nickname on IRC) then biboumi doesn’t try to +work around this issue: it just enforces the rules of the IRC server by +telling the user that he/she must choose an ASCII-only nickname. An +important goal is to keep the software (and its code) light and simple. + + +Install +======= +Refer to the [INSTALL][] file. + +Usage +===== + +Read [the documentation](doc/biboumi.1.md). + +Authors +======= +Florent Le Coz (louiz’) + + +Contact/Support +=============== +* XMPP ChatRoom: biboumi@muc.poez.io +* Report a bug: https://dev.louiz.org/projects/biboumi/issues/new + +To contribute, the preferred way is to commit your changes on some +publicly-available git repository (your own, or github +(https://github.com/louiz/biboumi), or a fork on https://lab.louiz.org) and +to notify the developers with a ticket on the bug tracker +(https://dev.louiz.org/projects/biboumi/issues/new), a pull request on +github or a merge request on gitlab. + +Optionally you can come discuss your changes on the XMPP chat room, +beforehand. + + +Licence +======= +Biboumi is Free Software. +(learn more: http://www.gnu.org/philosophy/free-sw.html) + +Biboumi is released under the zlib license. +Please read the COPYING file for details. + +[INSTALL]: INSTALL diff --git a/packaging/biboumi.spec.cmake b/packaging/biboumi.spec.cmake index 633a168..08b5c6d 100644 --- a/packaging/biboumi.spec.cmake +++ b/packaging/biboumi.spec.cmake @@ -56,7 +56,7 @@ make check %{?_smp_mflags} %files %{_bindir}/%{name} %{_mandir}/man1/%{name}.1* -%doc README COPYING doc/biboumi.1.md +%doc README.md COPYING doc/biboumi.1.md %{_unitdir}/%{name}.service %config(noreplace) %{biboumi_confdir}/biboumi.cfg -- cgit v1.2.3