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 download one of our release tarballs.

Note:

  Cyrus does not support compiling with Link Time Optimization, but
  some platforms now enable Link Time Optimization by default. If your
  platform does so, you will need to override it, perhaps by adding
  "-fno-lto" to "CFLAGS" and "LDFLAGS".


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-imapd.

+---------------------------+---------------------------+---------------------------+---------------------------+
| Package                   | Debian                    | RedHat                    | Notes                     |
|===========================|===========================|===========================|===========================|
| 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              | version 55 or newer       |
+---------------------------+---------------------------+---------------------------+---------------------------+
| uuid                      | uuid-dev                  | libuuid-devel             |                           |
+---------------------------+---------------------------+---------------------------+---------------------------+
| openssl (Note about       | libssl-dev                | openssl-devel             |                           |
| versions)                 |                           |                           |                           |
+---------------------------+---------------------------+---------------------------+---------------------------+
| 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 libpcre2-dev uuid-dev \
       libicu-dev
   sudo apt-get -t jessie-backports install libxapian-dev


Build dependencies for additional functionality
-----------------------------------------------

The following dependencies enable additional functionality, help with
code maintenance tasks or are required for building the documentation.


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

The developer dependencies are required if you are building from git
sources, have modified certain source files from the release tarball,
or have configured with "--enable-maintainer-mode" in order to build a
new package.

If you are building normally from a pure release tarball, then you
don't need these dependencies. The files, these dependencies produce,
have been pre-built and included in the release, and do not normally
need to be re-built.

+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| Package              | Debian          | RedHat          | Requ  | Notes                                         |
|                      |                 |                 | ired  |                                               |
|======================|=================|=================|=======|===============================================|
| perl-devel           | perl-dev        | perl-devel      | no    | Needed for building binary perl libraries,    |
|                      |                 |                 |       | version 5+.                                   |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| perl(ExtUtils::Make  |                 |                 | no    | Needed for building extensions to Perl.       |
| Maker)               |                 |                 |       |                                               |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| perl(Pod::POM::View  |                 |                 | no    | Needed to generate man pages. This has to be  |
| ::Restructured)      |                 |                 |       | available to the system- wide perl            |
|                      |                 |                 |       | interpreter, found by "which".                |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| python(GitPython)    | python3-git     |                 | no    | Needed for building the documentation.        |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| python(sphinx_rtd_t  | python3-sphinx- |                 | no    | Needed for building the documentation.        |
| heme)                | rtd-theme       |                 |       |                                               |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| python(Sphinx)       | python3-sphinx  |                 | no    | Needed for building the documentation.        |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| transfig             | transfig        | transfig        | no    | Also known as fig2dev, transfig is an         |
|                      |                 |                 |       | artifact from the old days, and is only used  |
|                      |                 |                 |       | for generation of a couple of png files in    |
|                      |                 |                 |       | the legacy documentation                      |
|                      |                 |                 |       | (doc/legacy/murder.png and                    |
|                      |                 |                 |       | doc/legacy/netnews.png). One day it should be |
|                      |                 |                 |       | merged into the current documentation, cause  |
|                      |                 |                 |       | then we can get rid of it: issues/1769.       |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| valgrind             | valgrind        | valgrind        | no    | Performance and memory testing.               |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+


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

+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| Package              | Debian          | RedHat          | Requ  | Notes                                         |
|                      |                 |                 | ired  |                                               |
|======================|=================|=================|=======|===============================================|
| Cyrus SASL Plain     | libsasl2-modul  | cyrus-sasl-     | yes/  | Required to pass Cyrus IMAP's PLAIN           |
|                      | es              | plain           | no    | 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, also |
|                      | gssapi-mit      |                 |       | known as the authentication mechanism         |
|                      |                 |                 |       | *GSSAPI*. Configure option: "--with-          |
|                      |                 |                 |       | gss_impl=mit".                                |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+


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

+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| Package              | Debian          | RedHat          | Requ  | Notes                                         |
|                      |                 |                 | ired  |                                               |
|======================|=================|=================|=======|===============================================|
| mysql or mariadb     | libmysqlclient- | mysql-devel or  | yes/  | MariaDB or MySQL development headers,         |
|                      | dev or          | mariadb-devel   | no    | required to allow Cyrus IMAP to use it as the |
|                      | libmariadb-dev  |                 |       | backend for its databases. Configure options: |
|                      |                 |                 |       | "--with- mysql", "--with-mysql-incdir", "--   |
|                      |                 |                 |       | with-mysql-libdir".                           |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| postgresql           | postgresql-dev  | postgresql-     | yes/  | PostgreSQL development headers, required to   |
|                      |                 | devel           | no    | allow Cyrus IMAP to use it as the backend for |
|                      |                 |                 |       | its databases. Configure option: "--with-     |
|                      |                 |                 |       | pgsql".                                       |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+


