external/bsd/bind/dist/unit/atf-src/INSTALL

   1 Installation instructions                       Automated Testing Framework
   2 ===========================================================================
   3
   4
   5 Introduction
   6 ************
   7
   8 ATF uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as its
   9 build system.  These are used only when compiling the application from the
  10 source code package.  If you want to install ATF from a binary package, you
  11 do not need to read this document.
  12
  13 For the impatient:
  14
  15   $ ./configure
  16   $ make
  17   Gain root privileges
  18   # make install
  19   Drop root privileges
  20   $ make installcheck
  21
  22 Or 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
  30 Dependencies
  31 ************
  32
  33 To 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
  42 If you are building ATF from the code on the repository, you will also need
  43 to have GNU autoconf, automake and libtool installed.
  44
  45
  46 Regenerating the build system
  47 *****************************
  48
  49 If you are building ATF from code extracted from the repository, you must
  50 first regenerate the files used by the build system.  You will also need to
  51 do this if you modify configure.ac, Makefile.am or any of the other build
  52 system files.  To do this, simply run:
  53
  54   $ autoreconf -i -s
  55
  56 For formal releases, no extra steps are needed.
  57
  58
  59 General build procedure
  60 ***********************
  61
  62 To build and install the source package, you must follow these steps:
  63
  64 1. 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
  70 2. 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
  74 3. Install the program by running 'make install'.  You may need to become
  75    root to issue this step.
  76
  77 4. Issue any manual installation steps that may be required.  These are
  78    described later in their own section.
  79
  80 5. 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
  85 Configuration flags
  86 *******************
  87
  88 The 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
 109 The following environment variables are specific to ATF's 'configure'
 110 script:
 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
 188 The 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
 211 Post-installation steps
 212 ***********************
 213
 214 After installing ATF, you have to register the DTDs it provides into the
 215 system-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
 217 directory will typically be /usr/local/share/xml/atf or /usr/share/xml/atf.
 218 Failure to do so will lead to further errors when processing the XML files
 219 generated by atf-report.
 220
 221
 222 ===========================================================================
 223 vim: filetype=text:textwidth=75:expandtab:shiftwidth=2:softtabstop=2