From 8cf44759a85d0524edab14ae2d1113328fd2e400 Mon Sep 17 00:00:00 2001
From: Tomek Mrugalski <tomasz@isc.org>
Date: Fri, 25 Jan 2019 20:10:12 +0100
Subject: [PATCH] [#372,!181] Initial user's guide section for hammer added.

---
 doc/guide/Makefile.am |  2 +-
 doc/guide/hammer.xml  | 85 +++++++++++++++++++++++++++++++++++++++++++
 doc/guide/install.xml |  4 +-
 3 files changed, 89 insertions(+), 2 deletions(-)
 create mode 100644 doc/guide/hammer.xml

diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am
index e59aca09e3..ead79dc0a9 100644
--- a/doc/guide/Makefile.am
+++ b/doc/guide/Makefile.am
@@ -10,7 +10,7 @@ DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml lease-expiration.xml logging.
 DOCBOOK += ddns.xml hooks.xml hooks-class-cmds.xml hooks-ha.xml hooks-host-cache.xml
 DOCBOOK += hooks-lease-cmds.xml hooks-radius.xml hooks-stat-cmds.xml libdhcp.xml
 DOCBOOK += lfc.xml stats.xml ctrl-channel.xml classify.xml shell.xml agent.xml
-DOCBOOK += netconf.xml api.xml congestion-handling.xml
+DOCBOOK += netconf.xml api.xml congestion-handling.xml hammer.xml
 
 EXTRA_DIST = $(DOCBOOK)
 
diff --git a/doc/guide/hammer.xml b/doc/guide/hammer.xml
new file mode 100644
index 0000000000..3c4d8ccd63
--- /dev/null
+++ b/doc/guide/hammer.xml
@@ -0,0 +1,85 @@
+<!--
+ - Copyright (C) 2019 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+
+<!-- need this include to make the &keaversion; macro work -->
+<!DOCTYPE book [
+<!ENTITY % keaversion SYSTEM "version.ent">
+%keaversion;
+]>
+
+<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="hammer">
+    <title>Hammer Building Tool</title>
+    <para>
+      An optionl building tool called hammer was introduced with Kea 1.6.0. It
+      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, but since it was
+      proven to be quite powerful, it is now part of the Kea distribution.
+    </para>
+
+    <note>
+      <simpara>Use of this tool is completely optional. Everything it does can
+      be done manually.</simpara>
+    </note>
+
+
+    <para>
+      The first time user is strongly encouraged to look at hammer's built in
+      help: <screen><userinput>./hammer.py --help</userinput></screen> It will
+      list available parameters.
+    </para>
+
+    <para>
+      Hammer is able to set up various operating systems running in LXC of
+      virtualbox. To list of supported systems, use
+      <command>list-systems</command> command:
+      <screen>
+$<userinput>./hammer.py list-systems</userinput>
+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
+</screen>
+</para>
+
+<!-- @todo: explain how to install deps (hammer ensure-hammer-deps), explain
+     what is installed -->
+
+<!-- @todo: explain how to install deps and kea on host system, without setting
+     up any VMs (is ensure-hammer-deps needed for this? if not, make a note
+     about it above) -->
+
+<para>
+  Hammer can be told to set up a new virtual machine and install specified OS on
+  it:
+  <screen>
+    ./hammer.py -p virtualbox -s freebsd -r 12.0 prepare-system
+  </screen>
+</para>
+
+<!-- @todo: describe how to install kea on a system,
+
+This didn't work (why?)
+./hammer.py -p virtualbox -s freebsd -r 12.0 -w install,unittest,docs,mysql build -->
+
+</section>
diff --git a/doc/guide/install.xml b/doc/guide/install.xml
index 531af5c240..fa2f4ef13b 100644
--- a/doc/guide/install.xml
+++ b/doc/guide/install.xml
@@ -633,6 +633,8 @@ $ <userinput>make</userinput>
           <screen><userinput>./configure [other-options] --with-cql=<replaceable>path-to-cql_config</replaceable></userinput></screen>
         </para>
       </section>
-   </section>
+    </section>
+
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hammer.xml"/>
 
   </chapter>
-- 
2.47.2