CalDAV, CardDAV, or JMAP (httpd subsystem)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| Package              | Debian          | RedHat          | Requ  | Notes                                         |
|                      |                 |                 | ired  |                                               |
|======================|=================|=================|=======|===============================================|
| libbrotli            | libbrotli-dev   | brotli-devel    | no    | It provides Brotli compression support for    |
|                      |                 |                 |       | http communications (otherwise only "deflate" |
|                      |                 |                 |       | and "gzip" (optionally) would be available).  |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| libchardet           | libchardet-dev  | libchardet-     | yes/  | It is used by the **JMAP** module of httpd to |
|                      |                 | devel           | no    | detect the character set of untagged 8-bit    |
|                      |                 |                 |       | headers. Without it, cyrus-imapd will not do  |
|                      |                 |                 |       | character-set detection. If some piece of     |
|                      |                 |                 |       | data has no character set coming in, it will  |
|                      |                 |                 |       | have no character set. Required for JMAP, but |
|                      |                 |                 |       | otherwise is not needed.                      |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| libical              | libical-dev     | libical-devel   | yes   | It provides calendaring functionality for     |
|                      |                 |                 |       | CalDAV, which can't be used without this lib. |
|                      |                 |                 |       | Version 3.0.10 or higher is required.         |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| libxml               | libxml2-dev     | libxml2-devel   | yes   | A fundamental lib for all *DAV functionality. |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| nghttp2              | libnghttp2-dev  | libnghttp2-dev  | no    | HTTP/2 support for the entire **httpd**       |
|                      |                 | el              |       | subsystem (*DAV & JMAP).                      |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| shapelib             | libshp-dev      | shapelib        | yes/  | It is required for **tzdist** service to have |
|                      |                 |                 | no    | geolocation support. Otherwise it is not      |
|                      |                 |                 |       | needed. Version 1.3.0 or higher is required   |
|                      |                 |                 |       | when using it.                                |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| wslay                | libwslay-dev    | wslay-devel     | no    | It provides WebSockets support in httpd. Only |
|                      |                 |                 |       | used with **JMAP**, otherwise not needed.     |
|                      |                 |                 |       | Version 1.1.1 or higher is required when      |
|                      |                 |                 |       | using it.                                     |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| xxd                  | xxd             | vim-common      | yes   | Needed for the _js.h files, for CalDAV and    |
|                      |                 |                 |       | CardDAV support.                              |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| zlib                 | zlib1g-dev      | zlib-devel      | no    | It provides gzip compression support for http |
|                      |                 |                 |       | communications.                               |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+


Other
~~~~~

+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| Package              | Debian          | RedHat          | Requ  | Notes                                         |
|                      |                 |                 | ired  |                                               |
|======================|=================|=================|=======|===============================================|
| CUnit                | libcunit1-dev   | cunit-devel     | no    | Development headers for compiling Cyrus       |
|                      |                 |                 |       | IMAP's unit tests. Required to run "make      |
|                      |                 |                 |       | check".                                       |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| SSL certificates     | ssl-cert-dev    | mod_ssl         | no    | Used if you're installing SSL certificates.   |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| ClamAV               | libclamav-dev   | clamav-devel    | no    | It is used by **cyr_virusscan**, otherwise    |
|                      |                 |                 |       | not needed.                                   |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| CLD2                 | libcld2-dev     | cld2-devel      | yes/  | Compact Language Detector 2                   |
|                      |                 |                 | no    | (probabilistically detects over 80 languages  |
|                      |                 |                 |       | in Unicode UTF-8 text, either plain text or   |
|                      |                 |                 |       | HTML/XML). Required for **Xapian** ("--       |
|                      |                 |                 |       | enable-xapian"), otherwise not needed.        |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| 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".                        |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| pcre2                | libpcre2-dev    | pcre2-devel     | yes   | PCRE 2 (10.x) - for utf-8/unicode regular     |
|                      |                 |                 |       | expression matching. Could be replaced by     |
|                      |                 |                 |       | something else in the future. See issues/1731 |
|                      |                 |                 |       | for more information.                         |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| perl(Term::ReadLine) |                 |                 | no    | Perl library needed by **cyradm**.            |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+
| libsrs2              | *no package*    | *no package*    | no    | It is used for implementing Sender Rewriting  |
|                      |                 |                 |       | Scheme (SRS) functionality for messages       |
|                      |                 |                 |       | forwarded by sieve scripts. Without it,       |
|                      |                 |                 |       | messages forwarded by sieve scripts will not  |
|                      |                 |                 |       | have this functionality and might have        |
|                      |                 |                 |       | difficulty delivering to SMTP servers that    |
|                      |                 |                 |       | insist on it.                                 |
+----------------------+-----------------+-----------------+-------+-----------------------------------------------+

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, or if you are using jmap.


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, CardDAV, WebDAV, JMAP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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


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.
