From: Marek Vavruša <marek.vavrusa@nic.cz>
Date: Thu, 19 Mar 2015 10:07:05 +0000 (+0100)
Subject: doc: installation
X-Git-Tag: v1.0.0-beta1~286^2
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=7f7566a3dcfb72b0ff4d4fa07ebf439185db63af;p=thirdparty%2Fknot-resolver.git

doc: installation
---

diff --git a/doc/build.rst b/doc/build.rst
new file mode 100644
index 000000000..369ea0eb3
--- /dev/null
+++ b/doc/build.rst
@@ -0,0 +1,107 @@
+Building project
+================
+
+The resolver isn't yet available in the repositories, so you can either build it from sources or use
+official `Docker images`_.
+
+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_"
+   "``modules``", "*varies*", ""
+   "``unit tests``", "*equivalent to library*", ""
+   "``integration tests``", "UNIX-like", "Depends on ELF/Mach-O (flat namespace) semantics for library injection"
+
+.. [*] Known to be running (not exclusively) on FreeBSD, Linux and OS X.
+.. [*] Modules are not supported yet, as the PE/DLL loading is different.
+
+Requirements
+------------
+
+The following is a list of software required to build Knot DNS Resolver, alternatively you can use
+the `Docker images`.
+
+.. csv-table:: Mandatory requirements.
+   :header: "Requirement", "Required by", "Notes"
+
+   "`GNU Make`_ 3.80+", "*all*", "*(build only)*"
+   "C compiler", "*all*", "*(build only)* [*]_ )"
+   "libknot_ 2.0+", "*all*", "Knot DNS library."
+
+.. csv-table:: Optional requirements.
+   :header: "Requirement", "Required by", "Notes"
+
+   "`pkg-config`_", "*all*", "*(build only, optional)*"
+   "libuv_ 1.0+", "``daemon``", "Multiplatform I/O and services."
+   "cmocka_", "``unit tests``", "Unit testing framework."
+   "Python_", "``integration tests``", "For scripting tests, C header files are required (``python-dev``)"
+   "GCCGO_",  "``Go modules``", "For building Go modules, see modules documentation."
+
+.. [*] Requires C99, ``__attribute__((cleanup))`` and ``-MMD -MP`` for dependency file generation. GCC, Clang and ICC are supported.
+
+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
+
+See the build page https://registry.hub.docker.com/u/cznic/knot-resolver 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
+
+Building from sources 
+~~~~~~~~~~~~~~~~~~~~~
+
+The Knot DNS Resolver depends on the development version of the Knot DNS library, and a reasonably recent version of `libuv`.
+Several dependencies may not be in the packages yet, the script pulls and installs all dependencies in a chroot.
+
+.. code-block:: bash
+
+	$ 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}
+
+Now you can build, test and install.
+
+.. code-block:: bash
+
+	$ 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
+
+.. _Docker images: https://registry.hub.docker.com/u/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/
+
+.. _GNU Make: http://www.gnu.org/software/make/
+.. _pkg-config: http://www.freedesktop.org/wiki/Software/pkg-config/
+.. _libknot: https://gitlab.labs.nic.cz/labs/knot
+.. _cmocka: https://cmocka.org/
+.. _Python: https://www.python.org/
+
+.. _boot2docker: http://boot2docker.io/
diff --git a/doc/index.rst b/doc/index.rst
index af71688d1..d54906980 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -8,8 +8,10 @@ Modular architecture of the library keeps the core tiny and efficient, and provi
 .. toctree::
    :maxdepth: 2
 
-   lib 
+   build
    daemon
+   lib
+
 
 Indices and tables
 ==================