From: Tomas Krizek Date: Thu, 14 Feb 2019 09:52:53 +0000 (+0100) Subject: meson: doc/build - update build and docker info X-Git-Tag: v4.0.0~24^2~122 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=72c0b87c04cace019826ca16fdff0127e8e65910;p=thirdparty%2Fknot-resolver.git meson: doc/build - update build and docker info --- diff --git a/README.md b/README.md index 32bf52685..059b9a514 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/doc/build.rst b/doc/build.rst index de2b544f3..f1ef4ed15 100644 --- a/doc/build.rst +++ b/doc/build.rst @@ -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 +`_. 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 `_ 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 `_ - -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 `_. - -.. 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 `_. - -.. 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 `_ 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 +`_ 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