
Compiling
*********

These instructions are based on Debian 8.0 because it has to be based
on something. Other Linux distributions will be similar in the broad
ideas but may differ in the specifics. If you already have a preferred
distro, use that (we assume you know how to use its package management
system). If you don't already have a preferred distro, maybe consider
using Debian.

First make sure you have a copy of the source. You can either fetch
the latest source from git, or using one of our release tarballs.


Setting up dependencies
=======================


Required Build Dependencies
---------------------------

Building a basic Cyrus that can send and receive email: the minimum
libraries required to build a functional Cyrus.


Build Dependencies
^^^^^^^^^^^^^^^^^^

+-----------------------------------+-----------------------------------+-----------------------------------+
| Package                           | Debian                            | RedHat                            |
+===================================+===================================+===================================+
| autoconf                          | autoconf                          | autoconf                          |
+-----------------------------------+-----------------------------------+-----------------------------------+
| automake                          | automake                          | automake                          |
+-----------------------------------+-----------------------------------+-----------------------------------+
| bison                             | bison                             | bison                             |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Cyrus SASL                        | libsasl2-dev                      | cyrus-sasl-devel                  |
+-----------------------------------+-----------------------------------+-----------------------------------+
| flex                              | flex                              | flex                              |
+-----------------------------------+-----------------------------------+-----------------------------------+
| gcc                               | gcc                               | gcc                               |
+-----------------------------------+-----------------------------------+-----------------------------------+
| gperf                             | gperf                             | gperf                             |
+-----------------------------------+-----------------------------------+-----------------------------------+
| jansson                           | libjansson-dev                    | jansson-devel                     |
+-----------------------------------+-----------------------------------+-----------------------------------+
| libbsd                            | libbsd-dev                        | libbsd-devel                      |
+-----------------------------------+-----------------------------------+-----------------------------------+
| libtool                           | libtool                           | libtool                           |
+-----------------------------------+-----------------------------------+-----------------------------------+
| ICU                               | libicu-dev                        | libicu-devel                      |
+-----------------------------------+-----------------------------------+-----------------------------------+
| uuid                              | uuid-dev                          | libuuid-devel                     |
+-----------------------------------+-----------------------------------+-----------------------------------+
| openssl (Note about versions)     | libssl-dev                        | openssl-devel                     |
+-----------------------------------+-----------------------------------+-----------------------------------+
| pkgconfig                         | pkg-config                        | pkgconfig                         |
+-----------------------------------+-----------------------------------+-----------------------------------+
| sqlite                            | libsqlite3-dev                    | sqlite-devel                      |
+-----------------------------------+-----------------------------------+-----------------------------------+

To install all dependencies from packages on Debian Jessie, use this:

   sudo apt-get install git build-essential autoconf automake libtool \
       pkg-config bison flex libssl-dev libjansson-dev libxml2-dev \
       libsqlite3-dev libical-dev libsasl2-dev libpcre3-dev uuid-dev \
       libicu-dev
   sudo apt-get -t jessie-backports install libxapian-dev


Optional Build Dependencies
---------------------------

The following build dependencies are optional, and enable
functionality, code maintenance tasks or building the documentation.


Developers only
~~~~~~~~~~~~~~~

+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| Package              | Debian          | RedHat          | Requ  | Notes                                         |
|                      |                 |                 | ired  |                                               |
|                      |                 |                 | for   |                                               |
|                      |                 |                 | "make |                                               |
|                      |                 |                 | chec  |                                               |
|                      |                 |                 | k"?   |                                               |
+======================+=================+=================+=======+===============================================+
| CUnit                | libcunit1-dev   | cunit-devel     | yes   | Development headers for compiling Cyrus       |
|                      |                 |                 |       | IMAP's unit tests.                            |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| perl(ExtUtils::Make  | ??              | ??              | no    | Perl library to assist in building extensions |
| Maker)               |                 |                 |       | to Perl.  Configure option: "--with-perl"     |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| *libdb-dev*          | libdb-dev       | libdb-devel     | no    | The -dev package must match the version of    |
|                      |                 |                 |       | libdb you already have installed (assuming    |
|                      |                 |                 |       | it's probably already installed). On Debian   |
|                      |                 |                 |       | 8.0, "libdb5.3-dev" is needed, but            |
|                      |                 |                 |       | "libdb5.1-dev" on 7.8.                        |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| perl-devel           | perl-dev        | perl-devel      | no    | Perl development headers to allow building    |
|                      |                 |                 |       | binary perl libraries. Needs version 5+.      |
|                      |                 |                 |       | Configure option: "--with-perl"               |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| valgrind             | valgrind        | valgrind        | no    | Performance and memory testing.               |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+


SASL Authentication
~~~~~~~~~~~~~~~~~~~

+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| Package              | Debian          | RedHat          | Requ  | Notes                                         |
|                      |                 |                 | ired  |                                               |
|                      |                 |                 | for   |                                               |
|                      |                 |                 | "make |                                               |
|                      |                 |                 | chec  |                                               |
|                      |                 |                 | k"?   |                                               |
+======================+=================+=================+=======+===============================================+
| Cyrus SASL Plain     | libsasl2-modul  | cyrus-sasl-     | yes   | Cyrus SASL package that ships the library     |
|                      | es              | plain           |       | required to pass Cyrus IMAP's PLAIN           |
|                      |                 |                 |       | authentication unit tests.                    |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| Cyrus SASL MD5       | libsasl2-modul  | cyrus-sasl-md5  | yes   | Cyrus SASL library required to pass Cyrus     |
|                      | es              |                 |       | IMAP's DIGEST-MD5 authentication unit tests   |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| sasl binaries        | sasl2-bin       | sasl2-bin       | no    | Administration tools for managing SASL        |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| Kerberos             | libsasl2        | krb5-devel      | no    | Development headers required to enable        |
|                      | -modules-       |                 |       | Kerberos v5 authentication capabilities.      |
|                      | gssapi-mit      |                 |       | Otherwise also known as the authentication    |
|                      |                 |                 |       | mechanism *GSSAPI*.  Configure option: "--    |
|                      |                 |                 |       | with-krbimpl=mit"                             |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+


Alternate database formats
~~~~~~~~~~~~~~~~~~~~~~~~~~

+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| Package              | Debian          | RedHat          | Requ  | Notes                                         |
|                      |                 |                 | ired  |                                               |
|                      |                 |                 | for   |                                               |
|                      |                 |                 | "make |                                               |
|                      |                 |                 | chec  |                                               |
|                      |                 |                 | k"?   |                                               |
+======================+=================+=================+=======+===============================================+
| lmdb                 | lmdb-dev        | lmdb            | no    | Lightning Memory-Mapped Database Manager      |
|                      |                 |                 |       | (LMDB) backend for Cyrus IMAP databases.      |
|                      |                 |                 |       | LMDB requires database environments to be set |
|                      |                 |                 |       | to a (user-configurable) maximum size. The    |
|                      |                 |                 |       | Cyrus backend uses 512MB as default size.     |
|                      |                 |                 |       | Cyrus installations may override this by      |
|                      |                 |                 |       | setting the environment variable              |
|                      |                 |                 |       | CYRUSDB_LMDB_MAXSIZE. The value of this       |
|                      |                 |                 |       | variable must be an integer, optionally       |
|                      |                 |                 |       | followed (without space) by 'mb' or 'gb' to   |
|                      |                 |                 |       | define the maximum size in bytes, megabytes   |
|                      |                 |                 |       | or gigabytes. The size should be a multiple   |
|                      |                 |                 |       | of the OS page size.                          |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| mysql or mariadb     | libmysqlclient- | mysql-devel or  | no    | MariaDB or MySQL development headers, to      |
|                      | dev or          | mariadb-devel   |       | allow Cyrus IMAP to use it as the backend for |
|                      | libmariadb-dev  |                 |       | its databases.  Configure option: "--with-    |
|                      |                 |                 |       | mysql", "--with-mysql-incdir", "--with-       |
|                      |                 |                 |       | mysql-libdir"                                 |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| postgresql           | postgresql-dev  | postgresql-     | no    |                                               |
|                      |                 | devel           |       |                                               |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+


CalDAV and/or CardDAV
~~~~~~~~~~~~~~~~~~~~~

+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| Package              | Debian          | RedHat          | Requ  | Notes                                         |
|                      |                 |                 | ired  |                                               |
|                      |                 |                 | for   |                                               |
|                      |                 |                 | "make |                                               |
|                      |                 |                 | chec  |                                               |
|                      |                 |                 | k"?   |                                               |
+======================+=================+=================+=======+===============================================+
| libical              | libical-dev     | libical-devel   | no    | libical >= 0.48 required for scheduling       |
|                      |                 |                 |       | support. **Note:** Linux distributions        |
|                      |                 |                 |       | Enterprise Linux 6 and Debian Squeeze are     |
|                      |                 |                 |       | known to ship outdated **libical** packages   |
|                      |                 |                 |       | versions 0.43 and 0.44 respectively. The      |
|                      |                 |                 |       | platforms will not support scheduling.        |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| libxml               | libxml2-dev     | libxml2-devel   |       | no                                            |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+


Other
~~~~~

+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| Package              | Debian          | RedHat          | Requ  | Notes                                         |
|                      |                 |                 | ired  |                                               |
|                      |                 |                 | for   |                                               |
|                      |                 |                 | "make |                                               |
|                      |                 |                 | chec  |                                               |
|                      |                 |                 | k"?   |                                               |
+======================+=================+=================+=======+===============================================+
| SSL certificates     | ssl-cert-dev    | mod_ssl         | no    | Used if you're installing SSL certificates    |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| net-snmp             | libsnmp-dev     | net-snmp-devel  | no    | version 4.2 or higher                         |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| openldap             | libldap2-dev    | openldap-devel  | no    | Development headers to enable **ptloader** to |
|                      |                 |                 |       | interface with LDAP directly, for             |
|                      |                 |                 |       | canonification of login usernames to mailbox  |
|                      |                 |                 |       | names, and verification of login usernames,   |
|                      |                 |                 |       | ACL subjects and group membership.  Configure |
|                      |                 |                 |       | option: "--with-ldap"                         |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| tcp_wrappers         | tcp_wrappers    | xx              | no    |                                               |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| transfig             | transfig        | xx              | no    |                                               |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| zlib                 | zlib1g-dev      | zlib-devel      | no    | Compression support for httpd                 |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| nghttp2              | libnghttp2-dev  | libnghttp2-dev  | no    | HTTP/2 support for httpd                      |
|                      |                 | el              |       |                                               |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+

Install tools for building
   * "sudo apt-get install build-essential"

Optionally install dependencies for building the docs.
   * "sudo pip install python-sphinx"

   * "sudo cpan install Pod::POM::View::Restructured"


Compile Cyrus
=============

There are additional compile and installation steps if you are using
Xapian for searching.


Default build: mail only
------------------------

   $ **autoreconf -i**
   $ **./configure** [options]

Check the summary after "./configure" completes to ensure it matches
your expectations.

To view all options, and disable or enable specific features, please
see:

   # **./configure --help**

Tip: Passing environment variables as an argument to configure,
  rather than setting them in the environment before running
  configure, allows their values to be logged in config.log.  This is
  useful for diagnosing problems.


Optional dependencies
---------------------

Some features are disabled by default and must be explicitly enabled
via configure.

Sieve is enabled by default.


CalDAV and CardDAV
~~~~~~~~~~~~~~~~~~

   "./configure --enable-http --enable-calalarmd"


Murder
~~~~~~

   "`./configure --enable-murder"


Replication
~~~~~~~~~~~

   "`./configure --enable-replication"


Compile
-------

   cd /path/to/cyrus-imapd

   autoreconf -i -s   # generates a configure script, and its various dependencies

   ./configure CFLAGS="-W -Wno-unused-parameter -g -O0 -Wall -Wextra -Werror -fPIC" \
   --enable-coverage --enable-calalarmd --enable-autocreate \
   --enable-nntp --enable-http --enable-unit-tests \
   --enable-replication --with-openssl=yes --enable-murder \
   --enable-idled --prefix=/usr/cyrus

   make lex-fix   # you need this if compile fails with errors from sieve/sieve.c

   make

The "--prefix" option sets where Cyrus is installed to.

It may be of use to also add "--std=gnu99" to the "CFLAGS".  That
generates TONS of warnings.

Having problems with compilation or linking?

If you're running on Debian, and you install to "/usr/local", you may
need to update your library loader. Edit "/etc/ld.so.conf.d/x86_64
-linux-gnu.conf" so it includes the following additional line:

   /usr/local/lib/x86_64-linux-gnu

Without this, when you attempt to start Cyrus, it reports "error while
loading shared libraries: libcyrus_imap.so.0: cannot open shared
object file: No such file or directory" because it can't find the
Cyrus library in /usr/local/lib.


Check
-----

   make check    # this runs the cunit tests.

This runs the cunit tests and is used for testing that the libraries
support all the expected behaviour. If this fails, please report it to
the cyrus-dev mailing list with details of your source version,
operating system and affected libraries.

Next: installing Cyrus.
