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