From: Marek VavruĊĦa Date: Thu, 19 Mar 2015 13:14:09 +0000 (+0100) Subject: doc: improved lib/build doc (apiref) X-Git-Tag: v1.0.0-beta1~283^2~1 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=3acaf8fa92e222f39e2a1eb6a50a0cdd94ca4ba1;p=thirdparty%2Fknot-resolver.git doc: improved lib/build doc (apiref) --- diff --git a/doc/build.rst b/doc/build.rst index 0f7c20609..ea4877df7 100644 --- a/doc/build.rst +++ b/doc/build.rst @@ -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 ``_CFLAGS`` and ``_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 ``_CFLAGS`` and ``_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/ diff --git a/doc/lib.rst b/doc/lib.rst index 422d93528..a0ccdca94 100644 --- a/doc/lib.rst +++ b/doc/lib.rst @@ -1,7 +1,44 @@ .. 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 diff --git a/lib/README.rst b/lib/README.rst index 2e6e7df4d..885232004 100644 --- a/lib/README.rst +++ b/lib/README.rst @@ -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