Debian Codegraph @

doc/html/_sources/imap/developer/compiling.rst.txt

raw
1 .. _compiling:
2
3 =========
4 Compiling
5 =========
6
7 These instructions are based on Debian 8.0 because it has to be based on
8 something. Other Linux distributions will be similar in the broad ideas but may
9 differ in the specifics. If you already have a preferred distro, use that (we
10 assume you know how to use its package management system). If you don't already
11 have a preferred distro, maybe consider using Debian.
12
13 First make sure you have a :ref:`copy of the source <getcyrus>`. You can either
14 fetch the latest source from git, or download one of our release tarballs.
15
16 .. Note::
17
18 Cyrus does not support compiling with `Link Time Optimization
19 <https://gcc.gnu.org/onlinedocs/gccint/LTO-Overview.html>`_,
20 but some platforms now enable Link Time Optimization by default.
21 If your platform does so, you will need to override it, perhaps
22 by adding ``-fno-lto`` to ``CFLAGS`` and ``LDFLAGS``.
23
24 Setting up dependencies
25 =======================
26
27 Required Build Dependencies
28 ---------------------------
29
30 Building a basic Cyrus that can send and receive email: the minimum libraries
31 required to build a functional cyrus-imapd.
32
33 .. csv-table::
34 :header: "Package", "Debian", "RedHat", "Notes"
35
36 `autoconf`_, "autoconf", "autoconf"
37 `automake`_, "automake", "automake"
38 `bison`_, "bison", "bison"
39 `Cyrus SASL`_, "libsasl2-dev", "cyrus-sasl-devel"
40 `flex`_, flex, flex
41 `gcc`_, gcc, gcc
42 `gperf`_, gperf, gperf
43 `jansson`_, libjansson-dev, jansson-devel
44 `libbsd`_, libbsd-dev, libbsd-devel
45 `libtool`_, libtool, libtool
46 `ICU`_, libicu-dev, libicu-devel, "version 55 or newer"
47 `uuid`_, uuid-dev, libuuid-devel
48 `openssl`_ :ref:`(Note about versions) <openssl-versions>`, libssl-dev, openssl-devel
49 `pkgconfig`_, pkg-config, pkgconfig
50 `sqlite`_, libsqlite3-dev, sqlite-devel
51
52 .. _autoconf: http://www.gnu.org/software/autoconf/
53 .. _automake: http://www.gnu.org/software/automake/
54 .. _bison: http://www.gnu.org/software/bison/
55 .. _Cyrus SASL: :ref:`Cyrus SASL <cyrussasl:sasl-index>`
56 .. _flex: http://flex.sourceforge.net/
57 .. _gcc: http://gcc.gnu.org
58 .. _gperf: http://www.gnu.org/software/gperf/
59 .. _jansson: http://www.digip.org/jansson/
60 .. _libbsd: https://libbsd.freedesktop.org/wiki/
61 .. _libtool: http://www.gnu.org/software/libtool/
62 .. _ICU: http://www.icu-project.org/
63 .. _uuid: https://www.kernel.org/pub/linux/utils/util-linux/
64 .. _openssl: http://www.openssl.org/
65 .. _pkgconfig: http://pkgconfig.freedesktop.org
66 .. _sqlite: https://www.sqlite.org/
67
68 To install all dependencies from packages on Debian Jessie, use this:
69
70 .. include:: /assets/cyrus-build-reqpkg.rst
71
72 Build dependencies for additional functionality
73 -----------------------------------------------
74
75 The following dependencies enable additional functionality, help with
76 code maintenance tasks or are required for building the documentation.
77
78 Developers only
79 ###############
80
81 The developer dependencies are required if you are building from git sources,
82 have modified certain source files from the release tarball, or have configured
83 with ``--enable-maintainer-mode`` in order to build a new package.
84
85 If you are building normally from a pure release tarball, then you don't need
86 these dependencies. The files, these dependencies produce, have been pre-built
87 and included in the release, and do not normally need to be re-built.
88
89 .. csv-table::
90 :header: "Package", "Debian", "RedHat", "Required", "Notes"
91 :widths: 20,15,15,5,45
92
93 `perl-devel`_, perl-dev, perl-devel, "no", "Needed for building binary perl
94 libraries, version 5+."
95 `perl(ExtUtils::MakeMaker)`_,,, "no", "Needed for building extensions to
96 Perl."
97 `perl(Pod::POM::View::Restructured)`_,,, "no", "Needed to generate man
98 pages. This has to be available to the system-wide perl interpreter, found
99 by ``which``."
100 `python(GitPython)`_,python3-git,, "no", "Needed for building the documentation."
101 `python(sphinx_rtd_theme)`_,python3-sphinx-rtd-theme,, "no", "Needed for building the documentation."
102 `python(Sphinx)`_,python3-sphinx,, "no", "Needed for building the documentation."
103 `transfig`_, transfig, transfig, "no", "Also known as fig2dev, transfig is
104 an artifact from the old days, and is only used for generation of a couple
105 of png files in the legacy documentation (doc/legacy/murder.png and
106 doc/legacy/netnews.png). One day it should be merged into the current
107 documentation, cause then we can get rid of it: `issues/1769`_."
108 `valgrind`_, valgrind, valgrind, "no", "Performance and memory testing."
109
110 SASL Authentication
111 ###################
112
113 .. csv-table::
114 :header: "Package", "Debian", "RedHat", "Required", "Notes"
115 :widths: 20,15,15,5,45
116
117 `Cyrus SASL Plain`_, libsasl2-modules, cyrus-sasl-plain, "yes/no", "Required
118 to pass Cyrus IMAP's PLAIN authentication unit tests."
119 `sasl binaries`_, sasl2-bin, sasl2-bin, "no", "Administration tools for
120 managing SASL."
121 `Kerberos`_, libsasl2-modules-gssapi-mit, krb5-devel, "no", "Development
122 headers required to enable Kerberos v5 authentication capabilities, also
123 known as the authentication mechanism *GSSAPI*. Configure option:
124 ``--with-gss_impl=mit``."
125
126 Alternate database formats
127 ##########################
128
129 .. csv-table::
130 :header: "Package", "Debian", "RedHat", "Required", "Notes"
131 :widths: 20,15,15,5,45
132
133 `mysql`_ or `mariadb`_, "libmysqlclient-dev or libmariadb-dev", "mysql-devel
134 or mariadb-devel", "yes/no", "MariaDB or MySQL development headers, required
135 to allow Cyrus IMAP to use it as the backend for its databases. Configure
136 options: ``--with-mysql``, ``--with-mysql-incdir``,
137 ``--with-mysql-libdir``."
138 `postgresql`_, postgresql-dev, postgresql-devel, "yes/no", "PostgreSQL
139 development headers, required to allow Cyrus IMAP to use it as the backend
140 for its databases. Configure option: ``--with-pgsql``."
141
142 CalDAV, CardDAV, or JMAP (httpd subsystem)
143 ##########################################
144
145 .. csv-table::
146 :header: "Package", "Debian", "RedHat", "Required", "Notes"
147 :widths: 20,15,15,5,45
148
149 `libbrotli`_, libbrotli-dev, brotli-devel, "no", "It provides Brotli
150 compression support for http communications (otherwise only ``deflate`` and
151 ``gzip`` (optionally) would be available)."
152 `libchardet`_, libchardet-dev, libchardet-devel, "yes/no", "It is used
153 by the **JMAP** module of httpd to detect the character set of untagged
154 8-bit headers. Without it, cyrus-imapd will not do character-set detection.
155 If some piece of data has no character set coming in, it will have no
156 character set. Required for JMAP, but otherwise is not needed."
157 `libical`_, libical-dev, libical-devel, "yes", "It provides
158 calendaring functionality for CalDAV, which can't be used without this lib.
159 Version 3.0.10 or higher is required."
160 `libxml`_, libxml2-dev, libxml2-devel, "yes", "A fundamental lib for
161 all \*DAV functionality."
162 `nghttp2`_, libnghttp2-dev, libnghttp2-devel, "no", "HTTP/2 support
163 for the entire **httpd** subsystem (\*DAV & JMAP)."
164 `shapelib`_, libshp-dev, shapelib, "yes/no", "It is required for
165 **tzdist** service to have geolocation support. Otherwise it is not needed.
166 Version 1.3.0 or higher is required when using it."
167 `wslay`_, libwslay-dev, wslay-devel, "no", "It provides WebSockets support
168 in httpd. Only used with **JMAP**, otherwise not needed. Version 1.1.1 or
169 higher is required when using it."
170 `xxd`_, xxd, vim-common, "yes", "Needed for the _js.h files, for CalDAV
171 and CardDAV support."
172 `zlib`_, zlib1g-dev, zlib-devel, "no", "It provides gzip compression
173 support for http communications."
174
175 Other
176 #####
177
178 .. csv-table::
179 :header: "Package", "Debian", "RedHat", "Required", "Notes"
180 :widths: 20,15,15,5,45
181
182 `CUnit`_, libcunit1-dev, cunit-devel, "no", "Development headers for
183 compiling Cyrus IMAP's unit tests. Required to run ``make check``."
184 SSL certificates, ssl-cert-dev, mod_ssl, "no", "Used if you're
185 installing SSL certificates."
186 `ClamAV`_, libclamav-dev, clamav-devel, "no", "It is used by
187 **cyr_virusscan**, otherwise not needed."
188 `CLD2`_, libcld2-dev, cld2-devel, "yes/no", "Compact Language Detector 2
189 (probabilistically detects over 80 languages in Unicode UTF-8 text, either
190 plain text or HTML/XML). Required for **Xapian** (``--enable-xapian``),
191 otherwise not needed."
192 `openldap`_, libldap2-dev, openldap-devel, "no", "Development headers
193 to enable **ptloader** to interface with LDAP directly, for canonification
194 of login usernames to mailbox names, and verification of login usernames,
195 ACL subjects and group membership. Configure option: ``--with-ldap``."
196 `pcre2`_, libpcre2-dev, pcre2-devel, "yes", "PCRE 2 (10.x) - for utf-8/unicode
197 regular expression matching. Could be replaced by something else in the
198 future. See `issues/1731`_ for more information."
199 `perl(Term::ReadLine)`_,,, "no", "Perl library needed by **cyradm**."
200 `libsrs2`_, *no package*, *no package*, "no", "It is used for
201 implementing Sender Rewriting Scheme (SRS) functionality for messages
202 forwarded by sieve scripts. Without it, messages forwarded by sieve scripts
203 will not have this functionality and might have difficulty delivering to
204 SMTP servers that insist on it."
205
206 .. _ClamAV: https://www.clamav.net/
207 .. _CUnit: http://cunit.sourceforge.net/
208 .. _Cyrus SASL Plain: :ref:`Cyrus SASL <cyrussasl:sasl-index>`
209 .. _Cyrus SASL MD5: :ref:`Cyrus SASL <cyrussasl:sasl-index>`
210 .. _sasl binaries: :ref:`Cyrus SASL <cyrussasl:sasl-index>`
211 .. _Kerberos: http://web.mit.edu/kerberos/www/
212 .. _libbrotli: https://github.com/google/brotli
213 .. _libchardet: https://github.com/Joungkyun/libchardet
214 .. _libical: https://github.com/libical/libical/
215 .. _libxml: http://xmlsoft.org/
216 .. _mysql: http://www.mysql.com
217 .. _mariadb: http://mariadb.org
218 .. _nghttp2: https://nghttp2.org/
219 .. _openldap: http://www.openldap.org/
220 .. _pcre: http://www.pcre.org/
221 .. _pcre2: http://www.pcre.org/
222 .. _perl(Term::ReadLine): https://metacpan.org/pod/Term::ReadLine
223 .. _perl(ExtUtils::MakeMaker): http://search.cpan.org/dist/ExtUtils-MakeMaker/
224 .. _perl(Pod::POM::View::Restructured): https://metacpan.org/pod/Pod::POM::View::Restructured
225 .. _perl-devel: http://www.perl.org/
226 .. _postgresql: http://www.postgresql.org/
227 .. _python(GitPython): https://github.com/gitpython-developers/GitPython
228 .. _python(sphinx_rtd_theme): https://github.com/readthedocs/sphinx_rtd_theme
229 .. _python(Sphinx): https://www.sphinx-doc.org/
230 .. _shapelib: http://shapelib.maptools.org
231 .. _libsrs2: https://www.libsrs2.org/
232 .. _transfig: http://www.xfig.org/
233 .. _valgrind: http://www.valgrind.org/
234 .. _wslay: https://tatsuhiro-t.github.io/wslay/
235 .. _zlib: http://zlib.net/
236 .. _xxd: https://github.com/ConorOG/xxd/
237 .. _CLD2: https://github.com/CLD2Owners/cld2
238 .. _issues/1769: https://github.com/cyrusimap/cyrus-imapd/issues/1769
239 .. _issues/1731: https://github.com/cyrusimap/cyrus-imapd/issues/1731#issuecomment-273064554
240
241
242 Install tools for building
243 * ``sudo apt-get install build-essential``
244
245
246 Optionally install dependencies for :ref:`building the docs <contribute-docs>`.
247 * ``sudo pip install python-sphinx``
248 * ``sudo cpan install Pod::POM::View::Restructured``
249
250
251 Compile Cyrus
252 =============
253
254 There are additional :ref:`compile and installation steps<imapinstall-xapian>`
255 if you are using Xapian for searching, or if you are :ref:`using jmap
256 <developer-jmap>`.
257
258 Default build: mail only
259 ------------------------
260
261 .. parsed-literal::
262
263 $ :command:`autoreconf -i`
264 $ :command:`./configure` [options]
265
266 Check the summary after ``./configure`` completes to ensure it
267 matches your expectations.
268
269 To view all options, and disable or enable specific features,
270 please see:
271
272 .. parsed-literal::
273
274 # :command:`./configure --help`
275
276 .. tip::
277 Passing environment variables as an argument to configure, rather than
278 setting them in the environment before running configure, allows their
279 values to be logged in config.log. This is useful for diagnosing problems.
280
281 Optional dependencies
282 ---------------------
283
284 Some features are disabled by default and must be explicitly enabled
285 via configure.
286
287 Sieve is enabled by default.
288
289 CalDAV, CardDAV, WebDAV, JMAP
290 #############################
291
292 ``./configure --enable-http --enable-calalarmd --enable-jmap``
293
294 Murder
295 ######
296
297 ``./configure --enable-murder``
298
299 Replication
300 ###########
301
302 ``./configure --enable-replication``
303
304 Compile
305 -------
306
307 .. code-block:: bash
308
309 cd /path/to/cyrus-imapd
310
311 autoreconf -i -s # generates a configure script, and its various dependencies
312
313 ./configure CFLAGS="-W -Wno-unused-parameter -g -O0 -Wall -Wextra -Werror -fPIC" \
314 --enable-coverage --enable-calalarmd --enable-autocreate \
315 --enable-nntp --enable-http --enable-unit-tests \
316 --enable-replication --with-openssl=yes --enable-murder \
317 --enable-idled --prefix=/usr/cyrus
318
319 make lex-fix # you need this if compile fails with errors from sieve/sieve.c
320
321 make
322
323 The ``--prefix`` option sets where Cyrus is installed to.
324
325 It may be of use to also add ``--std=gnu99`` to the ``CFLAGS``. That generates
326 TONS of warnings.
327
328 Having problems with :ref:`compilation <compilationerrors>` or
329 :ref:`linking <linker-warnings>`?
330
331 If you're running on Debian, and you install to ``/usr/local``, you may need to
332 update your library loader. Edit ``/etc/ld.so.conf.d/x86_64-linux-gnu.conf`` so
333 it includes the following additional line::
334
335 /usr/local/lib/x86_64-linux-gnu
336
337 Without this, when you attempt to start Cyrus, it reports ``error while loading
338 shared libraries: libcyrus_imap.so.0: cannot open shared object file: No such
339 file or directory`` because it can't find the Cyrus library in /usr/local/lib.
340
341 Check
342 -----
343
344 .. code-block:: bash
345
346 make check # this runs the cunit tests.
347
348 This runs the cunit tests and is used for testing that the libraries support
349 all the expected behaviour. If this fails, please :ref:`report it to the
350 cyrus-dev mailing list <feedback-mailing-lists>` with details of your source
351 version, operating system and affected libraries.
352
353
354 Next: :ref:`installing Cyrus <installing>`.
355
356 .. _Fastmail : https://www.fastmail.com