Designs/Hammer.md

+[[_TOC_]]
+
+## Main Hammer Commands
+
+### prepare-system
+
+This is the critical command in Hammer. Its main purpose is preparing a system for building and unit testing Kea. This command can prepare a local system or a VM using VirtualBox or LXC container. It installs all required build dependencies either from native system packages or if they are not available then from sources that are fetched from remote repositories. It also installs and configures services that are needed for running unit tests like MySQL, PostgreSQL or Radius.
+
+### build
+
+Build command builds Kea in two ways: either using ./configure and make directly or using scripts for preparing native system packages (RPM, deb or APK for Alpine). In the case of direct building, it is also possible to run unit tests. Before the command starts compilation it always runs `prepare-system` internally to be sure that all dependencies are in place.
+
+### ssh
+
+This command allows for accessing a VirtualBox VM or LXC container using SSH.
+
+### package-box
+
+This command is used for preparing a Vagrant box with either VirtualBox image or LXC image, and then uploading it to http://app.vagrantup.com/.
+
+## Design
+
+### Commands Execution and Providers
+
+Hammer can execute `prepare-system` and `build` commands either directly in the current system or inside VirtualBox VM or LXC container. Bringing up a VM or a container is realized by Vagrant and its providers for VirtualBox and LXC.
+
+Hammer, in case of VM or container, first brings them up, then copies itself (hammer.py) to the VM or the container, and then using SSH it executes (again) Hammer with indicated command inside the VM or container system directly. In the end, it copies the results e.g. native packages to the host system.
+
+Local example:
+
+```mermaid
+sequenceDiagram
+    participant H as Hammer Build
+    Note over H: Hammer does the build
+```
+
+VirtualBox/LXC example:
+
+```mermaid
+sequenceDiagram
+    participant H as Hammer Build
+    participant VC as VM/container
+    Note over H: Start VM/container
+    H->>VC: copy hammer.py
+    H->>+VC: run hammer.py build
+    Note over VC: Hammer does the build
+    VC-->>-H: return results
+```
+
+### Systems Support
+
+Hammer supports several operating systems and their particular versions (several Linux distributions and FreeBSD). In various places in the Hammer source code, there are system-specific cases and there are `if` conditions for particular operating systems and sometimes their versions.
+
+There is a `SYSTEMS` global map that enumerates operating systems and their versions that are supported in Hammer. New systems or their new versions should be put.
+
+If Hammer is going to work with a VM (VirtualBox) or a container (LXC) then it requires an image of the operating system that can be passed to VM or container. This is handled by Vagrant and its boxes. A box is a VM or container image with extra metadata wrapped in tar.gz.
+
+`IMAGE_TEMPLATES` global map maps OSes, their versions and provider (ie. VirtualBox or LXC) to two kinds of box images, bare image and kea image. `bare` and `kea` keys indicates the location of the images on http://app.vagrantup.com/.
+
+Bare images are base images that do not contain yet any specific things for Kea. Kea images have all dependencies installed and configured. Bare images are used to prepare Kea images using `package-box` command. Bare images can be acquired in 3 ways:
+
+- prepared manually
+- found on http://app.vagrantup.com/
+- in case of LXC prepared by lxc-vagrantizer tool (https://github.com/godfryd/lxc-vagrantizer).
+
+Other aspects of new OS preparation can be found on https://gitlab.isc.org/isc-private/qa-dhcp/-/wikis/new%20os.
+
+### Features
+
+By default, Hammer has some features enabled but most of them are disabled.
+
+All features in random order:
+
+- install
+- distcheck
+- unittest
+- docs
+- mysql
+- pgsql
+- cql
+- native-pkg
+- radius
+- gssapi
+- netconf
+- shell
+- forge
+- perfdhcp
+- ccache
+
+Features can be enabled with `-w` command line switch (`w` from with) or disabled using `-x` switch (`x` from exclude).
+
+The features have impact on both `prepare-system` and `build` commands.
+
+**install** - after completing a build of Kea, the artifacts are installed in the current system; if this was direct compilation with make then `make install` is executed; if this was build of packages then the built packages are installed
+
+**distcheck** - this invokes `make distcheck`
+
+**unittest** - in the case of `prepare-system` it installs dependencies for running unit; in case of `build` command it is only available in direct compilation and it enabled unittests using `--with-gtest-source` in `./configure` and then invokes unittests after compilation using `make check`
+
+**docs** - in the case of `prepare-system` it installs dependencies for generating docs (sphinx); in case of `build` command it adds `--enable-generate-docs` to ./configure which cases docs generation in `make` invocation
+
+**mysql** - in the case of `prepare-system` it installs and configures MySQL; in case of `build` command it adds `--with-mysql` to `./configure`
+
+**pgsql** - in the case of `prepare-system` it installs and configures PostgreSQL; in case of `build` command it adds `--with-pgsql` to `./configure`
+
+**native-pkg** - it enables other features: `docs`, `perfdhcp`, `shell`, `mysql`, `pgsql`, `radius` and `gssapi`; in the case of `prepare-system` it installs extra dependencies to build native system packages; in case of `build` command it builds Kea native system packages instead of just directly invoking `make`
+
+**radius** - in the case of `prepare-system` it installs and configures RADIUS service; in case of `build` command it adds `--with-freeradius` to `./configure`
+
+**gssapi** - in the case of `prepare-system` it installs GSS API libs; in case of `build` command it adds `--with-gssapi` to `./configure`
+
+**netconf** - in the case of `prepare-system` it installs sysrepo dependencies; in case of `build` command it adds `--with-libyang` and `--with-sysrepo` switches to `./configure`
+
+**shell** - in case of `build` command it adds `--enable-shell` switch to `./configure`
+
+**forge** - in the case of `prepare-system` it configures database in a way that is expected by Forge
+
+**perfdhcp** - in case of `build` command it adds `--enable-perfdhcp` to `./configure`
+
+**ccache** - it enables using `ccache` during Kea compilation
\ No newline at end of file