[#35,!36] Update ATF use doc and remove support for --with-atf=bind

modified:
    RELNOTES
    bind/Makefile.in
    configure
    configure.ac
    configure.ac+lt
    configure.ac-base
    configure.ac-lt
    doc/devel/atf.dox

8 files changed, 216 insertions, 126 deletions

diff --git a/RELNOTES b/RELNOTES
index cd9de71b..ba9324bd 100644
--- a/RELNOTES
+++ b/RELNOTES
@@ -194,6 +194,11 @@ by Eric Young (eay@cryptsoft.com).
   now fail if a host declaration specifies more than one uid.
   [Gitlab #7]
 
+- Updated developer's documentation on building and running unit tests.
+  Removed support for --with-atf=bind as BIND9 no longer bundles in ATF
+  source.
+  [Gitlab #35]
+
 		Changes since 4.4.0 (New Features)
 - none
 		Changes since 4.4.0 (Bug Fixes)
diff --git a/bind/Makefile.in b/bind/Makefile.in
index 107ce159..8fb5358e 100644
--- a/bind/Makefile.in
+++ b/bind/Makefile.in
@@ -26,15 +26,13 @@ bindconfig = --without-openssl --without-libxml2 --without-libjson \
 	--includedir=@includedir@ --libdir=@libdir@  --without-python\
 	@BINDLT@ @BINDIOMUX@ @BINDCONFIG@ --enable-full-report
 
-@BIND_ATF_FALSE@cleandirs = ./lib ./include
-@BIND_ATF_TRUE@cleandirs = ./lib ./include ./atf
+cleandirs = ./lib ./include
 cleanfiles = ./configure.log ./build.log ./install.log
 
 bindlibs = isc dns isccfg irs
 installdirs = includedir=${binddir}/include libdir=${binddir}/lib
 
-@BIND_ATF_FALSE@all: bind1 bind2
-@BIND_ATF_TRUE@all: bind1 atf bind2
+all: bind1 bind2
 
 bind1:
 # Extract the source from the tarball, if it hasn't been already.
diff --git a/configure b/configure
index 1c0302d7..a17d3afe 100755
--- a/configure
+++ b/configure
@@ -650,12 +650,10 @@ DISTCHECK_ATF_CONFIGURE_FLAG
 HAVE_ATF_FALSE
 HAVE_ATF_TRUE
 UNITTESTS
-pkgcfg_found
 ATF_BIN
 ATF_LDFLAGS
 ATF_CFLAGS
-BIND_ATF_FALSE
-BIND_ATF_TRUE
+pkgcfg_found
 byte_order
 AR
 RANLIB
@@ -1468,7 +1466,7 @@ Optional Features:
 Optional Packages:
   --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
   --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
-  --with-atf=PATH         specify location where atf was installed (or "bind")
+  --with-atf=PATH         specify location where atf was installed
   --with-srv-conf-file=PATH
                           Default file containing dhcpd configuration (default
                           is typically /etc/dhcpd.conf)
@@ -5598,26 +5596,8 @@ if test "${with_atf+set}" = set; then :
   withval=$with_atf; atf_path="$withval"
 fi
 
- if test "$atf_path" = "bind"; then
-  BIND_ATF_TRUE=
-  BIND_ATF_FALSE='#'
-else
-  BIND_ATF_TRUE='#'
-  BIND_ATF_FALSE=
-fi
-
-if test "$atf_path" = "bind" ; then
-    DISTCHECK_ATF_CONFIGURE_FLAG="--with-atf=bind"
-    atf_pcp="bind"
-    atf_path="\${top_srcdir}/bind/atf"
-    ATF_CFLAGS="-I$atf_path/include -DUNIT_TEST"
-    ATF_LDFLAGS="-L$atf_path/lib -latf-c"
-    ATF_BIN=`cd $srcdir; pwd`/bind/atf/bin
 
-
-
-    BINDCONFIG="$BINDCONFIG --with-atf"
-elif test "$atf_path" != "no" ; then
+if test "$atf_path" != "no" ; then
     DISTCHECK_ATF_CONFIGURE_FLAG="--with-atf=$atf_path"
     # Config path for pkg-config
     atf_pcp=""
@@ -7689,10 +7669,6 @@ if test -z "${am__fastdepCC_TRUE}" && test -z "${am__fastdepCC_FALSE}"; then
 Usually this means the macro was only invoked conditionally." "$LINENO" 5
 fi
 
-if test -z "${BIND_ATF_TRUE}" && test -z "${BIND_ATF_FALSE}"; then
-  as_fn_error $? "conditional \"BIND_ATF\" was never defined.
-Usually this means the macro was only invoked conditionally." "$LINENO" 5
-fi
 if test -z "${HAVE_ATF_TRUE}" && test -z "${HAVE_ATF_FALSE}"; then
   as_fn_error $? "conditional \"HAVE_ATF\" was never defined.
 Usually this means the macro was only invoked conditionally." "$LINENO" 5
diff --git a/configure.ac b/configure.ac
index dcca3894..eb083d49 100644
--- a/configure.ac
+++ b/configure.ac
@@ -252,21 +252,10 @@ fi
 DISTCHECK_ATF_CONFIGURE_FLAG=
 atf_path="no"
 AC_ARG_WITH([atf],
-    AS_HELP_STRING([--with-atf=PATH],[specify location where atf was installed (or "bind")]),
+    AS_HELP_STRING([--with-atf=PATH],[specify location where atf was installed]),
     [atf_path="$withval"])
-AM_CONDITIONAL(BIND_ATF, test "$atf_path" = "bind")
-if test "$atf_path" = "bind" ; then
-    DISTCHECK_ATF_CONFIGURE_FLAG="--with-atf=bind"
-    atf_pcp="bind"
-    atf_path="\${top_srcdir}/bind/atf"
-    ATF_CFLAGS="-I$atf_path/include -DUNIT_TEST"
-    ATF_LDFLAGS="-L$atf_path/lib -latf-c"
-    ATF_BIN=`cd $srcdir; pwd`/bind/atf/bin
-    AC_SUBST(ATF_CFLAGS)
-    AC_SUBST(ATF_LDFLAGS)
-    AC_SUBST(ATF_BIN)
-    BINDCONFIG="$BINDCONFIG --with-atf"
-elif test "$atf_path" != "no" ; then
+
+if test "$atf_path" != "no" ; then
     DISTCHECK_ATF_CONFIGURE_FLAG="--with-atf=$atf_path"
     # Config path for pkg-config
     atf_pcp=""
diff --git a/configure.ac+lt b/configure.ac+lt
index 2e00862d..7e3448c7 100644
--- a/configure.ac+lt
+++ b/configure.ac+lt
@@ -253,21 +253,9 @@ fi
 DISTCHECK_ATF_CONFIGURE_FLAG=
 atf_path="no"
 AC_ARG_WITH([atf],
-    AS_HELP_STRING([--with-atf=PATH],[specify location where atf was installed (or "bind")]),
+    AS_HELP_STRING([--with-atf=PATH],[specify location where atf was installed]),
     [atf_path="$withval"])
-AM_CONDITIONAL(BIND_ATF, test "$atf_path" = "bind")
-if test "$atf_path" = "bind" ; then
-    DISTCHECK_ATF_CONFIGURE_FLAG="--with-atf=bind"
-    atf_pcp="bind"
-    atf_path="\${top_srcdir}/bind/atf"
-    ATF_CFLAGS="-I$atf_path/include -DUNIT_TEST"
-    ATF_LDFLAGS="-L$atf_path/lib -latf-c"
-    ATF_BIN=`cd $srcdir; pwd`/bind/atf/bin
-    AC_SUBST(ATF_CFLAGS)
-    AC_SUBST(ATF_LDFLAGS)
-    AC_SUBST(ATF_BIN)
-    BINDCONFIG="$BINDCONFIG --with-atf"
-elif test "$atf_path" != "no" ; then
+if test "$atf_path" != "no" ; then
     DISTCHECK_ATF_CONFIGURE_FLAG="--with-atf=$atf_path"
     # Config path for pkg-config
     atf_pcp=""
diff --git a/configure.ac-base b/configure.ac-base
index f570c6f5..302f6f04 100644
--- a/configure.ac-base
+++ b/configure.ac-base
@@ -258,21 +258,9 @@ fi
 DISTCHECK_ATF_CONFIGURE_FLAG=
 atf_path="no"
 AC_ARG_WITH([atf],
-    AS_HELP_STRING([--with-atf=PATH],[specify location where atf was installed (or "bind")]),
+    AS_HELP_STRING([--with-atf=PATH],[specify location where atf was installed]),
     [atf_path="$withval"])
-AM_CONDITIONAL(BIND_ATF, test "$atf_path" = "bind")
-if test "$atf_path" = "bind" ; then
-    DISTCHECK_ATF_CONFIGURE_FLAG="--with-atf=bind"
-    atf_pcp="bind"
-    atf_path="\${top_srcdir}/bind/atf"
-    ATF_CFLAGS="-I$atf_path/include -DUNIT_TEST"
-    ATF_LDFLAGS="-L$atf_path/lib -latf-c"
-    ATF_BIN=`cd $srcdir; pwd`/bind/atf/bin
-    AC_SUBST(ATF_CFLAGS)
-    AC_SUBST(ATF_LDFLAGS)
-    AC_SUBST(ATF_BIN)
-    BINDCONFIG="$BINDCONFIG --with-atf"
-elif test "$atf_path" != "no" ; then
+if test "$atf_path" != "no" ; then
     DISTCHECK_ATF_CONFIGURE_FLAG="--with-atf=$atf_path"
     # Config path for pkg-config
     atf_pcp=""
diff --git a/configure.ac-lt b/configure.ac-lt
index dcca3894..7ec27800 100644
--- a/configure.ac-lt
+++ b/configure.ac-lt
@@ -252,21 +252,9 @@ fi
 DISTCHECK_ATF_CONFIGURE_FLAG=
 atf_path="no"
 AC_ARG_WITH([atf],
-    AS_HELP_STRING([--with-atf=PATH],[specify location where atf was installed (or "bind")]),
+    AS_HELP_STRING([--with-atf=PATH],[specify location where atf was installed]),
     [atf_path="$withval"])
-AM_CONDITIONAL(BIND_ATF, test "$atf_path" = "bind")
-if test "$atf_path" = "bind" ; then
-    DISTCHECK_ATF_CONFIGURE_FLAG="--with-atf=bind"
-    atf_pcp="bind"
-    atf_path="\${top_srcdir}/bind/atf"
-    ATF_CFLAGS="-I$atf_path/include -DUNIT_TEST"
-    ATF_LDFLAGS="-L$atf_path/lib -latf-c"
-    ATF_BIN=`cd $srcdir; pwd`/bind/atf/bin
-    AC_SUBST(ATF_CFLAGS)
-    AC_SUBST(ATF_LDFLAGS)
-    AC_SUBST(ATF_BIN)
-    BINDCONFIG="$BINDCONFIG --with-atf"
-elif test "$atf_path" != "no" ; then
+if test "$atf_path" != "no" ; then
     DISTCHECK_ATF_CONFIGURE_FLAG="--with-atf=$atf_path"
     # Config path for pkg-config
     atf_pcp=""
diff --git a/doc/devel/atf.dox b/doc/devel/atf.dox
index 0bf82d13..3026c4bc 100644
--- a/doc/devel/atf.dox
+++ b/doc/devel/atf.dox
@@ -29,44 +29,68 @@ Test Framework)</a> as a framework to run our unittests.
 @section testsAtf ATF unit-tests
 
 ATF stands for Automated Test Framework, and is the framework used for unit
-tests in ISC DHCP and BIND9. ATF sources can be downloaded from
-https://github.com/jmmv/kyua . ATF itself must be configured, compiled
-and then installed to be available during the DHCP configure procedure.
+tests in ISC DHCP.  Since ATF was created, a next generation QA toolchain
+called, Kyua, has beend developed that can execute ATF unit tests.  There are
+two approaches one can take to install the necessary software for executing
+ISC DHCP unit tests:
 
-There are three options for installing ATF.  1) Get the ATF sources and
-follow INSTALL file supplied with ATF sources (it's essentially the typical
-./configure && make && make install procedure).  2) install Kyua with the ATF
-compatibility package, or 3) use the ATF version included in bind sources.
+1) Install pre-Kyua release (0.19 or earlier) of ATF
 
