build.rst 11.1 KB
Newer Older
1 2
.. _build:

3 4
Building from sources
=====================
Marek Vavruša's avatar
Marek Vavruša committed
5

6 7
.. note:: Latest up-to-date packages for various distribution can be obtained
   from `<https://knot-resolver.cz/download/>`_
Marek Vavruša's avatar
Marek Vavruša committed
8

9
Knot-resolver is written for UNIX-like systems using modern C standards.
10 11 12 13 14
Portable I/O is provided by libuv_.
Some 64-bit systems with LuaJIT 2.1 may be affected by
`a problem <https://github.com/LuaJIT/LuaJIT/blob/v2.1/doc/status.html#L100>`_
-- Linux on x86_64 is unaffected but `Linux on aarch64 is
<https://gitlab.labs.nic.cz/knot/knot-resolver/issues/216>`_.
Marek Vavruša's avatar
Marek Vavruša committed
15

16 17 18
.. code-block:: bash

   $ git clone --recursive https://gitlab.labs.nic.cz/knot/knot-resolver.git
Marek Vavruša's avatar
Marek Vavruša committed
19

20
Dependencies
Marek Vavruša's avatar
Marek Vavruša committed
21 22
------------

23 24 25 26 27
.. warning:: Section *Dependencies* is not up-to-date. Also, individual modules
   might have additional build or runtime dependencies.

The following is a list of dependencies needed to build and run Knot Resolver.

Marek Vavruša's avatar
Marek Vavruša committed
28

Marek Vavruša's avatar
Marek Vavruša committed
29
.. csv-table::
Marek Vavruša's avatar
Marek Vavruša committed
30 31
   :header: "Requirement", "Required by", "Notes"

32
   "ninja", "*all*", "*(build_only)*"
33
   "meson >= 0.46", "*all*", "*(build only)* [#]_"
34
   "C and C++ compiler", "*all*", "*(build only)* [#]_"
35
   "`pkg-config`_", "*all*", "*(build only)* [#]_"
36
   "libknot_ 2.7.6+", "*all*", "Knot DNS libraries"
37
   "LuaJIT_ 2.0+", "*all*", "Embedded scripting language."
38
   "libuv_ 1.7+", "*all*", "Multiplatform I/O and services."
39 40
   "lmdb", "*all*", "Memory-mapped database for cache"
   "GnuTLS", "*all*", "TLS"
Marek Vavruša's avatar
Marek Vavruša committed
41

42 43 44
There are also *optional* packages that enable specific functionality in Knot
Resolver, they are useful mainly for developers to build documentation and
tests.
Marek Vavruša's avatar
Marek Vavruša committed
45

Marek Vavruša's avatar
Marek Vavruša committed
46
.. csv-table::
47
   :header: "Optional", "Needed for", "Notes"
Marek Vavruša's avatar
Marek Vavruša committed
48

49
   "`lua-http`_", "``modules/http``", "HTTP/2 client/server for Lua."
50 51
   "luasocket_", "``trust anchors, modules/stats``", "Sockets for Lua."
   "luasec_", "``trust anchors``", "TLS for Lua."
Marek Vavruša's avatar
Marek Vavruša committed
52
   "cmocka_", "``unit tests``", "Unit testing framework."
53
   "Doxygen_", "``documentation``", "Generating API documentation."
54 55
   "Sphinx_ and sphinx_rtd_theme_", "``documentation``", "Building this
   HTML/PDF documentation."
56
   "breathe_", "``documentation``", "Exposing Doxygen API doc to Sphinx."
57 58 59
   "libsystemd_ >= 227", "``daemon``", "Systemd socket activation support."
   "libprotobuf_ 3.0+", "``modules/dnstap``", "Protocol Buffers support for
   dnstap_."
60
   "`libprotobuf-c`_ 1.0+", "``modules/dnstap``", "C bindings for Protobuf."
61 62
   "libfstrm_ 0.2+", "``modules/dnstap``", "Frame Streams data transport
   protocol."
63 64
   "luacheck_", "``lint-lua``", "Syntax and static analysis checker for Lua."
   "`clang-tidy`_", "``lint-c``", "Syntax and static analysis checker for C."
65
   "luacov_", "``check-config``", "Code coverage analysis for Lua modules."
Marek Vavruša's avatar
Marek Vavruša committed
66

