   Installation instructions

   By Julio Merino, The NetBSD Foundation

                                    Contents

    1. Introduction

    2. Dependencies

    3. Regenerating the build system

    4. General build procedure

    5. Configuration flags

    6. Post-installation steps

                                  Introduction

   ATF uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as its
   build system. These are used only when compiling the application from the
   source code package. If you want to install ATF from a binary package, you
   do not need to read this document.

   For the impatient:

 $ ./configure
 $ make
 Gain root privileges
 # make install
 Drop root privileges
 $ make installcheck

   Or alternatively, install as a regular user into your home directory:

 $ ./configure --prefix ~/local
 $ make
 $ make install
 $ make installcheck

                                  Dependencies

   To build and use ATF successfully you need:

     * A standards-compliant C/C++ complier. For example, GNU GCC 2.95 will
       not work.

     * A POSIX shell interpreter.

     * A make(1) utility.

   If you are building ATF from the code on the repository, you will also
   need the following tools. The versions listed here are the ones used to
   build the files bundled in the last formal release, but these are not
   strictly required. Newer ones will most likely work and, maybe, some
   slightly older ones:

     * GNU autoconf 2.65

     * GNU automake 1.11.1

     * GNU libtool 2.2.6b

   If you are building the XML documentation (which is a requisite to be able
   to generate a distfile), you will also need the following tools:

     * links

     * The Simple DocBook DTD 1.1

     * tidy

     * xsltproc

     * xmlcatalog and xmllint

                         Regenerating the build system

   If you are building ATF from code extracted from the repository, you must
   first regenerate the files used by the build system. You will also need to
   do this if you modify one of configure.ac or Makefile.am.m4. To do this,
   simply run:

 $ ./autogen.sh

   For formal releases, no extra steps are needed.

                            General build procedure

   To build and install the source package, you must follow these steps:

    1. Configure the sources to adapt to your operating system. This is done
       using the 'configure' script located on the sources' top directory,
       and it is usually invoked without arguments unless you want to change
       the installation prefix. More details on this procedure are given on a
       later section.

    2. Build the sources to generate the binaries and scripts. Simply run
       'make' on the sources' top directory after configuring them. No
       problems should arise.

    3. Install the program by running 'make install'. You may need to become
       root to issue this step.

    4. Issue any manual installation steps that may be required. These are
       described later in their own section.

    5. Check that the installed programs work by running 'make installcheck'.
       You do not need to be root to do this, even though some checks will
       not be run otherwise.

                              Configuration flags

   The most common, standard flags given to 'configure' are:

     * --prefix=directory

       Possible values: Any path

       Default: /usr/local

       Specifies where the program (binaries and all associated files) will
       be installed.

     * --sysconfdir=directory

       Possible values: Any path

       Default: /usr/local/etc

       Specifies where the installed programs will look for configuration
       files. '/atf' will be appended to the given path unless ATF_CONFSUBDIR
       is redefined as explained later on.

     * --help

       Shows information about all available flags and exits immediately,
       without running any configuration tasks.

   The following environment variables are specific to ATF's 'configure'
   script:

     * ATF_BUILD_CC

       Possible values: empty, a absolute or relative path to a C compiler.

       Default: the value of CC as detected by the configure script.

       Specifies the C compiler that ATF will use at run time whenever the
       build-time-specific checks are used.

     * ATF_BUILD_CFLAGS

       Possible values: empty, a list of valid C compiler flags.

       Default: the value of CFLAGS as detected by the configure script.

       Specifies the C compiler flags that ATF will use at run time whenever
       the build-time-specific checks are used.

     * ATF_BUILD_CPP

       Possible values: empty, a absolute or relative path to a C/C++
       preprocessor.

       Default: the value of CPP as detected by the configure script.

       Specifies the C/C++ preprocessor that ATF will use at run time
       whenever the build-time-specific checks are used.

     * ATF_BUILD_CPPFLAGS

       Possible values: empty, a list of valid C/C++ preprocessor flags.

       Default: the value of CPPFLAGS as detected by the configure script.

       Specifies the C/C++ preprocessor flags that ATF will use at run time
       whenever the build-time-specific checks are used.

     * ATF_BUILD_CXX

       Possible values: empty, a absolute or relative path to a C++ compiler.

       Default: the value of CXX as detected by the configure script.

       Specifies the C++ compiler that ATF will use at run time whenever the
       build-time-specific checks are used.

     * ATF_BUILD_CXXFLAGS

       Possible values: empty, a list of valid C++ compiler flags.

       Default: the value of CXXFLAGS as detected by the configure script.

       Specifies the C++ compiler flags that ATF will use at run time
       whenever the build-time-specific checks are used.

     * ATF_CONFSUBDIR

       Possible values: empty, a relative path.

       Default: atf.

       Specifies the subdirectory of the configuration directory (given by
       the --sysconfdir argument) under which ATF will search for its
       configuration files.

     * ATF_M4

       Possible values: empty, absolute path to a M4 macro processor.

       Default: empty.

       Specifies the M4 macro processor that ATF will use at run time to
       generate GNU Automake files. If empty, the configure script will try
       to find a suitable M4 implementation for you.

     * ATF_SHELL

       Possible values: empty, absolute path to a POSIX shell interpreter.

       Default: empty.

       Specifies the POSIX shell interpreter that ATF will use at run time to
       execute its scripts and the test programs written using the atf-sh
       library. If empty, the configure script will try to find a suitable
       interpreter for you.

     * ATF_WORKDIR

       Possible values: empty, an absolute path.

       Default: /tmp or /var/tmp, depending on availability.

       Specifies the directory that ATF will use to place its temporary files
       and work directories for test cases. This is just a default and can be
       overriden at run time.

     * LINKS

       Possible values: absolute path.

       Default: links.

       Specifies the program name or the absolute path of the 'links'
       application. Required when --enable-doc-build is used; otherwise
       ignored.

     * TIDY

       Possible values: absolute path.

       Default: tidy.

       Specifies the program name or the absolute path of the 'tidy' tool.
       Required when --enable-doc-build is used; otherwise ignored.

     * XMLCATALOG

       Possible values: absolute path.

       Default: xmlcatalog.

       Specifies the program name or the absolute path of the 'xmlcatalog'
       tool. Required when --enable-doc-build is used; otherwise ignored.

     * XML_CATALOG_FILE

       Possible values: absolute path.

       Default: /etc/xml/catalog

       Specifies the path to the system-wide XML catalog used to lookup the
       required DTDs. The build will NOT perform any network access to load
       them. Required when --enable-doc-build is used; otherwise ignored.

     * XMLLINT

       Possible values: absolute path.

       Default: xmllint.

       Specifies the program name or the absolute path of the 'xmllint' tool.
       Required when --enable-doc-build is used; otherwise ignored.

     * XSLTPROC

       Possible values: absolute path.

       Default: xsltproc.

       Specifies the program name or the absolute path of the 'xsltproc'
       tool. Required when --enable-doc-build is used; otherwise ignored.

   The following flags are specific to ATF's 'configure' script:

     * --enable-developer

       Possible values: yes, no

       Default: Depends on the version number. Stable versions define this to
       'no' while all others have it set to 'yes'.

       Enables several features useful for development, such as the inclusion
       of debugging symbols in all objects or the enabling of warnings during
       compilation.

     * --enable-doc-build

       Possible values: yes, no

       Default: no.

       Enables the building of the XML documentation. This must be enabled in
       order to be able to generate a distribution file (aka run 'make
       dist'). Disabled by default because the toolchain required to enable
       this feature is pretty big, and not everyone needs it: the
       distribution files come with up-to-date, pregenerated documentation.

     * --enable-unstable-shared

       Possible values: yes, no

       Default: no.

       Forces the building of shared libraries in addition to static ones.
       The build of shared libraries is currently disabled because their ABIs
       and APIs are unstable and subject to change. This flag is provided for
       development purposes only and will be removed once the libraries are
       stable enough.

                            Post-installation steps

   After installing ATF, you have to register the DTDs it provides into the
   system-wide XML catalog. See the comments at the top of the files in
   ${datadir}/share/xml/atf to see the correct public identifiers. This
   directory will typically be /usr/local/share/xml/atf or
   /usr/share/xml/atf. Failure to do so will lead to further errors when
   processing the XML files generated by atf-report.