-To configure and build the ATF from BIND you should set the "--with-atf" option
-to "bind".
-@verbatim
-./configure --with-atf=bind
-@endverbatim
+Using this approach is the simplest as it involves installing only ATF. However
+it requires using a version of ATF that is no longer maintained and which may
+eventually may be unavailable.
 
+ATF may be found here: https://github.com/jmmv/atf
 
-Beginning with ATF version 0.16, it is necessary to include the following
-options --enable-tools and --disable-shared when configuring ATF:
 
-@verbatim
-    configure --prefix=<prefix> --enable-tools --disable-shared
-@endverbatim
+2) Install post-Kyua release of ATF (0.20 or later) and Kyua
+
+Using this approach requires the installation of more software as Kyua has
+dependencies that ATF lacks.  The advantage is that the version(s) that can
+be used are all still supported.
 
-ISC DHCP unittests will run with ATF releases upto 0.19.  Beginning with
-ATF 0.20, the tools, atf-run and atf-report required by ISC DHCP, were
-deprecated and are no longer included with ATF.
+Kyua may be found here: https://github.com/jmmv/kyua
 
-The ATF successor, called Kyua, is being developed. As of August 2012,
-the latest available release of Kyua is 0.5. It claims to offer
-feature parity with ATF. Migration to Kyua may be planned some time in
-the future, but DHCP uses ATF for now. Such an upgrade should be done
-in coordination with BIND.
+@subsection preKyuaATF Using pre-Kyua ATF
 