67
.. [#] If ``meson >= 0.46`` isn't available for your distro, check backports
68
   repository oor use python pip to install it.
69
.. [#] Requires ``__attribute__((cleanup))`` and ``-MMD -MP`` for
70 71 72 73 74 75 76
   dependency file generation. GCC, Clang and ICC are supported.
.. [#] You can use variables ``<dependency>_CFLAGS`` and ``<dependency>_LIBS``
   to configure dependencies manually (i.e. ``libknot_CFLAGS`` and
   ``libknot_LIBS``).
.. [#] libuv 1.7 brings SO_REUSEPORT support that is needed for multiple forks.
   libuv < 1.7 can be still used, but only in single-process mode. Use
   :ref:`different method <daemon-reuseport>` for load balancing.
Marek Vavruša's avatar
Marek Vavruša committed
77

78 79 80
Packaged dependencies
~~~~~~~~~~~~~~~~~~~~~

81 82 83
.. note:: Some build dependencies can be found in
   `home:CZ-NIC:knot-reslver-build
   <https://build.opensuse.org/project/show/home:CZ-NIC:knot-resolver-build>`_.
84 85 86

Most of the dependencies can be resolved from packages, here's an overview for
several platforms.
87

88 89
* **Debian** (since *sid*) - current stable doesn't have libknot and libuv,
  which must be installed from sources.
90 91 92 93 94 95

.. code-block:: bash

   sudo apt-get install pkg-config libknot-dev libuv1-dev libcmocka-dev libluajit-5.1-dev

* **Ubuntu** - unknown.
96 97 98 99 100 101 102 103 104 105 106
* **Fedora**

.. code-block:: bash

   # minimal build
   sudo dnf install @buildsys-build knot-devel libuv-devel luajit-devel
   # unit tests
   sudo dnf install libcmocka-devel
   # integration tests
   sudo dnf install cmake git python-dns python-jinja2
   # optional features
107
   sudo dnf install lua-sec-compat lua-socket-compat systemd-devel
108 109
   # docs
   sudo dnf install doxygen python-breathe python-sphinx
110

111
* **RHEL/CentOS** - unknown.
112 113 114 115
* **openSUSE** - there is an `experimental package
  <https://build.opensuse.org/package/show/server:dns/knot-resolver>`_.
* **FreeBSD** - when installing from ports, all dependencies will install
  automatically, corresponding to the selected options.
116 117
* **NetBSD** - unknown.
* **OpenBSD** - unknown.
118 119
* **Mac OS X** - the dependencies can be found through `Homebrew
  <http://brew.sh/>`_.
120 121 122 123 124

.. code-block:: bash

   brew install pkg-config libuv luajit cmocka

125 126 127 128 129 130 131 132 133 134 135
Compilation
-----------

When installing into custom prefix during development / testing, using static
library is recommended to avoid issues with loading a shared library.

.. code-block:: bash

   $ meson build_dev --prefix=/tmp/kr --default-library=static
   $ ninja -C build_dev
   $ ninja install -C build_dev
Marek Vavruša's avatar
Marek Vavruša committed
136

137 138 139 140
Meson performs the build in the specified directory (``build_dev/`` in this
case) and doesn't pollute the source tree.  This allows you to have multiple
build roots with different build configurations at the same time.

141 142 143 144
.. note:: When compiling on OS X, creating a shared library is currently not
   possible when using luajit package from Homebrew due to `#37169
   <https://github.com/Homebrew/homebrew-core/issues/37169>`_.

145 146 147
Build options
~~~~~~~~~~~~~

148 149 150 151 152
It's possible to change the compilation with build options. These are useful to
packagers or developers who wish to customize the daemon behaviour, run
extended test suites etc.  By default, these are all set to sensible values.

For complete list of build options create a build directory and run:
153 154 155

.. code-block:: bash

156 157 158 159 160
   $ meson build_info
   $ meson configure build_info

To customize project build option, use ``-Doption=value`` when creating
a build directory:
161

162
.. code-block:: bash
163

164
   $ meson build_doc -Ddoc=enabled
165

166 167
.. _build-custom-flags:

168 169 170
Customizing compiler flags
~~~~~~~~~~~~~~~~~~~~~~~~~~

171 172
If you'd like to use customize the build, see meson's `built-in options
<https://mesonbuild.com/Builtin-options.html>`_. For hardening, see ``b_pie``.
173

174 175 176
For complete control over the build flags, use ``--buildtype=plain`` and set
``CFLAGS``, ``LDFLAGS`` when creating the build directory with ``meson``
command.
177

178 179 180 181
Tests
-----

The following command runs all tests. By default, only unit tests are enabled.
182 183 184

.. code-block:: bash

185
   $ ninja -C build_dev
186
   $ meson test -C build_dev
187

188
More comprehensive tests require you to install kresd before running the test
189
suite. To run all available tests, use ``-Dextra_tests=enabled`` build
190
option.
Marek Vavruša's avatar
Marek Vavruša committed
191 192 193

.. code-block:: bash

194 195 196 197 198 199 200 201 202 203 204 205 206
   $ ninja -C build_test
   $ ninja install -C build_test
   $ meson test -C build_test

It's also possible to run only specific test suite or a test.

.. code-block:: bash

   $ meson test -C build_test --help
   $ meson test -C build_test --list
   $ meson test -C build_test --no-suite postinstall
   $ meson test -C build_test integration.serve_stale

207 208 209 210 211 212 213 214 215 216 217 218 219 220
.. _build-html-doc:

HTML Documentation
------------------

To check for documentation dependencies and allow its installation, use
``-Ddoc=enabled``. The documentation doesn't build automatically. Instead,
target ``doc`` must be called explicitly.

.. code-block:: bash

   $ meson build_doc -Ddoc=enabled
   $ ninja -C build_doc doc

221 222 223 224 225 226 227 228
Tarball
-------

Released tarballs are available from `<https://knot-resolver.cz/download/>`_

To make a release tarball from git, use the follwing command. The

.. code-block:: bash
229

230
   $ ninja -C build_dev dist
231

232 233 234 235 236 237
It's also possible to make a development snapshot tarball:

.. code-block:: bash

   $ ./scripts/make-dev-archive.sh

238 239
.. _packaging:

240 241 242 243
Packaging
---------

Recommended build options for packagers:
244

245
* ``--buildtype=release`` for default flags (optimalization, asserts, ...). For complete control over flags, use ``plain`` and see :ref:`build-custom-flags`.
246 247 248
* ``--prefix=/usr`` to customize
  prefix, other directories can be set in a similar fashion, see ``meson setup
  --help``
249
* ``-Ddoc=enabled`` for offline html documentation (see :ref:`build-html-doc`)
250
* ``-Dinstall_kresd_conf=enabled`` to install default config file
251 252 253
* ``-Dclient=enabled`` to force build of kresc
* ``-Dunit_tests=enabled`` to force build of unit tests

254 255 256 257 258 259 260 261 262
Systemd
~~~~~~~

It's recommended to use the upstream system unit files. If any customizations
are required, drop-in files should be used, instead of patching/changing the
unit files themselves.

Depending on your systemd version, choose the appropriate build option:

263
* ``-Dsystemd_files=enabled`` (recommended) installs unit files with
264
  systemd socket activation support. Requires systemd >=227.
265
* ``-Dsystemd_files=nosocket`` for systemd <227. Unit files won't use
266 267 268 269 270 271 272 273 274 275 276 277
  socket activation.

To support enabling services after boot, you must also link ``kresd.target`` to
``multi-user.target.wants``:

.. code-block:: bash

   ln -s ../kresd.target /usr/lib/systemd/system/multi-user.target.wants/kresd.target

Trust anchors
~~~~~~~~~~~~~

278 279 280 281 282 283 284 285
If the target distro has externally managed DNSSEC trust anchors or root hints:

* ``-Dkeyfile_default=/usr/share/dns/root.key``
* ``-Droot_hints=/usr/share/dns/root.hints``

In case you want to have automatically managed DNSSEC trust anchors instead,
set the following and make sure both ``root.keys`` (check default
``keyfile_default`` path in summary) and its parent directory will be writable
286
by kresd process. This also requires luasocket_ and luasec_ runtime dependencies.
287 288

* ``-Dmanaged_ta=enabled``
289

290 291
Docker image
------------
292

293 294 295
Visit `hub.docker.com/r/cznic/knot-resolver
<https://hub.docker.com/r/cznic/knot-resolver/>`_ for instructions how to run
the container.
296

297
For development, it's possible to build the container directly from your git tree:
298 299 300

.. code-block:: bash

301
   $ docker build -t knot-resolver .
302 303


Vladimír Čunát's avatar
Vladimír Čunát committed
304
.. _Docker images: https://hub.docker.com/r/cznic/knot-resolver
Marek Vavruša's avatar
Marek Vavruša committed
305
.. _libuv: https://github.com/libuv/libuv
306
.. _LuaJIT: http://luajit.org/luajit.html
307
.. _Doxygen: https://www.stack.nl/~dimitri/doxygen/manual/index.html
308 309
.. _breathe: https://github.com/michaeljones/breathe
.. _Sphinx: http://sphinx-doc.org/
310
.. _sphinx_rtd_theme: https://pypi.python.org/pypi/sphinx_rtd_theme
311
.. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/
312
.. _libknot: https://gitlab.labs.nic.cz/knot/knot-dns
Marek Vavruša's avatar
Marek Vavruša committed
313
.. _cmocka: https://cmocka.org/
314
.. _luasec: https://luarocks.org/modules/brunoos/luasec
315
.. _luasocket: https://luarocks.org/modules/luarocks/luasocket
316
.. _lua-http: https://luarocks.org/modules/daurnimator/http
317
.. _boot2docker: http://boot2docker.io/
318
.. _deckard: https://gitlab.labs.nic.cz/knot/deckard
319
.. _libsystemd: https://www.freedesktop.org/wiki/Software/systemd/
320 321 322 323
.. _dnstap: http://dnstap.info/
.. _libprotobuf: https://developers.google.com/protocol-buffers/
.. _libprotobuf-c: https://github.com/protobuf-c/protobuf-c/wiki
.. _libfstrm: https://github.com/farsightsec/fstrm
324
.. _luacheck: http://luacheck.readthedocs.io
325
.. _clang-tidy: http://clang.llvm.org/extra/clang-tidy/index.html
326 327
.. _luacov: https://keplerproject.github.io/luacov/
.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php