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