68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncInstallation instructions Automated Testing Framework

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync===========================================================================

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncIntroduction

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync************

c7814cf6e1240a519cbec0441e033d0e2470ed00vboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncATF uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as its

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncbuild system. These are used only when compiling the application from the

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncsource code package. If you want to install ATF from a binary package, you

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncdo not need to read this document.

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncFor the impatient:

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync $ ./configure

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync $ make

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync Gain root privileges

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync # make install

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync Drop root privileges

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync $ make installcheck

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

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

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync $ ./configure --prefix ~/local

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync $ make

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync $ make install

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync $ make installcheck

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncDependencies

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync************

715e49c31b15c23c17a9ce3be42a75e7c48d4b78vboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncTo build and use ATF successfully you need:

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

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

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync work.

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync* A POSIX shell interpreter.

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync* A make(1) utility.

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncIf you are building ATF from the code on the repository, you will also need

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncto have GNU autoconf, automake and libtool installed.

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncRegenerating the build system

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync*****************************

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncIf you are building ATF from code extracted from the repository, you must

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncfirst regenerate the files used by the build system. You will also need to

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncdo this if you modify configure.ac, Makefile.am or any of the other build

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsyncsystem files. To do this, simply run:

68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync

$ 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.

* GDB

Possible values: empty, absolute path to GNU GDB.

Default: empty.

Specifies the path to the GNU GDB binary that atf-run will use to gather

a stack trace of a crashing test program. If empty, the configure script

will try to find a suitable binary for you.

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

* --enable-developer

Possible values: yes, no

Default: 'yes' in Git HEAD builds; 'no' in formal releases.

Enables several features useful for development, such as the inclusion

of debugging symbols in all objects or the enforcement of compilation

warnings.

The compiler will be executed with an exhaustive collection of warning

detection features regardless of the value of this flag. However, such

warnings are only fatal when --enable-developer is 'yes'.

* --enable-tools

Possible values: yes, no

Default: no.

Enables the build of the deprecated atf-config, atf-report, atf-run

and atf-version tools. atf-report and atf-run have been superseded by

Kyua, and atf-config and atf-version are unnecessary.

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