-To build and run the unit-tests, use the following:
+This section describes how to install and use pre-Kyua ATF release to run
+ISC DHCP unit tests.  The most recent release of ATF that can be used without
+also needing Kyua, is ATF version 0.19.  While this version is still available
+and using it is least software to install to to run ISC DHCP unit tests, there
+may come a point in time when this version is no longer available. It may be
+downloaded here: https://github.com/jmmv/atf/releases/tag/atf-0.19
+
+After downloading and unpacking the source, you'll need to configure
+it, build it, and then install it.  Note you'll need to include the
+"--enable-tools" option when configuring ATF.   The following would build
+and install it to /opt/atf/atf-0.19/local:
 
 @verbatim
-$ ./configure --with-atf
+
+$ cd /opt/atf
+$ tar -xvf $HOME/Downloads/atf-0.19.tar.gz
+
+# While the --prefix is optional, you must specify --enable-tools
+#as a configure option
+
+$ ./configure --prefix=/opt/atf/atf-0.19/local --enable-tools
 $ make
+$ sudo make install
+
+@endverbatim
+
+To build and run the ISC DHCP unit-tests, use the following:
+
+@verbatim
+$ git clone https://gitlab.isc.org/isc-projects/dhcp.git
+$ cd dhcp
+
+# Note because we used --prefix when configuraing ATF above, we
+# need to tell ISC DHCP configure where it is located.
+
+$ ./configure --with-atf=/opt/atf/atf-0.19/local
+
+# Run all of the unit tests via "make check"
 $ make check
 @endverbatim
 
