build.rst 5.57 KB
Newer Older
Marek Vavruša's avatar
Marek Vavruša committed
1 2 3 4 5 6 7 8 9 10 11 12
Building project
================

The resolver isn't yet available in the repositories, so you can either build it from sources or use
official `Docker images`_.

Platform considerations
-----------------------

.. csv-table::
   :header: "Project", "Platforms", "Compatibility notes"

13 14
   "``daemon``", "UNIX-like [#]_, Microsoft Windows", "C99, libuv_ provides portable I/O"
   "``library``", "UNIX-like, Microsoft Windows [#]_ ", "MSVC_ not supported, needs MinGW_"
Marek Vavruša's avatar
Marek Vavruša committed
15
   "``modules``", "*varies*", ""
16 17
   "``tests/unit``", "*equivalent to library*", ""
   "``tests/integration``", "UNIX-like", "Depends on library injection (see [2]_)"
Marek Vavruša's avatar
Marek Vavruša committed
18

19 20
.. [#] Known to be running (not exclusively) on FreeBSD, Linux and OS X.
.. [#] Modules are not supported yet, as the PE/DLL loading is different. Library injection is working with ELF *(or Mach-O flat namespace)* only.
Marek Vavruša's avatar
Marek Vavruša committed
21 22 23 24

Requirements
------------

Marek Vavruša's avatar
Marek Vavruša committed
25
The following is a list of software required to build Knot DNS Resolver from sources.
Marek Vavruša's avatar
Marek Vavruša committed
26

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

   "`GNU Make`_ 3.80+", "*all*", "*(build only)*"
31 32
   "`pkg-config`_", "*all*", "*(build only)* [#]_"
   "C compiler", "*all*", "*(build only)* [#]_"
Marek Vavruša's avatar
Marek Vavruša committed
33 34
   "libknot_ 2.0+", "*all*", "Knot DNS library."

Marek Vavruša's avatar
Marek Vavruša committed
35
There are also *optional* packages that enable specific functionality in Knot DNS Resolver, apart from the `libuv`_ and `GCCGO`_, they are useful mainly for developers to build documentation and tests.
Marek Vavruša's avatar
Marek Vavruša committed
36

Marek Vavruša's avatar
Marek Vavruša committed
37
.. csv-table::
Marek Vavruša's avatar
Marek Vavruša committed
38 39
   :header: "Requirement", "Required by", "Notes"

Marek Vavruša's avatar
Marek Vavruša committed
40
   "Lua_ 5.1+", "``daemon``", "Embeddable scripting language (LuaJIT_ is preferred)."
Marek Vavruša's avatar
Marek Vavruša committed
41 42 43
   "libuv_ 1.0+", "``daemon``", "Multiplatform I/O and services."
   "cmocka_", "``unit tests``", "Unit testing framework."
   "Python_", "``integration tests``", "For scripting tests, C header files are required (``python-dev``)"
44 45 46
   "GCCGO_",  "``modules/go``", "For building Go modules, see modules documentation."
   "Doxygen_", "``documentation``", "Generating API documentation."
   "Sphinx_", "``documentation``", "Building this HTML/PDF documentation."
47
   "breathe_", "``documentation``", "Exposing Doxygen API doc to Sphinx."
Marek Vavruša's avatar
Marek Vavruša committed
48

49 50
.. [#] Requires C99, ``__attribute__((cleanup))`` and ``-MMD -MP`` for 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``).
Marek Vavruša's avatar
Marek Vavruša committed
51

52 53
Getting Docker image
--------------------
Marek Vavruša's avatar
Marek Vavruša committed
54 55 56 57 58

Docker images require only either Linux or a Linux VM (see boot2docker_ on OS X).

.. code-block:: bash

59
   $ docker run cznic/knot-resolver
Marek Vavruša's avatar
Marek Vavruša committed
60

61
See the `Docker images`_ page for more information and options.
Marek Vavruša's avatar
Marek Vavruša committed
62 63 64 65
You can hack on the container by changing the container entrypoint to shell like:

.. code-block:: bash

66
   $ docker run -it --entrypoint=/bin/bash cznic/knot-resolver
Marek Vavruša's avatar
Marek Vavruša committed
67

68 69
.. tip:: You can build the Docker image yourself with ``docker build -t knot-resolver scripts``.

Marek Vavruša's avatar
Marek Vavruša committed
70
Building from sources 
71
---------------------
Marek Vavruša's avatar
Marek Vavruša committed
72 73 74 75 76 77

The Knot DNS Resolver depends on the development version of the Knot DNS library, and a reasonably recent version of `libuv`.
Several dependencies may not be in the packages yet, the script pulls and installs all dependencies in a chroot.

.. code-block:: bash

78
   $ make info # See what's missing
Marek Vavruša's avatar
Marek Vavruša committed
79 80 81 82 83 84

You can avoid rebuilding dependencies by specifying `BUILD_IGNORE` variable, see the Dockerfile_ for example.
Usually you only really need to rebuild `libknot`.

.. code-block:: bash

85 86 87 88
   $ export FAKEROOT="${HOME}/.local"
   $ export PKG_CONFIG_PATH="${FAKEROOT}/lib/pkgconfig"
   $ export BUILD_IGNORE="..." # Ignore installed dependencies
   $ ./scripts/bootstrap-depends.sh ${FAKEROOT}
89 90


91 92 93 94 95 96
.. note:: The build system relies on `pkg-config`_ to find dependencies.
   You can override it to force custom versions of the software by environment variables.

   .. code-block:: bash

      $ make check libknot_CFLAGS="-I/opt/include" libknot_LIBS="-L/opt/lib -lknot -lknot-int -ldnssec"
97

98 99 100
.. warning:: If the dependencies lie outside of library search path, you need to add them somehow.
   Try ``LD_LIBRARY_PATH`` on Linux/BSD, and ``DYLD_FALLBACK_LIBRARY_PATH`` on OS X.
   Otherwise you need to add the locations to linker search path.
101

102
When you have all the dependencies ready, you can build, test and install.
Marek Vavruša's avatar
Marek Vavruša committed
103 104 105

.. code-block:: bash

106
   $ make PREFIX="/usr/local"
107 108
   $ make check
   $ make install
Marek Vavruša's avatar
Marek Vavruša committed
109

110 111
.. note:: Always build with ``PREFIX`` if you want to install, as it is hardcoded in the executable for module search path.

112
Alternatively you can build only specific parts of the project, i.e. ``library``.
Marek Vavruša's avatar
Marek Vavruša committed
113 114

.. code-block:: bash
115 116 117 118 119 120 121 122 123 124

   $ make lib
   $ make lib-install

.. note:: Documentation is not built by default, run ``make doc`` to build it.

Building extras
~~~~~~~~~~~~~~~

The project can be built with code coverage tracking using the ``COVERAGE=1`` variable.
Marek Vavruša's avatar
Marek Vavruša committed
125

126
.. _Docker images: https://registry.hub.docker.com/u/cznic/knot-resolver
Marek Vavruša's avatar
Marek Vavruša committed
127 128 129 130 131
.. _libuv: https://github.com/libuv/libuv
.. _MSVC: https://msdn.microsoft.com/en-us/vstudio/hh386302.aspx
.. _MinGW: http://www.mingw.org/
.. _Dockerfile: https://registry.hub.docker.com/u/cznic/knot-resolver/dockerfile/

132 133
.. _Lua: http://www.lua.org/about.html
.. _LuaJIT: http://luajit.org/luajit.html
134
.. _GCCGO: https://golang.org/doc/install/gccgo
135 136 137
.. _Doxygen: http://www.stack.nl/~dimitri/doxygen/manual/index.html
.. _breathe: https://github.com/michaeljones/breathe
.. _Sphinx: http://sphinx-doc.org/
Marek Vavruša's avatar
Marek Vavruša committed
138 139 140 141 142 143
.. _GNU Make: http://www.gnu.org/software/make/
.. _pkg-config: http://www.freedesktop.org/wiki/Software/pkg-config/
.. _libknot: https://gitlab.labs.nic.cz/labs/knot
.. _cmocka: https://cmocka.org/
.. _Python: https://www.python.org/

144
.. _boot2docker: http://boot2docker.io/