$ 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
* ``-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/
.. _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
projects / thirdparty / knot-resolver.git / commitdiff
