README.md

   1 ## Atheme IRC Services
   2
   3 Atheme is a set of IRC services designed for large IRC networks with high
   4 scalability requirements. It is relatively mature software, with some code
   5 and design derived from another package called Shrike.
   6
   7 Atheme's behavior is tunable using modules and a highly detailed
   8 configuration file. Almost all behavior can be changed at deployment time
   9 just by editing the configuration.
  10
  11
  12
  13 ## Obtaining Atheme
  14
  15 If you have a modern version of Git (1.6.5 or newer), you can recursively
  16 clone the repository:
  17
  18     $ git clone --recursive 'https://github.com/atheme/atheme/' atheme-devel
  19     $ cd atheme-devel
  20
  21 If you have an older version of Git, you must clone the repository, and then
  22 fetch its submodules:
  23
  24     $ git clone 'https://github.com/atheme/atheme/' atheme-devel
  25     $ cd atheme-devel
  26     $ git submodule init
  27     $ git submodule update
  28
  29 If you don't have Git, you can download a package archive from our website at
  30 <https://atheme.github.io/>.
  31
  32 If you are browsing our GitHub repository, please do NOT click the "Download
  33 ZIP" button or the "Source code" links there, as they will give you an archive
  34 that lacks the required submodules. There are proper `.tar.bz2` or `.tar.xz`
  35 archives attached to each release under "Assets", which is what the "Download"
  36 button on our website will take you to.
  37
  38
  39
  40 ## Basic build instructions for the impatient
  41
  42 Obtain the source code repository and change into its directory (using the
  43 commands given above).
  44
  45 If you are building Atheme on a GNU/Linux system, or something which can
  46 sufficiently emulate that (like WSL 2 on Windows 10), execute the following
  47 commands:
  48
  49     $ ./configure
  50     $ make
  51     $ make install
  52
  53 If you are building Atheme on an OpenBSD (or similar) system, execute the
  54 following commands instead:
  55
  56     # pkg_add gmake
  57     $ ./configure --disable-linker-defs
  58     $ gmake
  59     $ gmake install
  60
  61
  62
  63 ## Library Detection
  64
  65 If your user-installed libraries that you want Atheme to use are installed by
  66 your package manager to a directory such as `/usr/local/`, you may need to
  67 supplement the default compiler and linker search paths so that Atheme can
  68 detect those libraries (e.g. cracklib from FreeBSD Ports):
  69
  70     $ ./configure CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib"
  71
  72 The following libraries generally require pkg-config to be installed:
  73
  74 - PHC Argon2 Reference Implementation (`libargon2.pc`)
  75 - OpenSSL (`libcrypto.pc`)
  76 - GNU libidn (`libidn.pc`)
  77 - GNU Nettle (`nettle.pc`)
  78 - PCRE (`libpcre.pc`)
  79 - libqrencode (`libqrencode.pc`)
  80 - Sodium (`libsodium.pc`)
  81
  82 If you do not have pkg-config installed and want to use one or more of these
  83 libraries, please see `./configure --help` for the options to set to override
  84 pkg-config discovery for those libraries. For example, if you wish to use GNU
  85 libidn, and it is installed into a default search path for your compiler and
  86 linker, and you do not have pkg-config installed, execute:
  87
  88     $ ./configure LIBIDN_CFLAGS="" LIBIDN_LIBS="-lidn"
  89
  90 If a library relies on populating `LIBFOO_CFLAGS` with some preprocessor
  91 definitions, or populating `LIBFOO_LIBS` with some library linking flags,
  92 this will generally fail. Install pkg-config for the best results.
  93
  94
  95
  96 ## Choice of compiler and its features
  97
  98 If you wish to compile Atheme with the LLVM project's C compiler (`clang`),
  99 you may also wish to use LLVM's linker (`lld`). You can accomplish this as
 100 follows:
 101
 102     $ ./configure CC="clang" LDFLAGS="-fuse-ld=lld"
 103
 104 If you want to use compiler sanitizers, and you want to build with Clang, you
 105 MUST also use LLD, as most of the sanitizers in Clang require LTO to function
 106 properly, and Clang in LTO mode emits LLVM bitcode, not machine code. The
 107 linker is ultimately responsible for performing most of the LTO heavy lifting,
 108 and translating the result into machine code, and most other linkers do not
 109 know how to do this.
 110
 111 To use compiler sanitizers with GCC (supported):
 112
 113     $ ./configure --disable-heap-allocator --disable-linker-defs \
 114         --enable-compiler-sanitizers CC="gcc"
 115
 116 To use compiler sanitizers with Clang (recommended):
 117
 118     $ ./configure --disable-heap-allocator --disable-linker-defs \
 119         --enable-compiler-sanitizers CC="clang" LDFLAGS="-fuse-ld=lld"
 120
 121 If you do enable the sanitizers, it is recommended to enable the configuration
 122 option `general::db_save_blocking`; see the example configuration file for
 123 more details.
 124
 125 The sanitizers are not recommended for production usage, but they are
 126 recommended for developers, including third parties writing new features
 127 and/or modifying the source code.
 128
 129
 130
 131 ## Getting More Help
 132
 133 If you're still lost, read the [INSTALL](INSTALL) file or check out our wiki
 134 for more hints.
 135
 136 - [Our Website](https://atheme.github.io/)
 137 - [Our GitHub Repository](https://github.com/atheme/atheme/)
 138 - [The Atheme Wiki](https://github.com/atheme/atheme/wiki/)
 139 - [The #atheme channel on Libera Chat](ircs://irc.libera.chat:6697/#atheme)