@@ -75,25 +99,23 @@ subdirectory.  Note that if one or more tests in a unit test subdirectory fail
 the make process will stop.  To run all of the tests regardless of outcome,
 use "make -k check"
 
-The following syntax is supported as well:
-@verbatim
-$ ./configure --with-atf=/path/to/your/atf/install
-@endverbatim
-
-but it seems to have troubles sometimes detecting ATF installation, at least
-with ATF 0.14 and Mac OS X 10.6.8.
+Note, If you installed ATF to its default location rather than using --prefix
+or you install the pkg-config .pc files for ATF, you should be able to
+simply specify "--with-atf" without a path when configuring ISC DHCP.
 
-Each code directory (e.g. server/) that has unit-tests has a sub-directory
-named tests (e.g. server/tests). You can execute "make check" in that
-directory to run specific subset of tests.
+Each dhcp source sub-directory (e.g. server, common) that has unit-tests has a
+sub-directory named tests (e.g. server/tests). You can execute "make check" in
+that sub-directory to run its specific subset of tests.
 
 Unit-tests are grouped into suites, each suite being a separate
 executable. The typical way to run tests is:
 
 @verbatim
 $ atf-run | atf-report
-(This assumes atf-run and atf-report are in your path)
-or
+
+# (This assumes atf-run and atf-report are in your path)
+# or
+
 $ sh ../../tests/unittests.sh
 @endverbatim
 
