new config option: build ATF stuff from bind [#38754]

1 files changed, 59 insertions, 42 deletions

diff --git a/doc/devel/atf.dox b/doc/devel/atf.dox
index dd596841..0bf82d13 100644
--- a/doc/devel/atf.dox
+++ b/doc/devel/atf.dox
@@ -31,9 +31,19 @@ Test Framework)</a> as a framework to run our unittests.
 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.  Please
+and then installed to be available during the DHCP configure procedure.
+
+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).
+./configure && make && make install procedure).  2) install Kyua with the ATF
+compatibility package, or 3) use the ATF version included in bind sources.
+
+To configure and build the ATF from BIND you should set the "--with-atf" option
+to "bind".
+@verbatim
+./configure --with-atf=bind
+@endverbatim
+
 
 Beginning with ATF version 0.16, it is necessary to include the following
 options --enable-tools and --disable-shared when configuring ATF:
@@ -46,10 +56,11 @@ 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.
 
-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.
+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.
 
 To build and run the unit-tests, use the following:
 
@@ -86,21 +97,23 @@ or
 $ sh ../../tests/unittests.sh
 @endverbatim
 
-atf-run will read the Atffile in the current directory and execute all the tests
-specified in it. Using atf-run - rather than calling the test binary directly -
-has several major benefits. The main one is that atf-run is able to recover from
-test segfault and continue execution from the next case onwards. Another is that
-it is possible to specify a timeout for a test. atf-run will kill the test in
-case of any infinite loops and will continue running next tests.
+atf-run will read the Atffile in the current directory and execute all
+the tests specified in it. Using atf-run - rather than calling the
+test binary directly - has several major benefits. The main one is
+that atf-run is able to recover from test segfault and continue
+execution from the next case onwards. Another is that it is possible
+to specify a timeout for a test. atf-run will kill the test in case of
+any infinite loops and will continue running next tests.
 
 It is possible to run atf-run without passing its output to atf-report, but its
 output is somewhat convoluted. That is useful in some situations, e.g. when one
 wants to see test output.
 
-It is possible to run test binary directly. The only required parameter is the
-test case name. The binary will print out a warning 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.
+It is possible to run test binary directly. The only required
+parameter is the test case name. The binary will print out a warning
+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.
 
 @section testsAtfAdding Adding new unit-tests
 
@@ -162,27 +175,30 @@ See existing Makefile.am for examples, and the Automake documentation:
 
     http://www.gnu.org/software/automake/manual/html_node/Tests.html
 
-<b>2. Implement the test.</b> That typically means that you create a new file that will
-hold test code. It is recommended you name it (tested_feature_name)_unittest.c
-and put the file in specified tests directory.  For example tests related to
-hash tables used on the server side should be named
-server/tests/hash_unittest.c. If in doubt, it is convenient to name the test
-code after the file that holds tested code, e.g. server/mdb6.c is tested in
+<b>2. Implement the test.</b> That typically means that you create a
+new file that will hold test code. It is recommended you name it
+(tested_feature_name)_unittest.c and put the file in specified tests
+directory.  For example tests related to hash tables used on the
+server side should be named server/tests/hash_unittest.c. If in doubt,
+it is convenient to name the test code after the file that holds
+tested code, e.g. server/mdb6.c is tested in
 server/tests/mdb6_unittest.c.
 
-The file server/tests/simple_unittest.c holds a template explaining the basic
-layout of the ATF tests.  There may be many test cases in a single *_unittest.c
-file. Make sure that you register all your test cases using ATF_TP_ADD_TC()
-macro, and try to minimize modifications to the tested code if possible. Keep in
-mind that we are using modernized \ref codingGuidelines for test
-development. You are advised to also look at atf-c-api(3) man page.
-
-To add a new test, such as when a new module is added or when you want to start
-testing existing code, you can copy the server/tests/simple_unittest.c as a new
-new file, add the new file as a target in Makefile.am, and begin adding
-tests. Reviewing that file is a good idea, even if you decide to write your test
-from scratch, as it give you quick overview of the essential capabilities of the
-ATF framework (how to write test, how to make checks, pass or fail test
+The file server/tests/simple_unittest.c holds a template explaining
+the basic layout of the ATF tests.  There may be many test cases in a
+single *_unittest.c file. Make sure that you register all your test
+cases using ATF_TP_ADD_TC() macro, and try to minimize modifications
+to the tested code if possible. Keep in mind that we are using
+modernized \ref codingGuidelines for test development. You are advised
+to also look at atf-c-api(3) man page.
+
+To add a new test, such as when a new module is added or when you want
+to start testing existing code, you can copy the
+server/tests/simple_unittest.c as a new new file, add the new file as
+a target in Makefile.am, and begin adding tests. Reviewing that file
+is a good idea, even if you decide to write your test from scratch, as
+it give you quick overview of the essential capabilities of the ATF
+framework (how to write test, how to make checks, pass or fail test
 etc.). Do not forget to add your new file to git via "git add
 yourtest_unittest.c".
 
@@ -190,14 +206,15 @@ yourtest_unittest.c".
 name to ATF_TESTS. The tests directory will be built only in case where
 ATF is enabled, using --with-atf during configure phase.
 
-<b>4. Modify Atffile to include your new test</b>, if needed. Tests in the
-specified directory must be registered in Atffile. See server/tests/Atffile for
-an example. Currently every executable with name of the form *_unittest will be
-executed automatically. If you followed naming convention proposed in a previous
-step, your test will be included and will be included automatically.
+<b>4. Modify Atffile to include your new test</b>, if needed. Tests in
+the specified directory must be registered in Atffile. See
+server/tests/Atffile for an example. Currently every executable with
+name of the form *_unittest will be executed automatically. If you
+followed naming convention proposed in a previous step, your test will
+be included and will be included automatically.
 
-<b>5. Enjoy your improved confidence in the code</b>, as you can run the tests after
-any change you may want to do:
+<b>5. Enjoy your improved confidence in the code</b>, as you can run
+the tests after any change you may want to do:
 
 @verbatim
 $ make check