Installation instructions Automated Testing Framework
===========================================================================
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.68
* GNU automake 1.11.1
* GNU libtool 2.2.6b
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 configure.ac, Makefile.am or any of the other build
system files. To do this, simply run:
$ autoreconf -i -s
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_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.
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-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.
===========================================================================
vim: filetype=text:textwidth=75:expandtab:shiftwidth=2:softtabstop=2