Skip to content
GitLab
Projects Groups Snippets
  • /
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in / Register
  • Kea Kea
  • Project information
    • Project information
    • Activity
    • Labels
    • Members
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
  • Issues 559
    • Issues 559
    • List
    • Boards
    • Service Desk
    • Milestones
  • Merge requests 63
    • Merge requests 63
  • Deployments
    • Deployments
    • Releases
  • Packages and registries
    • Packages and registries
    • Container Registry
  • Monitor
    • Monitor
    • Incidents
  • Analytics
    • Analytics
    • Value stream
    • Repository
  • Wiki
    • Wiki
  • Snippets
    • Snippets
  • Activity
  • Graph
  • Create a new issue
  • Commits
  • Issue Boards
Collapse sidebar
  • ISC Open Source ProjectsISC Open Source Projects
  • KeaKea
  • Wiki
  • Designs
  • Hammer

Hammer · Changes

Page history
rename designs to Designs authored Aug 17, 2022 by Andrei Pavel's avatar Andrei Pavel
Hide whitespace changes
Inline Side-by-side
Designs/Hammer.md 0 → 100644
View page @ e3c1f9fd
[[_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
Clone repository

🏠 Homepage

📖 Docs

📦 Download: sources, packages, git

🚚 Release Notes

🛠 Hooks

🐛 Known Issues: serious, all issues

🗒 Mailing Lists: kea-users, kea-dev

🌍 Community Developed Tools


Dev corner

Designs

Gitlab Howto

Coding Guidelines

Release Process

Developer's Guide

IDE Tips


🔍 All Wiki Pages