external/bsd/atf/dist/doc/install.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
   3                   "http://docbook.org/xml/simple/1.1/sdocbook.dtd">
   4
   5 <article>
   6
   7 <articleinfo>
   8   <title>Installation instructions</title>
   9
  10   <author>
  11     <firstname>Julio</firstname>
  12     <surname>Merino</surname>
  13     <affiliation>
  14       <orgname>The NetBSD Foundation</orgname>
  15     </affiliation>
  16   </author>
  17 </articleinfo>
  18
  19 <section id="introduction">
  20
  21 <title>Introduction</title>
  22
  23 <para>ATF uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as
  24 its build system.  These are used only when compiling the application from
  25 the source code package.  If you want to install ATF from a binary package,
  26 you do not need to read this document.</para>
  27
  28 <para>For the impatient:</para>
  29
  30 <programlisting role="screen">
  31 $ <userinput>./configure</userinput>
  32 $ <userinput>make</userinput>
  33 Gain root privileges
  34 # <userinput>make install</userinput>
  35 Drop root privileges
  36 $ <userinput>make installcheck</userinput>
  37 </programlisting>
  38
  39 <para>Or alternatively, install as a regular user into your home
  40 directory:</para>
  41
  42 <programlisting role="screen">
  43 $ <userinput>./configure --prefix ~/local</userinput>
  44 $ <userinput>make</userinput>
  45 $ <userinput>make install</userinput>
  46 $ <userinput>make installcheck</userinput>
  47 </programlisting>
  48
  49 </section>
  50
  51 <section>
  52
  53 <title>Dependencies</title>
  54
  55 <para>To build and use ATF successfully you need:</para>
  56
  57 <itemizedlist>
  58
  59 <listitem><para>A standards-compliant C/C++ complier.  For example, GNU GCC
  60 2.95 will not work.</para></listitem>
  61
  62 <listitem><para>A POSIX shell interpreter.</para></listitem>
  63
  64 <listitem><para>A make(1) utility.</para></listitem>
  65
  66 </itemizedlist>
  67
  68 <para>If you are building ATF from the code on the repository, you will also need
  69 the following tools.  The versions listed here are the ones used to build
  70 the files bundled in the last formal release, but these are not strictly
  71 required.  Newer ones will most likely work and, maybe, some slightly older
  72 ones:</para>
  73
  74 <itemizedlist>
  75
  76 <listitem><para>GNU autoconf 2.65</para></listitem>
  77
  78 <listitem><para>GNU automake 1.11.1</para></listitem>
  79
  80 <listitem><para>GNU libtool 2.2.6b</para></listitem>
  81
  82 </itemizedlist>
  83
  84 <para>If you are building the XML documentation (which is a requisite to be able
  85 to generate a distfile), you will also need the following tools:</para>
  86
  87 <itemizedlist>
  88
  89 <listitem><para>links</para></listitem>
  90
  91 <listitem><para>The Simple DocBook DTD 1.1</para></listitem>
  92
  93 <listitem><para>tidy</para></listitem>
  94
  95 <listitem><para>xsltproc</para></listitem>
  96
  97 <listitem><para>xmlcatalog and xmllint</para></listitem>
  98
  99 </itemizedlist>
 100
 101 </section>
 102
 103 <section>
 104
 105 <title>Regenerating the build system</title>
 106
 107 <para>If you are building ATF from code extracted from the repository, you must
 108 first regenerate the files used by the build system.  You will also need to
 109 do this if you modify one of configure.ac or Makefile.am.m4.  To do this,
 110 simply run:</para>
 111
 112 <programlisting role="screen">
 113 $ <userinput>./autogen.sh</userinput>
 114 </programlisting>
 115
 116 <para>For formal releases, no extra steps are needed.</para>
 117
 118 </section>
 119
 120 <section>
 121
 122 <title>General build procedure</title>
 123
 124 <para>To build and install the source package, you must follow these
 125 steps:</para>
 126
 127 <orderedlist>
 128
 129 <listitem><para>Configure the sources to adapt to your operating system.
 130 This is done using the 'configure' script located on the sources' top
 131 directory, and it is usually invoked without arguments unless you want to
 132 change the installation prefix.  More details on this procedure are given
 133 on a later section.</para></listitem>
 134
 135 <listitem><para>Build the sources to generate the binaries and scripts.
 136 Simply run 'make' on the sources' top directory after configuring them.  No
 137 problems should arise.</para></listitem>
 138
 139 <listitem><para>Install the program by running 'make install'.  You may
 140 need to become root to issue this step.</para></listitem>
 141
 142 <listitem><para>Issue any manual installation steps that may be required.
 143 These are described later in their own section.</para></listitem>
 144
 145 <listitem><para>Check that the installed programs work by running 'make
 146 installcheck'.  You do not need to be root to do this, even though some
 147 checks will not be run otherwise.  (Be aware that on, some systems, GNU
 148 Libtool will break these checks.  If you get some failures, try
 149 reconfiguring the project providing the '--disable-fast-install' flag to
 150 'configure' and then rebuild and recheck.)</para></listitem>
 151
 152 </orderedlist>
 153
 154 </section>
 155
 156 <section>
 157
 158 <title>Configuration flags</title>
 159
 160 <para>The most common, standard flags given to 'configure' are:</para>
 161
 162 <variablelist>
 163
 164 <varlistentry>
 165   <term>--prefix=directory</term>
 166
 167   <listitem>
 168     <para>Possible values: Any path</para>
 169
 170     <para>Default: /usr/local</para>
 171
 172     <para>Specifies where the program (binaries and all associated files)
 173     will be installed.</para>
 174   </listitem>
 175 </varlistentry>
 176
 177 <varlistentry>
 178   <term>--sysconfdir=directory</term>
 179
 180   <listitem>
 181     <para>Possible values: Any path</para>
 182
 183     <para>Default: /usr/local/etc</para>
 184
 185     <para>Specifies where the installed programs will look for
 186     configuration files.  '/atf' will be appended to the given path unless
 187     ATF_CONFSUBDIR is redefined as explained later on.</para>
 188   </listitem>
 189 </varlistentry>
 190
 191 <varlistentry>
 192   <term>--help</term>
 193
 194   <listitem>
 195     <para>Shows information about all available flags and exits
 196     immediately, without running any configuration tasks.</para>
 197   </listitem>
 198 </varlistentry>
 199
 200 </variablelist>
 201
 202 <para>The following environment variables are specific to ATF's 'configure'
 203 script:</para>
 204
 205 <variablelist>
 206
 207 <varlistentry>
 208   <term>ATF_BUILD_CC</term>
 209
 210   <listitem>
 211     <para>Possible values: empty, a absolute or relative path to a C
 212     compiler.</para>
 213
 214     <para>Default: the value of CC as detected by the configure
 215     script.</para>
 216
 217     <para>Specifies the C compiler that ATF will use at run time whenever
 218     the build-time-specific checks are used.</para>
 219   </listitem>
 220 </varlistentry>
 221
 222 <varlistentry>
 223   <term>ATF_BUILD_CFLAGS</term>
 224
 225   <listitem>
 226     <para>Possible values: empty, a list of valid C compiler flags.</para>
 227
 228     <para>Default: the value of CFLAGS as detected by the configure
 229     script.</para>
 230
 231     <para>Specifies the C compiler flags that ATF will use at run time
 232     whenever the build-time-specific checks are used.</para>
 233   </listitem>
 234 </varlistentry>
 235
 236 <varlistentry>
 237   <term>ATF_BUILD_CPP</term>
 238
 239   <listitem>
 240     <para>Possible values: empty, a absolute or relative path to a C/C++
 241     preprocessor.</para> <para>Default: the value of CPP as detected by the
 242     configure script.</para>
 243
 244     <para>Specifies the C/C++ preprocessor that ATF will use at run time
 245     whenever the build-time-specific checks are used.</para>
 246   </listitem>
 247 </varlistentry>
 248
 249 <varlistentry>
 250   <term>ATF_BUILD_CPPFLAGS</term>
 251
 252   <listitem>
 253     <para>Possible values: empty, a list of valid C/C++ preprocessor
 254     flags.</para>
 255
 256     <para>Default: the value of CPPFLAGS as detected by the configure
 257     script.</para>
 258
 259     <para>Specifies the C/C++ preprocessor flags that ATF will use at run
 260     time whenever the build-time-specific checks are used.</para>
 261   </listitem>
 262 </varlistentry>
 263
 264 <varlistentry>
 265   <term>ATF_BUILD_CXX</term>
 266
 267   <listitem>
 268     <para>Possible values: empty, a absolute or relative path to a C++
 269     compiler.</para>
 270
 271     <para>Default: the value of CXX as detected by the configure
 272     script.</para>
 273
 274     <para>Specifies the C++ compiler that ATF will use at run time whenever
 275     the build-time-specific checks are used.</para>
 276   </listitem>
 277 </varlistentry>
 278
 279 <varlistentry>
 280   <term>ATF_BUILD_CXXFLAGS</term>
 281
 282   <listitem>
 283     <para>Possible values: empty, a list of valid C++ compiler
 284     flags.</para>
 285
 286     <para>Default: the value of CXXFLAGS as detected by the configure
 287     script.</para>
 288
 289     <para>Specifies the C++ compiler flags that ATF will use at run time
 290     whenever the build-time-specific checks are used.</para>
 291   </listitem>
 292 </varlistentry>
 293
 294 <varlistentry>
 295   <term>ATF_CONFSUBDIR</term>
 296
 297   <listitem>
 298     <para>Possible values: empty, a relative path.</para>
 299
 300     <para>Default: atf.</para>
 301
 302     <para>Specifies the subdirectory of the configuration directory (given
 303     by the --sysconfdir argument) under which ATF will search for its
 304     configuration files.</para>
 305   </listitem>
 306 </varlistentry>
 307
 308 <varlistentry>
 309   <term>ATF_M4</term>
 310
 311   <listitem>
 312     <para>Possible values: empty, absolute path to a M4 macro
 313     processor.</para>
 314
 315     <para>Default: empty.</para>
 316
 317     <para>Specifies the M4 macro processor that ATF will use at run time to
 318     generate GNU Automake files.  If empty, the configure script will try
 319     to find a suitable M4 implementation for you.</para>
 320   </listitem>
 321 </varlistentry>
 322
 323 <varlistentry>
 324   <term>ATF_SHELL</term>
 325
 326   <listitem>
 327     <para>Possible values: empty, absolute path to a POSIX shell
 328     interpreter.</para>
 329
 330     <para>Default: empty.</para>
 331
 332     <para>Specifies the POSIX shell interpreter that ATF will use at run
 333     time to execute its scripts and the test programs written using the
 334     atf-sh library.  If empty, the configure script will try to find a
 335     suitable interpreter for you.</para>
 336   </listitem>
 337 </varlistentry>
 338
 339 <varlistentry>
 340   <term>ATF_WORKDIR</term>
 341
 342   <listitem>
 343     <para>Possible values: empty, an absolute path.</para>
 344
 345     <para>Default: /tmp or /var/tmp, depending on availability.</para>
 346
 347     <para>Specifies the directory that ATF will use to place its temporary
 348     files and work directories for test cases.  This is just a default and
 349     can be overriden at run time.</para>
 350   </listitem>
 351 </varlistentry>
 352
 353 <varlistentry>
 354   <term>LINKS</term>
 355
 356   <listitem>
 357     <para>Possible values: absolute path.</para>
 358
 359     <para>Default: links.</para>
 360
 361     <para>Specifies the program name or the absolute path of the 'links'
 362     application.  Required when --enable-doc-build is used; otherwise
 363     ignored.</para>
 364   </listitem>
 365 </varlistentry>
 366
 367 <varlistentry>
 368   <term>TIDY</term>
 369
 370   <listitem>
 371     <para>Possible values: absolute path.</para>
 372
 373     <para>Default: tidy.</para>
 374
 375     <para>Specifies the program name or the absolute path of the 'tidy'
 376     tool.  Required when --enable-doc-build is used; otherwise
 377     ignored.</para>
 378   </listitem>
 379 </varlistentry>
 380
 381 <varlistentry>
 382   <term>XMLCATALOG</term>
 383
 384   <listitem>
 385     <para>Possible values: absolute path.</para>
 386
 387     <para>Default: xmlcatalog.</para>
 388
 389     <para>Specifies the program name or the absolute path of the
 390     'xmlcatalog' tool.  Required when --enable-doc-build is used; otherwise
 391     ignored.</para>
 392   </listitem>
 393 </varlistentry>
 394
 395 <varlistentry>
 396   <term>XML_CATALOG_FILE</term>
 397
 398   <listitem>
 399     <para>Possible values: absolute path.</para>
 400
 401     <para>Default: /etc/xml/catalog</para>
 402
 403     <para>Specifies the path to the system-wide XML catalog used to lookup
 404     the required DTDs.  The build will NOT perform any network access to
 405     load them.  Required when --enable-doc-build is used; otherwise
 406     ignored.</para>
 407   </listitem>
 408 </varlistentry>
 409
 410 <varlistentry>
 411   <term>XMLLINT</term>
 412
 413   <listitem>
 414     <para>Possible values: absolute path.</para>
 415
 416     <para>Default: xmllint.</para>
 417
 418     <para>Specifies the program name or the absolute path of the 'xmllint'
 419     tool.  Required when --enable-doc-build is used; otherwise
 420     ignored.</para>
 421   </listitem>
 422 </varlistentry>
 423
 424 <varlistentry>
 425   <term>XSLTPROC</term>
 426
 427   <listitem>
 428     <para>Possible values: absolute path.</para>
 429
 430     <para>Default: xsltproc.</para>
 431
 432     <para>Specifies the program name or the absolute path of the 'xsltproc'
 433     tool.  Required when --enable-doc-build is used; otherwise
 434     ignored.</para>
 435   </listitem>
 436 </varlistentry>
 437
 438 </variablelist>
 439
 440 <para>The following flags are specific to ATF's 'configure' script:</para>
 441
 442 <variablelist>
 443
 444 <varlistentry>
 445   <term>--enable-developer</term>
 446   <listitem>
 447     <para>Possible values: yes, no</para>
 448
 449     <para>Default: Depends on the version number.  Stable versions define
 450     this to 'no' while all others have it set to 'yes'.</para>
 451
 452     <para>Enables several features useful for development, such as the
 453     inclusion of debugging symbols in all objects or the enabling of
 454     warnings during compilation.</para>
 455   </listitem>
 456 </varlistentry>
 457
 458 <varlistentry>
 459   <term>--enable-doc-build</term>
 460   <listitem>
 461     <para>Possible values: yes, no</para>
 462
 463     <para>Default: no.</para>
 464
 465     <para>Enables the building of the XML documentation.  This must be
 466     enabled in order to be able to generate a distribution file (aka run
 467     'make dist').  Disabled by default because the toolchain required to
 468     enable this feature is pretty big, and not everyone needs it: the
 469     distribution files come with up-to-date, pregenerated
 470     documentation.</para>
 471   </listitem>
 472 </varlistentry>
 473
 474 <varlistentry>
 475   <term>--enable-unstable-shared</term>
 476   <listitem>
 477     <para>Possible values: yes, no</para>
 478
 479     <para>Default: no.</para>
 480
 481     <para>Forces the building of shared libraries in addition to static
 482     ones.  The build of shared libraries is currently disabled because
 483     their ABIs and APIs are unstable and subject to change.  This flag is
 484     provided for development purposes only and will be removed once the
 485     libraries are stable enough.</para>
 486   </listitem>
 487 </varlistentry>
 488
 489 </variablelist>
 490
 491 </section>
 492
 493 <section>
 494
 495 <title>Post-installation steps</title>
 496
 497 <para>After installing ATF, you have to register the DTDs it provides into
 498 the system-wide XML catalog.  See the comments at the top of the files in
 499 ${datadir}/share/xml/atf to see the correct public identifiers.  This
 500 directory will typically be /usr/local/share/xml/atf or /usr/share/xml/atf.
 501 Failure to do so will lead to further errors when processing the XML files
 502 generated by atf-report.</para>
 503
 504 </section>
 505
 506 </article>