Commit 72c0b87c authored by Tomas Krizek's avatar Tomas Krizek

meson: doc/build - update build and docker info

parent d070b854
......@@ -45,7 +45,6 @@ This is simple and doesn't require any dependencies or system modifications, jus
$ docker run -Pit cznic/knot-resolver
```
See the build page [hub.docker.com/r/cznic/knot-resolver](https://hub.docker.com/r/cznic/knot-resolver/) for more information and options.
The images are meant as an easy way to try knot-resolver, and they're not designed for production use.
### Running
......
......@@ -166,8 +166,8 @@ To run in-tree tests:
$ meson test --no-suite postinstall -C build_dev
More comprehensive tests require you to install kresd before running the test
suite. To run all available tests (also see ``extra_tests`` build option
above), use:
suite. To run all available tests (also see ``extra_tests`` build option),
use:
.. code-block:: bash
......@@ -206,176 +206,43 @@ by kresd process.
* ``-Dmanaged_ta=enabled``
Building with security compiler flags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Customizing compiler flags
~~~~~~~~~~~~~~~~~~~~~~~~~~
If you'd like to use custom compiler flags, see meson's `built-in options
<https://mesonbuild.com/Builtin-options.html>`_. You might be interested in
``c_args``, ``c_link_args``. For hardening, it's also possible to use
``b_pie``.
Docker image
------------
Knot Resolver enables certain `security compile-time flags <https://wiki.debian.org/Hardening#Notes_on_Memory_Corruption_Mitigation_Methods>`_ that do not affect performance.
You can add more flags to the build by appending them to `CFLAGS` variable, e.g. ``make CFLAGS="-fstack-protector"``.
.. csv-table::
:header: "Method", "Status", "Notes"
"-fstack-protector", "*disabled*", "(must be specifically enabled in CFLAGS)"
"-D_FORTIFY_SOURCE=2", "**enabled**", ""
"-pie", "**enabled**", "enables ASLR for kresd (disable with ``make HARDENING=no``)"
"RELRO", "**enabled**", "full [#]_"
You can also disable linker hardening when it's unsupported with ``make HARDENING=no``.
.. [#] See `checksec.sh <http://www.trapkit.de/tools/checksec.html>`_
Building for packages
~~~~~~~~~~~~~~~~~~~~~
The build system supports DESTDIR_
TODO no longer support, use meson --prefix instead (DESTDIR will cause invalid path to modules)
.. Our amalgamation has fallen into an unmaintained state and probably doesn't work.
.. and `amalgamated builds <https://www.sqlite.org/amalgamation.html>`_.
.. code-block:: bash
$ make install DESTDIR=/tmp/stage
.. $ make all install AMALG=yes # Amalgamated build
.. Amalgamated build assembles everything in one source file and compiles it. It is useful for packages, as the compiler sees the whole program and is able to produce a smaller and faster binary. On the other hand, it complicates debugging.
.. tip:: There is a template for service file and AppArmor profile to help you kickstart the package.
Default paths
~~~~~~~~~~~~~
The default installation follows FHS with several custom paths for configuration and modules.
All paths are prefixed with ``PREFIX`` variable by default if not specified otherwise.
TODO: rewrite/update entire section
.. csv-table::
:header: "Component", "Variable", "Default", "Notes"
"library", "``LIBDIR``", "``$(PREFIX)/lib``", "pkg-config is auto-generated [#]_"
"daemon", "``SBINDIR``", "``$(PREFIX)/sbin``", ""
"configuration", "``ETCDIR``", "``$(PREFIX)/etc/knot-resolver``", "Configuration file, templates."
"modules", "``MODULEDIR``", "``$(LIBDIR)/kdns_modules``", "Runtime directory for loading dynamic modules [#]_."
"trust anchor file", "``keyfile_default``", "*(none)*", "Path to read-only trust anchor file, which is used as fallback when no other file is specified. [#]_"
"work directory", "", "the current directory", "Run directory for daemon. (Only relevant during run time, not e.g. during installation.)"
.. [#] The ``libkres.pc`` is installed in ``$(LIBDIR)/pkgconfig``.
.. [#] The default moduledir can be changed with `-m` option to `kresd` daemon or by calling `moduledir()` function from lua.
.. [#] If no other trust anchor is specified by user, the compiled-in path ``keyfile_default`` must contain a valid trust anchor. This is typically used by distributions which provide DNSSEC root trust anchors as part of distribution package. Users can disable the built-in trust anchor by adding ``trust_anchors.keyfile_default = nil`` to their configuration.
.. note:: Each module is self-contained and may install additional bundled files within ``$(MODULEDIR)/$(modulename)``. These files should be read-only, non-executable.
Static or dynamic?
~~~~~~~~~~~~~~~~~~
By default the resolver library is built as a dynamic library with versioned ABI. You can revert to static build with ``BUILDMODE`` variable.
.. code-block:: bash
$ make BUILDMODE=dynamic # Default, create dynamic library
$ make BUILDMODE=static # Create static library
When the library is linked statically, it usually produces a smaller binary. However linking it to various C modules might violate ODR and increase the size.
Resolving dependencies
~~~~~~~~~~~~~~~~~~~~~~
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 libknot_CFLAGS="-I/opt/include" libknot_LIBS="-L/opt/lib -lknot -ldnssec"
Optional dependencies may be disabled as well using ``HAS_x=yes|no`` variable.
.. code-block:: bash
$ make HAS_go=no HAS_cmocka=no
.. 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.
Building extras
~~~~~~~~~~~~~~~
The project can be built with code coverage tracking using the ``COVERAGE=1`` variable.
The `make coverage` target gathers both gcov code coverage for C files, and luacov_ code coverage for Lua files and merges it for analysis. It requires lcov_ to be installed.
.. code-block:: bash
$ make coverage
Running unit and integration tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The linter requires luacheck_ and `clang-tidy`_ and is executed by ``make lint``.
The unit tests require cmocka_ and are executed by ``make check``.
Tests for the dnstap module need go and are executed by ``make ckeck-dnstap``.
The integration tests use Deckard, the `DNS test harness <deckard>`_.
.. code-block:: bash
$ make check-integration
Note that the daemon and modules must be installed first before running integration tests, the reason is that the daemon
is otherwise unable to find and load modules.
Read the `documentation <deckard_doc>`_ for more information about requirements, how to run it and extend it.
Getting Docker image
--------------------
Docker images require only either Linux or a Linux VM (see boot2docker_ on OS X).
.. code-block:: bash
$ docker run cznic/knot-resolver
Visit `hub.docker.com/r/cznic/knot-resolver
<https://hub.docker.com/r/cznic/knot-resolver/>`_ for instructions how to run
the container.
See the `Docker images`_ page for more information and options.
You can hack on the container by changing the container entrypoint to shell like:
For development, it's possible to build the container directly from your git tree:
.. code-block:: bash
$ docker run -it --entrypoint=/bin/bash cznic/knot-resolver
$ docker build -t knot-resolver .
.. tip:: You can build the Docker image yourself with ``docker build -t knot-resolver scripts``.
.. _Docker images: https://hub.docker.com/r/cznic/knot-resolver
.. _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/
.. _Lua: https://www.lua.org/about.html
.. _LuaJIT: http://luajit.org/luajit.html
.. _Go: https://golang.org
.. _geoip: https://github.com/abh/geoip
.. _Doxygen: https://www.stack.nl/~dimitri/doxygen/manual/index.html
.. _breathe: https://github.com/michaeljones/breathe
.. _Sphinx: http://sphinx-doc.org/
.. _sphinx_rtd_theme: https://pypi.python.org/pypi/sphinx_rtd_theme
.. _GNU Make: https://www.gnu.org/software/make/
.. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/
.. _libknot: https://gitlab.labs.nic.cz/knot/knot-dns
.. _cmocka: https://cmocka.org/
.. _Python: https://www.python.org/
.. _luasec: https://luarocks.org/modules/brunoos/luasec
.. _luasocket: https://luarocks.org/modules/luarocks/luasocket
.. _lua-http: https://luarocks.org/modules/daurnimator/http
.. _boot2docker: http://boot2docker.io/
.. _deckard: https://gitlab.labs.nic.cz/knot/deckard
.. _deckard_doc: https://gitlab.labs.nic.cz/knot/knot-resolver/blob/master/tests/README.rst
.. _libsystemd: https://www.freedesktop.org/wiki/Software/systemd/
.. _dnstap: http://dnstap.info/
.. _libprotobuf: https://developers.google.com/protocol-buffers/
......@@ -385,5 +252,3 @@ You can hack on the container by changing the container entrypoint to shell like
.. _clang-tidy: http://clang.llvm.org/extra/clang-tidy/index.html
.. _luacov: https://keplerproject.github.io/luacov/
.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php
.. _DESTDIR: https://www.gnu.org/prep/standards/html_node/DESTDIR.html
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment