1Installation instructions Automated Testing Framework 2=========================================================================== 3 4 5Introduction 6************ 7 8ATF uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as its 9build system. These are used only when compiling the application from the 10source code package. If you want to install ATF from a binary package, you 11do not need to read this document. 12 13For the impatient: 14 15 $ ./configure 16 $ make 17 Gain root privileges 18 # make install 19 Drop root privileges 20 $ make installcheck 21 22Or alternatively, install as a regular user into your home directory: 23 24 $ ./configure --prefix ~/local 25 $ make 26 $ make install 27 $ make installcheck 28 29 30Dependencies 31************ 32 33To build and use ATF successfully you need: 34 35* A standards-compliant C/C++ complier. For example, GNU GCC 2.95 will not 36 work. 37 38* A POSIX shell interpreter. 39 40* A make(1) utility. 41 42If you are building ATF from the code on the repository, you will also need 43to have GNU autoconf, automake and libtool installed. 44 45 46Regenerating the build system 47***************************** 48 49If you are building ATF from code extracted from the repository, you must 50first regenerate the files used by the build system. You will also need to 51do this if you modify configure.ac, Makefile.am or any of the other build 52system files. To do this, simply run: 53 54 $ autoreconf -i -s 55 56For formal releases, no extra steps are needed. 57 58 59General build procedure 60*********************** 61 62To build and install the source package, you must follow these steps: 63 641. Configure the sources to adapt to your operating system. This is done 65 using the 'configure' script located on the sources' top directory, 66 and it is usually invoked without arguments unless you want to change 67 the installation prefix. More details on this procedure are given on a 68 later section. 69 702. Build the sources to generate the binaries and scripts. Simply run 71 'make' on the sources' top directory after configuring them. No 72 problems should arise. 73 743. Install the program by running 'make install'. You may need to become 75 root to issue this step. 76 774. Issue any manual installation steps that may be required. These are 78 described later in their own section. 79 805. Check that the installed programs work by running 'make installcheck'. 81 You do not need to be root to do this, even though some checks will not 82 be run otherwise. 83 84 85Configuration flags 86******************* 87 88The most common, standard flags given to 'configure' are: 89 90* --prefix=directory 91 Possible values: Any path 92 Default: /usr/local 93 94 Specifies where the program (binaries and all associated files) will 95 be installed. 96 97* --sysconfdir=directory 98 Possible values: Any path 99 Default: /usr/local/etc 100 101 Specifies where the installed programs will look for configuration files. 102 '/atf' will be appended to the given path unless ATF_CONFSUBDIR is 103 redefined as explained later on. 104 105* --help 106 Shows information about all available flags and exits immediately, 107 without running any configuration tasks. 108 109The following environment variables are specific to ATF's 'configure' 110script: 111 112* ATF_BUILD_CC 113 Possible values: empty, a absolute or relative path to a C compiler. 114 Default: the value of CC as detected by the configure script. 115 116 Specifies the C compiler that ATF will use at run time whenever the 117 build-time-specific checks are used. 118 119* ATF_BUILD_CFLAGS 120 Possible values: empty, a list of valid C compiler flags. 121 Default: the value of CFLAGS as detected by the configure script. 122 123 Specifies the C compiler flags that ATF will use at run time whenever the 124 build-time-specific checks are used. 125 126* ATF_BUILD_CPP 127 Possible values: empty, a absolute or relative path to a C/C++ 128 preprocessor. 129 Default: the value of CPP as detected by the configure script. 130 131 Specifies the C/C++ preprocessor that ATF will use at run time whenever 132 the build-time-specific checks are used. 133 134* ATF_BUILD_CPPFLAGS 135 Possible values: empty, a list of valid C/C++ preprocessor flags. 136 Default: the value of CPPFLAGS as detected by the configure script. 137 138 Specifies the C/C++ preprocessor flags that ATF will use at run time 139 whenever the build-time-specific checks are used. 140 141* ATF_BUILD_CXX 142 Possible values: empty, a absolute or relative path to a C++ compiler. 143 Default: the value of CXX as detected by the configure script. 144 145 Specifies the C++ compiler that ATF will use at run time whenever the 146 build-time-specific checks are used. 147 148* ATF_BUILD_CXXFLAGS 149 Possible values: empty, a list of valid C++ compiler flags. 150 Default: the value of CXXFLAGS as detected by the configure script. 151 152 Specifies the C++ compiler flags that ATF will use at run time whenever 153 the build-time-specific checks are used. 154 155* ATF_CONFSUBDIR 156 Possible values: empty, a relative path. 157 Default: atf. 158 159 Specifies the subdirectory of the configuration directory (given by the 160 --sysconfdir argument) under which ATF will search for its configuration 161 files. 162 163* ATF_SHELL 164 Possible values: empty, absolute path to a POSIX shell interpreter. 165 Default: empty. 166 167 Specifies the POSIX shell interpreter that ATF will use at run time to 168 execute its scripts and the test programs written using the atf-sh 169 library. If empty, the configure script will try to find a suitable 170 interpreter for you. 171 172* ATF_WORKDIR 173 Possible values: empty, an absolute path. 174 Default: /tmp or /var/tmp, depending on availability. 175 176 Specifies the directory that ATF will use to place its temporary files 177 and work directories for test cases. This is just a default and can be 178 overriden at run time. 179 180* GDB 181 Possible values: empty, absolute path to GNU GDB. 182 Default: empty. 183 184 Specifies the path to the GNU GDB binary that atf-run will use to gather 185 a stack trace of a crashing test program. If empty, the configure script 186 will try to find a suitable binary for you. 187 188The following flags are specific to ATF's 'configure' script: 189 190* --enable-developer 191 Possible values: yes, no 192 Default: 'yes' in Git HEAD builds; 'no' in formal releases. 193 194 Enables several features useful for development, such as the inclusion 195 of debugging symbols in all objects or the enforcement of compilation 196 warnings. 197 198 The compiler will be executed with an exhaustive collection of warning 199 detection features regardless of the value of this flag. However, such 200 warnings are only fatal when --enable-developer is 'yes'. 201 202* --enable-tools 203 Possible values: yes, no 204 Default: no. 205 206 Enables the build of the deprecated atf-config, atf-report, atf-run 207 and atf-version tools. atf-report and atf-run have been superseded by 208 Kyua, and atf-config and atf-version are unnecessary. 209 210 211Post-installation steps 212*********************** 213 214After installing ATF, you have to register the DTDs it provides into the 215system-wide XML catalog. See the comments at the top of the files in 216${datadir}/share/xml/atf to see the correct public identifiers. This 217directory will typically be /usr/local/share/xml/atf or /usr/share/xml/atf. 218Failure to do so will lead to further errors when processing the XML files 219generated by atf-report. 220 221 222=========================================================================== 223vim: filetype=text:textwidth=75:expandtab:shiftwidth=2:softtabstop=2 224