ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntInstallation instructions Automated Testing Framework
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt===========================================================================
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntATF uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as its
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntbuild system. These are used only when compiling the application from the
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntsource code package. If you want to install ATF from a binary package, you
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntdo not need to read this document.
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntFor the impatient:
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt $ ./configure
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Gain root privileges
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt # make install
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Drop root privileges
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt $ make installcheck
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntOr alternatively, install as a regular user into your home directory:
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt $ ./configure --prefix ~/local
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt $ make install
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt $ make installcheck
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntTo build and use ATF successfully you need:
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt* A standards-compliant C/C++ complier. For example, GNU GCC 2.95 will not
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt* A POSIX shell interpreter.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt* A make(1) utility.
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntIf you are building ATF from the code on the repository, you will also need
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Huntto have GNU autoconf, automake and libtool installed.
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntRegenerating the build system
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt*****************************
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntIf you are building ATF from code extracted from the repository, you must
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntfirst regenerate the files used by the build system. You will also need to
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntdo this if you modify configure.ac, Makefile.am or any of the other build
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntsystem files. To do this, simply run:
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt $ autoreconf -i -s
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntFor formal releases, no extra steps are needed.
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntGeneral build procedure
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt***********************
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntTo build and install the source package, you must follow these steps:
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt1. Configure the sources to adapt to your operating system. This is done
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt using the 'configure' script located on the sources' top directory,
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt and it is usually invoked without arguments unless you want to change
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt the installation prefix. More details on this procedure are given on a
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt later section.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt2. Build the sources to generate the binaries and scripts. Simply run
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt 'make' on the sources' top directory after configuring them. No
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt problems should arise.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt3. Install the program by running 'make install'. You may need to become
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt root to issue this step.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt4. Issue any manual installation steps that may be required. These are
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt described later in their own section.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt5. Check that the installed programs work by running 'make installcheck'.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt You do not need to be root to do this, even though some checks will not
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt be run otherwise.
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntConfiguration flags
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt*******************
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntThe most common, standard flags given to 'configure' are:
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt* --prefix=directory
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Possible values: Any path
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Specifies where the program (binaries and all associated files) will
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt be installed.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt* --sysconfdir=directory
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Possible values: Any path
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Specifies where the installed programs will look for configuration files.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt '/atf' will be appended to the given path unless ATF_CONFSUBDIR is
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt redefined as explained later on.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Shows information about all available flags and exits immediately,
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt without running any configuration tasks.
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntThe following environment variables are specific to ATF's 'configure'
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt* ATF_BUILD_CC
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Possible values: empty, a absolute or relative path to a C compiler.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Default: the value of CC as detected by the configure script.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Specifies the C compiler that ATF will use at run time whenever the
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt build-time-specific checks are used.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt* ATF_BUILD_CFLAGS
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Possible values: empty, a list of valid C compiler flags.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Default: the value of CFLAGS as detected by the configure script.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Specifies the C compiler flags that ATF will use at run time whenever the
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt build-time-specific checks are used.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt* ATF_BUILD_CPP
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Possible values: empty, a absolute or relative path to a C/C++
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt preprocessor.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Default: the value of CPP as detected by the configure script.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Specifies the C/C++ preprocessor that ATF will use at run time whenever
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt the build-time-specific checks are used.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt* ATF_BUILD_CPPFLAGS
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Possible values: empty, a list of valid C/C++ preprocessor flags.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Default: the value of CPPFLAGS as detected by the configure script.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Specifies the C/C++ preprocessor flags that ATF will use at run time
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt whenever the build-time-specific checks are used.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt* ATF_BUILD_CXX
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Possible values: empty, a absolute or relative path to a C++ compiler.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Default: the value of CXX as detected by the configure script.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Specifies the C++ compiler that ATF will use at run time whenever the
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt build-time-specific checks are used.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt* ATF_BUILD_CXXFLAGS
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Possible values: empty, a list of valid C++ compiler flags.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Default: the value of CXXFLAGS as detected by the configure script.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Specifies the C++ compiler flags that ATF will use at run time whenever
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt the build-time-specific checks are used.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt* ATF_CONFSUBDIR
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Possible values: empty, a relative path.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Default: atf.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Specifies the subdirectory of the configuration directory (given by the
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt --sysconfdir argument) under which ATF will search for its configuration
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Possible values: empty, absolute path to a POSIX shell interpreter.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Default: empty.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Specifies the POSIX shell interpreter that ATF will use at run time to
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt execute its scripts and the test programs written using the atf-sh
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt library. If empty, the configure script will try to find a suitable
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt interpreter for you.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt* ATF_WORKDIR
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Possible values: empty, an absolute path.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Default: /tmp or /var/tmp, depending on availability.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Specifies the directory that ATF will use to place its temporary files
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt and work directories for test cases. This is just a default and can be
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt overriden at run time.
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt Possible values: empty, absolute path to GNU GDB.
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt Default: empty.
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt Specifies the path to the GNU GDB binary that atf-run will use to gather
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt a stack trace of a crashing test program. If empty, the configure script
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt will try to find a suitable binary for you.
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntThe following flags are specific to ATF's 'configure' script:
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt* --enable-developer
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Possible values: yes, no
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt Default: 'yes' in Git HEAD builds; 'no' in formal releases.
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt Enables several features useful for development, such as the inclusion
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt of debugging symbols in all objects or the enforcement of compilation
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt The compiler will be executed with an exhaustive collection of warning
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt detection features regardless of the value of this flag. However, such
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt warnings are only fatal when --enable-developer is 'yes'.
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt* --enable-tools
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Possible values: yes, no
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt Default: no.
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt Enables the build of the deprecated atf-config, atf-report, atf-run
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt and atf-version tools. atf-report and atf-run have been superseded by
a747113422afaa29ce72d2c5ba7f0b7ea9ec2054Evan Hunt Kyua, and atf-config and atf-version are unnecessary.
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntPost-installation steps
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt***********************
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntAfter installing ATF, you have to register the DTDs it provides into the
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntsystem-wide XML catalog. See the comments at the top of the files in
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt${datadir}/share/xml/atf to see the correct public identifiers. This
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntdirectory will typically be /usr/local/share/xml/atf or /usr/share/xml/atf.
ef421f66f47224a42073deaf087378c5d0c9952eEvan HuntFailure to do so will lead to further errors when processing the XML files
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntgenerated by atf-report.
ef421f66f47224a42073deaf087378c5d0c9952eEvan Hunt===========================================================================
ef421f66f47224a42073deaf087378c5d0c9952eEvan Huntvim: filetype=text:textwidth=75:expandtab:shiftwidth=2:softtabstop=2