diff options
Diffstat (limited to 'doc/sphinx/arm/hammer.rst')
| -rw-r--r-- | doc/sphinx/arm/hammer.rst | 130 |
1 files changed, 130 insertions, 0 deletions
diff --git a/doc/sphinx/arm/hammer.rst b/doc/sphinx/arm/hammer.rst new file mode 100644 index 0000000..b8a5318 --- /dev/null +++ b/doc/sphinx/arm/hammer.rst @@ -0,0 +1,130 @@ +.. _hammer: + +Hammer Building Tool +==================== + +Hammer is a Python 3 script that lets users automate tasks related to building +Kea, such as setting up virtual machines, installing Kea dependencies, +compiling Kea with various options, running unit-tests and more. This +tool was created primarily for internal QA purposes at ISC and it is not +included in the Kea distribution; however, it is available in the Kea +git repository. This tool was developed primarily for internal purposes +and ISC cannot guarantee its proper operation. Administrators who decide to use it +should do so with care. + +.. note:: + + Use of this tool is completely optional. Everything it does can be + done manually. + +The first-time user is strongly encouraged to look at Hammer's built-in +help: + +.. code-block:: console + + $ ./hammer.py --help + +It will list available parameters. + +Hammer is able to set up various operating systems running either in LXC +or in VirtualBox. For a list of supported systems, use the +``supported-systems`` command: + +.. code-block:: console + + $ ./hammer.py supported-systems + fedora: + - 27: lxc, virtualbox + - 28: lxc, virtualbox + - 29: lxc, virtualbox + centos: + - 7: lxc, virtualbox + rhel: + - 8: virtualbox + ubuntu: + - 16.04: lxc, virtualbox + - 18.04: lxc, virtualbox + - 18.10: lxc, virtualbox + debian: + - 8: lxc, virtualbox + - 9: lxc, virtualbox + freebsd: + - 11.2: virtualbox + - 12.0: virtualbox + +It is also possible to run the build locally, in the current system (if the OS +is supported). + +First, the Hammer dependencies must be installed: Vagrant +and either VirtualBox or LXC. Hammer can install +Vagrant and the required Vagrant plugins using the command: + +.. code-block:: console + + $ ./hammer.py ensure-hammer-deps + +VirtualBox and LXC must be installed manually. + +The basic functions provided by Hammer are to prepare the build environment +and perform the actual build, and to run the unit tests locally in the current +system. This can be achieved by running the command: + +.. code-block:: console + + $ ./hammer.py build -p local + +The scope of the process can be defined using the ``--with`` (``-w``) and ``--without`` +(``-x``) options. By default, the ``build`` command builds Kea with +documentation, installs it locally, and runs unit tests. + +To exclude the installation and generation of docs, type: + +.. code-block:: console + + $ ./hammer.py build -p local -x install docs + +The basic scope can be extended by mysql, pgsql, native-pkg, +radius, shell, and forge. + +.. note:: + + If building Kea locally, Hammer dependencies like Vagrant are + not needed. + +Hammer can be told to set up a new virtual machine with a specified +operating system, without the build: + +.. code-block:: console + + $ ./hammer.py prepare-system -p virtualbox -s freebsd -r 12.0 + +This way, a system can be prepared for our own use. To get to such a system +using SSH, invoke: + +.. code-block:: console + + $ ./hammer.py ssh -p virtualbox -s freebsd -r 12.0 + +It is possible to speed up subsequent Hammer builds via +`ccache <https://ccache.samba.org/>`__. During +compilation, ccache stores objects in a shared folder. In subsequent runs, +instead of doing an actual compilation, ccache returns the stored earlier +objects. The cache with these objects for reuse must be stored outside of VM +or LXC. To indicate the folder, the ``--ccache-dir`` +parameter for Hammer must be included. In the indicated folder, there are separate stored objects for each target +operating system. + +.. code-block:: console + + $ ./hammer.py build -p lxc -s ubuntu -r 18.04 --ccache-dir ~/kea-ccache + +.. note:: + + ccache is currently only supported for LXC in Hammer; support + for VirtualBox may be added later. + +For more information check: + +.. code-block:: console + + $ ./hammer.py --help |