@@ -115,6 +137,142 @@ that direct binary execution is not recommended as it won't be able to
 recover from crash.  However, such an approach is convenient for
 running the test under the debugger.
 
+@subsection KyuaPlusATF Using Kyua with ATF
+
+Kyua is a QA toolchain that has been layered on top of ATF.  The tools
+necessary to run ATF unit tests migrated from ATF to within Kyua beginning
+with ATF 0.20. This section includes instructions for building and running
+ISC DHCP with Kyua. Instructions are included for both Ubuntu 18.04 and MacOS.
+
+@subsubsection KyuaLinux Kyua Ubuntu 18.04 Instructions
+
+The following instructions are for based on Ubuntu 18.04, but
+are typical of a linux installation. It installs all software
+into default locations for simplicity.  If you want to use
+custom installation paths, you may have to set additional environment
+variables, library paths, and the like.
+
+Before we install kyua, we must install its dependencies: lua, sqlite3,
+ATF, and lutok
+
+@verbatim
+
+# lua and sqlite3 have packages, we'll use them
+
+$ apt-get install liblua5.1-0-dev
+$ apt-get install libsqlite3-dev
+
+# Fetch, build, and install the lastest version of ATF
+#
+
+$ git clone https://github.com/jmmv/atf.git
+$ cd atf
+$ autoreconf --install --force
+$ ./configure
+$ make
+$ sudo make install
+$ cd ..
+
+# Fetch fetch, build, and install the lastest version lutok
+#
+
+$ git clone https://github.com/jmmv/lutok.git
+$ cd lutok
+
+# We must use -I argument to tell auotreconf where to find the ATF .m4 files
+$ autoreconf --install -s -I/usr/local/share/aclocal
+
+$ ./configure
+$ make
+$ sudo make install
+$ cd ..
+
+# Finally, we fetch, build and install the lastest kyua
+
+$ git clone https://github.com/jmmv/kyua.git
+$ cd kyua
+
+# We must use -I argument to tell auotreconf where to find the ATF .m4 files
+$ autoreconf --install -s -I/usr/local/share/aclocal
+
+$ ./configure
+$ make
+$ sudo make install
+$ cd ..
+@endverbatim
+
+To build ISC DHCP with Kyua and run all the unit tests is the same:
+
+@verbatim
+$ git clone https://gitlab.isc.org/isc-projects/dhcp.git
+$ cd dhcp
+
+# Because we used default installations we simply enable unit tests with
+# --with-atf with no path value.
+
+$ ./configure --with-atf
+$ make
+
+# Run the ISC DHCP unit tests
+$ make check
+@endverbatim
+
+@subsubsection KyuaMacOS Kyua macOS Instructions
+
+The following instructions are for based on macOS Mojave (10.1.4.4).
+Before we install kyua, we must install its dependencies: pkgconfig, lutok,
+and ATF:
+
+@verbatim
+
+# install dependencies
+$ brew install pkgconfig
+$ brew install lutok
+
+# install atf so we can build kyua and dhcp with unit tests
+git clone https://github.com/jmmv/atf.git
+cd atf
+autoreconf --install --force
+./configure --prefix=/opt/atf
+make
+sudo make install
+cd ..
+
+# configure kyua with atf
+git clone https://github.com/jmmv/kyua.git
+cd kyua
+autoreconf --install -s -I/opt/atf/share/aclocal
+./configure --prefix=/opt/kyua
+make
+sudo make install
+cd ..
+
+# reconfigure atf with kyua
+cd atf
+PATH=$PATH:/opt/kyua/bin ./configure --prefix=/opt/atf
+make
+sudo make install
+cd ..
+@endverbatim
+
+To build ISC DHCP with Kyua and run all the unit tests is the same:
+
+@verbatim
+$ git clone https://gitlab.isc.org/isc-projects/dhcp.git
+$ cd dhcp
+
+# Because we used the prefix "/opt/atf" to install ATF we need to
+# add that path to --with-atf when we configure ISC DHCP.
+
+$ ./configure --with-atf=/opt/atf
+$ make
+
+# Add kyua to the path and then run the ISC DHCP unit tests
+# via "make check"
+$ export PATH=$PATH:/opt/kyua/bin
+$ make check
+@endverbatim
+
 @section testsAtfAdding Adding new unit-tests
 
 There are a small number of unit-tests that are not ATF based. They will be