external/bsd/atf/dist/INSTALL

   1    Installation instructions
   2
   3    By Julio Merino, The NetBSD Foundation
   4
   5                                     Contents
   6
   7     1. Introduction
   8
   9     2. Dependencies
  10
  11     3. Regenerating the build system
  12
  13     4. General build procedure
  14
  15     5. Configuration flags
  16
  17     6. Post-installation steps
  18
  19                                   Introduction
  20
  21    ATF uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as its
  22    build system. These are used only when compiling the application from the
  23    source code package. If you want to install ATF from a binary package, you
  24    do not need to read this document.
  25
  26    For the impatient:
  27
  28  $ ./configure
  29  $ make
  30  Gain root privileges
  31  # make install
  32  Drop root privileges
  33  $ make installcheck
  34
  35    Or alternatively, install as a regular user into your home directory:
  36
  37  $ ./configure --prefix ~/local
  38  $ make
  39  $ make install
  40  $ make installcheck
  41
  42                                   Dependencies
  43
  44    To build and use ATF successfully you need:
  45
  46      * A standards-compliant C/C++ complier. For example, GNU GCC 2.95 will
  47        not work.
  48
  49      * A POSIX shell interpreter.
  50
  51      * A make(1) utility.
  52
  53    If you are building ATF from the code on the repository, you will also
  54    need the following tools. The versions listed here are the ones used to
  55    build the files bundled in the last formal release, but these are not
  56    strictly required. Newer ones will most likely work and, maybe, some
  57    slightly older ones:
  58
  59      * GNU autoconf 2.65
  60
  61      * GNU automake 1.11.1
  62
  63      * GNU libtool 2.2.6b
  64
  65    If you are building the XML documentation (which is a requisite to be able
  66    to generate a distfile), you will also need the following tools:
  67
  68      * links
  69
  70      * The Simple DocBook DTD 1.1
  71
  72      * tidy
  73
  74      * xsltproc
  75
  76      * xmlcatalog and xmllint
  77
  78                          Regenerating the build system
  79
  80    If you are building ATF from code extracted from the repository, you must
  81    first regenerate the files used by the build system. You will also need to
  82    do this if you modify one of configure.ac or Makefile.am.m4. To do this,
  83    simply run:
  84
  85  $ ./autogen.sh
  86
  87    For formal releases, no extra steps are needed.
  88
  89                             General build procedure
  90
  91    To build and install the source package, you must follow these steps:
  92
  93     1. Configure the sources to adapt to your operating system. This is done
  94        using the 'configure' script located on the sources' top directory,
  95        and it is usually invoked without arguments unless you want to change
  96        the installation prefix. More details on this procedure are given on a
  97        later section.
  98
  99     2. Build the sources to generate the binaries and scripts. Simply run
 100        'make' on the sources' top directory after configuring them. No
 101        problems should arise.
 102
 103     3. Install the program by running 'make install'. You may need to become
 104        root to issue this step.
 105
 106     4. Issue any manual installation steps that may be required. These are
 107        described later in their own section.
 108
 109     5. Check that the installed programs work by running 'make installcheck'.
 110        You do not need to be root to do this, even though some checks will
 111        not be run otherwise. (Be aware that on, some systems, GNU Libtool
 112        will break these checks. If you get some failures, try reconfiguring
 113        the project providing the '--disable-fast-install' flag to 'configure'
 114        and then rebuild and recheck.)
 115
 116                               Configuration flags
 117
 118    The most common, standard flags given to 'configure' are:
 119
 120      * --prefix=directory
 121
 122        Possible values: Any path
 123
 124        Default: /usr/local
 125
 126        Specifies where the program (binaries and all associated files) will
 127        be installed.
 128
 129      * --sysconfdir=directory
 130
 131        Possible values: Any path
 132
 133        Default: /usr/local/etc
 134
 135        Specifies where the installed programs will look for configuration
 136        files. '/atf' will be appended to the given path unless ATF_CONFSUBDIR
 137        is redefined as explained later on.
 138
 139      * --help
 140
 141        Shows information about all available flags and exits immediately,
 142        without running any configuration tasks.
 143
 144    The following environment variables are specific to ATF's 'configure'
 145    script:
 146
 147      * ATF_BUILD_CC
 148
 149        Possible values: empty, a absolute or relative path to a C compiler.
 150
 151        Default: the value of CC as detected by the configure script.
 152
 153        Specifies the C compiler that ATF will use at run time whenever the
 154        build-time-specific checks are used.
 155
 156      * ATF_BUILD_CFLAGS
 157
 158        Possible values: empty, a list of valid C compiler flags.
 159
 160        Default: the value of CFLAGS as detected by the configure script.
 161
 162        Specifies the C compiler flags that ATF will use at run time whenever
 163        the build-time-specific checks are used.
 164
 165      * ATF_BUILD_CPP
 166
 167        Possible values: empty, a absolute or relative path to a C/C++
 168        preprocessor.
 169
 170        Default: the value of CPP as detected by the configure script.
 171
 172        Specifies the C/C++ preprocessor that ATF will use at run time
 173        whenever the build-time-specific checks are used.
 174
 175      * ATF_BUILD_CPPFLAGS
 176
 177        Possible values: empty, a list of valid C/C++ preprocessor flags.
 178
 179        Default: the value of CPPFLAGS as detected by the configure script.
 180
 181        Specifies the C/C++ preprocessor flags that ATF will use at run time
 182        whenever the build-time-specific checks are used.
 183
 184      * ATF_BUILD_CXX
 185
 186        Possible values: empty, a absolute or relative path to a C++ compiler.
 187
 188        Default: the value of CXX as detected by the configure script.
 189
 190        Specifies the C++ compiler that ATF will use at run time whenever the
 191        build-time-specific checks are used.
 192
 193      * ATF_BUILD_CXXFLAGS
 194
 195        Possible values: empty, a list of valid C++ compiler flags.
 196
 197        Default: the value of CXXFLAGS as detected by the configure script.
 198
 199        Specifies the C++ compiler flags that ATF will use at run time
 200        whenever the build-time-specific checks are used.
 201
 202      * ATF_CONFSUBDIR
 203
 204        Possible values: empty, a relative path.
 205
 206        Default: atf.
 207
 208        Specifies the subdirectory of the configuration directory (given by
 209        the --sysconfdir argument) under which ATF will search for its
 210        configuration files.
 211
 212      * ATF_M4
 213
 214        Possible values: empty, absolute path to a M4 macro processor.
 215
 216        Default: empty.
 217
 218        Specifies the M4 macro processor that ATF will use at run time to
 219        generate GNU Automake files. If empty, the configure script will try
 220        to find a suitable M4 implementation for you.
 221
 222      * ATF_SHELL
 223
 224        Possible values: empty, absolute path to a POSIX shell interpreter.
 225
 226        Default: empty.
 227
 228        Specifies the POSIX shell interpreter that ATF will use at run time to
 229        execute its scripts and the test programs written using the atf-sh
 230        library. If empty, the configure script will try to find a suitable
 231        interpreter for you.
 232
 233      * ATF_WORKDIR
 234
 235        Possible values: empty, an absolute path.
 236
 237        Default: /tmp or /var/tmp, depending on availability.
 238
 239        Specifies the directory that ATF will use to place its temporary files
 240        and work directories for test cases. This is just a default and can be
 241        overriden at run time.
 242
 243      * LINKS
 244
 245        Possible values: absolute path.
 246
 247        Default: links.
 248
 249        Specifies the program name or the absolute path of the 'links'
 250        application. Required when --enable-doc-build is used; otherwise
 251        ignored.
 252
 253      * TIDY
 254
 255        Possible values: absolute path.
 256
 257        Default: tidy.
 258
 259        Specifies the program name or the absolute path of the 'tidy' tool.
 260        Required when --enable-doc-build is used; otherwise ignored.
 261
 262      * XMLCATALOG
 263
 264        Possible values: absolute path.
 265
 266        Default: xmlcatalog.
 267
 268        Specifies the program name or the absolute path of the 'xmlcatalog'
 269        tool. Required when --enable-doc-build is used; otherwise ignored.
 270
 271      * XML_CATALOG_FILE
 272
 273        Possible values: absolute path.
 274
 275        Default: /etc/xml/catalog
 276
 277        Specifies the path to the system-wide XML catalog used to lookup the
 278        required DTDs. The build will NOT perform any network access to load
 279        them. Required when --enable-doc-build is used; otherwise ignored.
 280
 281      * XMLLINT
 282
 283        Possible values: absolute path.
 284
 285        Default: xmllint.
 286
 287        Specifies the program name or the absolute path of the 'xmllint' tool.
 288        Required when --enable-doc-build is used; otherwise ignored.
 289
 290      * XSLTPROC
 291
 292        Possible values: absolute path.
 293
 294        Default: xsltproc.
 295
 296        Specifies the program name or the absolute path of the 'xsltproc'
 297        tool. Required when --enable-doc-build is used; otherwise ignored.
 298
 299    The following flags are specific to ATF's 'configure' script:
 300
 301      * --enable-developer
 302
 303        Possible values: yes, no
 304
 305        Default: Depends on the version number. Stable versions define this to
 306        'no' while all others have it set to 'yes'.
 307
 308        Enables several features useful for development, such as the inclusion
 309        of debugging symbols in all objects or the enabling of warnings during
 310        compilation.
 311
 312      * --enable-doc-build
 313
 314        Possible values: yes, no
 315
 316        Default: no.
 317
 318        Enables the building of the XML documentation. This must be enabled in
 319        order to be able to generate a distribution file (aka run 'make
 320        dist'). Disabled by default because the toolchain required to enable
 321        this feature is pretty big, and not everyone needs it: the
 322        distribution files come with up-to-date, pregenerated documentation.
 323
 324      * --enable-unstable-shared
 325
 326        Possible values: yes, no
 327
 328        Default: no.
 329
 330        Forces the building of shared libraries in addition to static ones.
 331        The build of shared libraries is currently disabled because their ABIs
 332        and APIs are unstable and subject to change. This flag is provided for
 333        development purposes only and will be removed once the libraries are
 334        stable enough.
 335
 336                             Post-installation steps
 337
 338    After installing ATF, you have to register the DTDs it provides into the
 339    system-wide XML catalog. See the comments at the top of the files in
 340    ${datadir}/share/xml/atf to see the correct public identifiers. This
 341    directory will typically be /usr/local/share/xml/atf or
 342    /usr/share/xml/atf. Failure to do so will lead to further errors when
 343    processing the XML files generated by atf-report.