Commit 8c1d3dbd authored by Marek Vavruša's avatar Marek Vavruša

Merge branch 'doxygen-groups'

parents d1fcd8f8 505585b9
......@@ -10,14 +10,14 @@ Platform considerations
.. csv-table::
:header: "Project", "Platforms", "Compatibility notes"
"``daemon``", "UNIX-like [*]_, Microsoft Windows", "C99, libuv_ provides portable I/O"
"``library``", "UNIX-like, Microsoft Windows [*]_ ", "MSVC_ not supported (requires ``__attribute__((cleanup))`` and GNU99), needs MinGW_"
"``daemon``", "UNIX-like [#]_, Microsoft Windows", "C99, libuv_ provides portable I/O"
"``library``", "UNIX-like, Microsoft Windows [#]_ ", "MSVC_ not supported, needs MinGW_"
"``modules``", "*varies*", ""
"``unit tests``", "*equivalent to library*", ""
"``integration tests``", "UNIX-like", "Depends on ELF/Mach-O (flat namespace) semantics for library injection"
"``tests/unit``", "*equivalent to library*", ""
"``tests/integration``", "UNIX-like", "Depends on library injection (see [2]_)"
.. [*] Known to be running (not exclusively) on FreeBSD, Linux and OS X.
.. [*] Modules are not supported yet, as the PE/DLL loading is different.
.. [#] 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.
Requirements
------------
......@@ -29,8 +29,8 @@ the `Docker images`.
:header: "Requirement", "Required by", "Notes"
"`GNU Make`_ 3.80+", "*all*", "*(build only)*"
"`pkg-config`_", "*all*", "*(build only [*]_ )*"
"C compiler", "*all*", "*(build only)* [*]_ )"
"`pkg-config`_", "*all*", "*(build only)* [#]_"
"C compiler", "*all*", "*(build only)* [#]_"
"libknot_ 2.0+", "*all*", "Knot DNS library."
.. csv-table:: Optional requirements.
......@@ -42,10 +42,10 @@ the `Docker images`.
"GCCGO_", "``modules/go``", "For building Go modules, see modules documentation."
"Doxygen_", "``documentation``", "Generating API documentation."
"Sphinx_", "``documentation``", "Building this HTML/PDF documentation."
"breathe_", "``documentation``", "Interfacing Doxygen API documentation to Sphinx HTML/PDF documentation."
"breathe_", "``documentation``", "Exposing Doxygen API doc to Sphinx."
.. [*] 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``).
.. [#] 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``).
Docker image
~~~~~~~~~~~~
......@@ -54,14 +54,14 @@ Docker images require only either Linux or a Linux VM (see boot2docker_ on OS X)
.. code-block:: bash
$ docker run cznic/knot-resolver
$ docker run cznic/knot-resolver
See the `Docker images`_ page for more information and options.
You can hack on the container by changing the container entrypoint to shell like:
.. code-block:: bash
$ docker run -it --entrypoint=/bin/bash cznic/knot-resolver
$ docker run -it --entrypoint=/bin/bash cznic/knot-resolver
Building from sources
~~~~~~~~~~~~~~~~~~~~~
......@@ -71,37 +71,47 @@ Several dependencies may not be in the packages yet, the script pulls and instal
.. code-block:: bash
$ make info # See what's missing
$ make info # See what's missing
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
$ export FAKEROOT="${HOME}/.local"
$ export PKG_CONFIG_PATH="${FAKEROOT}/lib/pkgconfig"
$ export BUILD_IGNORE="..." # Ignore installed dependencies
$ ./scripts/bootstrap-depends.sh ${FAKEROOT}
The build system depends on `pkg-config`_ to find dependencies, but you can ignore it and force custom versions
of the software by environment variables.
$ export FAKEROOT="${HOME}/.local"
$ export PKG_CONFIG_PATH="${FAKEROOT}/lib/pkgconfig"
$ export BUILD_IGNORE="..." # Ignore installed dependencies
$ ./scripts/bootstrap-depends.sh ${FAKEROOT}
.. code-block:: bash
$ make info libknot_CFLAGS="-I/opt/include" libknot_LIBS="-L/opt/lib -lknot -lknot-int -ldnssec"
.. 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"
When you have all the dependencies ready, you can build, test and install.
.. code-block:: bash
$ make
$ make check
$ make install
$ make
$ make check
$ make install
Alternatively you can build only specific parts of the project, i.e. ``library``.
.. code-block:: bash
$ make lib
$ make lib-install
$ 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.
.. _Docker images: https://registry.hub.docker.com/u/cznic/knot-resolver
.. _libuv: https://github.com/libuv/libuv
......@@ -109,6 +119,7 @@ Alternatively you can build only specific parts of the project, i.e. ``library``
.. _MinGW: http://www.mingw.org/
.. _Dockerfile: https://registry.hub.docker.com/u/cznic/knot-resolver/dockerfile/
.. _GCCGO: https://golang.org/doc/install/gccgo
.. _Doxygen: http://www.stack.nl/~dimitri/doxygen/manual/index.html
.. _breathe: https://github.com/michaeljones/breathe
.. _Sphinx: http://sphinx-doc.org/
......
......@@ -19,3 +19,18 @@ right now.
$ ./daemon/kresolved -a 127.0.0.1#53
.. _libuv: https://github.com/libuv/libuv
Interacting with the daemon
---------------------------
The daemon features a CLI interface if launched interactively, type ``help`` to see the list of available commands.
You can load modules this way and use their properties to get information about statistics and such.
.. code-block:: bash
$ kresolved
...
[system] started in interactive mode, type 'help'
> load cached
> cached.cached_size
{ "size": 53 }
\ No newline at end of file
.. include:: ../lib/README.rst
API reference
-------------
Library layout
--------------
.. doxygenindex::
The library as described provides basic services for name resolution, which should cover the usage.
The following part is for those who are planning to hack on the library or develop modules, to give
you an idea about the API and the library layout.
Name resolution
~~~~~~~~~~~~~~~
.. doxygengroup:: resolution
:project: libkresolve
Resolution plan
~~~~~~~~~~~~~~~
.. doxygengroup:: rplan
:project: libkresolve
Cache
~~~~~
.. doxygengroup:: cache
:project: libkresolve
Nameservers
~~~~~~~~~~~
.. doxygengroup:: nameservers
:project: libkresolve
Modules
~~~~~~~
.. doxygengroup:: modules
:project: libkresolve
Utilities
~~~~~~~~~
.. doxygengroup:: utils
:project: libkresolve
......@@ -9,16 +9,15 @@ Requirements
Overview
--------
Resolution plan
~~~~~~~~~~~~~~~
Resolving a name
~~~~~~~~~~~~~~~~
Cache
~~~~~
.. note:: Migrating from ``getaddrinfo``
Reputation
~~~~~~~~~~
Using cache
~~~~~~~~~~~
Modules
~~~~~~~
Loading modules
~~~~~~~~~~~~~~~
.. _libknot: https://gitlab.labs.nic.cz/labs/knot/tree/master/src/libknot
......@@ -14,6 +14,9 @@
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/** \addtogroup cache
* @{
*/
#pragma once
#include <libknot/rrset.h>
......@@ -120,3 +123,4 @@ int kr_cache_clear(namedb_txn_t *txn);
*/
int kr_cache_prune(namedb_txn_t *txn, uint32_t timestamp);
/** @} */
......@@ -22,6 +22,10 @@
#include "lib/module.h"
#include "lib/cache.h"
/** \addtogroup resolution
* @{
*/
/**
* Name resolution context.
*
......@@ -62,3 +66,5 @@ int kr_context_deinit(struct kr_context *ctx);
* @return KNOT_E*
*/
int kr_context_register(struct kr_context *ctx, const char *module_name);
/** @} */
......@@ -14,6 +14,10 @@
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/** \addtogroup resolution
* @{
*/
#pragma once
#include <errno.h>
......@@ -44,4 +48,6 @@
#define KR_DNS_PORT 53
#define KR_DNAME_ROOT ((const knot_dname_t*)"")
#define KR_EDNS_VERSION 0
#define KR_EDNS_PAYLOAD 4096
\ No newline at end of file
#define KR_EDNS_PAYLOAD 4096
/** @} */
......@@ -16,6 +16,10 @@
#pragma once
/** \addtogroup modules
* @{
*/
#include <libknot/processing/layer.h>
#include <libknot/packet/pkt.h>
......@@ -44,3 +48,4 @@ struct kr_layer_param {
#define QRDEBUG(query, cls, fmt, ...)
#endif
/** @} */
......@@ -14,6 +14,10 @@
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/** \addtogroup modules
* @{
*/
#pragma once
#include <libknot/processing/layer.h>
......@@ -87,3 +91,5 @@ void kr_module_unload(struct kr_module *module);
*/
#define KR_MODULE_EXPORT(module) \
uint32_t module ## _api() { return KR_MODULE_API; }
/** @} */
......@@ -14,6 +14,10 @@
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/** \addtogroup nameservers
* @{
*/
#pragma once
#include "lib/layer.h"
......@@ -28,4 +32,6 @@ enum kr_ns_score {
* @param param layer parameters
* @return enum kr_ns_score or higher positive value
*/
int kr_nsrep_score(const knot_dname_t *ns, struct kr_layer_param *param);
\ No newline at end of file
int kr_nsrep_score(const knot_dname_t *ns, struct kr_layer_param *param);
/** @} */
......@@ -14,6 +14,10 @@
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/** \addtogroup resolution
* @{
*/
#pragma once
#include <libknot/packet/pkt.h>
......@@ -31,3 +35,5 @@
*/
int kr_resolve(struct kr_context* ctx, knot_pkt_t *answer,
const knot_dname_t *qname, uint16_t qclass, uint16_t qtype);
/** @} */
......@@ -14,6 +14,10 @@
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/** \addtogroup rplan
* @{
*/
#pragma once
#include <sys/time.h>
......@@ -135,3 +139,5 @@ struct kr_query *kr_rplan_current(struct kr_rplan *rplan);
* Return true if resolution chain satisfies given query.
*/
bool kr_rplan_satisfies(struct kr_query *closure, const knot_dname_t *name, uint16_t cls, uint16_t type);
/** @} */
......@@ -14,6 +14,10 @@
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/** \addtogroup utils
* @{
*/
#pragma once
#include <stdio.h>
......@@ -35,3 +39,5 @@ extern void _cleanup_fclose(FILE **p);
/** Concatenate N strings. */
char* kr_strcatdup(unsigned n, ...);
/** @} */
......@@ -14,6 +14,10 @@
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/** \addtogroup rplan
* @{
*/
#pragma once
#include <libknot/dname.h>
......@@ -68,3 +72,4 @@ int kr_set_zone_cut_addr(struct kr_zonecut *cut, const knot_rrset_t *rr, uint16_
*/
int kr_find_zone_cut(struct kr_zonecut *cut, const knot_dname_t *name, namedb_txn_t *txn, uint32_t timestamp);
/** @} */
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