INSTALL
author ali <ali@juiblex.co.uk>
Sat Feb 18 17:08:22 2012 +0000 (2012-02-18)
changeset 24 adf633a3ae6f
permissions -rw-r--r--
Testcases for short and long lines
ali@0
     1
Installation Instructions
ali@0
     2
*************************
ali@0
     3
ali@0
     4
Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005,
ali@0
     5
2006, 2007, 2008, 2009 Free Software Foundation, Inc.
ali@0
     6
ali@0
     7
   Copying and distribution of this file, with or without modification,
ali@0
     8
are permitted in any medium without royalty provided the copyright
ali@0
     9
notice and this notice are preserved.  This file is offered as-is,
ali@0
    10
without warranty of any kind.
ali@0
    11
ali@0
    12
Basic Installation
ali@0
    13
==================
ali@0
    14
ali@0
    15
   Briefly, the shell commands `./configure; make; make install' should
ali@0
    16
configure, build, and install this package.  The following
ali@0
    17
more-detailed instructions are generic; see the `README' file for
ali@0
    18
instructions specific to this package.  Some packages provide this
ali@0
    19
`INSTALL' file but do not implement all of the features documented
ali@0
    20
below.  The lack of an optional feature in a given package is not
ali@0
    21
necessarily a bug.  More recommendations for GNU packages can be found
ali@0
    22
in *note Makefile Conventions: (standards)Makefile Conventions.
ali@0
    23
ali@0
    24
   The `configure' shell script attempts to guess correct values for
ali@0
    25
various system-dependent variables used during compilation.  It uses
ali@0
    26
those values to create a `Makefile' in each directory of the package.
ali@0
    27
It may also create one or more `.h' files containing system-dependent
ali@0
    28
definitions.  Finally, it creates a shell script `config.status' that
ali@0
    29
you can run in the future to recreate the current configuration, and a
ali@0
    30
file `config.log' containing compiler output (useful mainly for
ali@0
    31
debugging `configure').
ali@0
    32
ali@0
    33
   It can also use an optional file (typically called `config.cache'
ali@0
    34
and enabled with `--cache-file=config.cache' or simply `-C') that saves
ali@0
    35
the results of its tests to speed up reconfiguring.  Caching is
ali@0
    36
disabled by default to prevent problems with accidental use of stale
ali@0
    37
cache files.
ali@0
    38
ali@0
    39
   If you need to do unusual things to compile the package, please try
ali@0
    40
to figure out how `configure' could check whether to do them, and mail
ali@0
    41
diffs or instructions to the address given in the `README' so they can
ali@0
    42
be considered for the next release.  If you are using the cache, and at
ali@0
    43
some point `config.cache' contains results you don't want to keep, you
ali@0
    44
may remove or edit it.
ali@0
    45
ali@0
    46
   The file `configure.ac' (or `configure.in') is used to create
ali@0
    47
`configure' by a program called `autoconf'.  You need `configure.ac' if
ali@0
    48
you want to change it or regenerate `configure' using a newer version
ali@0
    49
of `autoconf'.
ali@0
    50
ali@0
    51
   The simplest way to compile this package is:
ali@0
    52
ali@0
    53
  1. `cd' to the directory containing the package's source code and type
ali@0
    54
     `./configure' to configure the package for your system.
ali@0
    55
ali@0
    56
     Running `configure' might take a while.  While running, it prints
ali@0
    57
     some messages telling which features it is checking for.
ali@0
    58
ali@0
    59
  2. Type `make' to compile the package.
ali@0
    60
ali@0
    61
  3. Optionally, type `make check' to run any self-tests that come with
ali@0
    62
     the package, generally using the just-built uninstalled binaries.
ali@0
    63
ali@0
    64
  4. Type `make install' to install the programs and any data files and
ali@0
    65
     documentation.  When installing into a prefix owned by root, it is
ali@0
    66
     recommended that the package be configured and built as a regular
ali@0
    67
     user, and only the `make install' phase executed with root
ali@0
    68
     privileges.
ali@0
    69
ali@0
    70
  5. Optionally, type `make installcheck' to repeat any self-tests, but
ali@0
    71
     this time using the binaries in their final installed location.
ali@0
    72
     This target does not install anything.  Running this target as a
ali@0
    73
     regular user, particularly if the prior `make install' required
ali@0
    74
     root privileges, verifies that the installation completed
ali@0
    75
     correctly.
ali@0
    76
ali@0
    77
  6. You can remove the program binaries and object files from the
ali@0
    78
     source code directory by typing `make clean'.  To also remove the
ali@0
    79
     files that `configure' created (so you can compile the package for
ali@0
    80
     a different kind of computer), type `make distclean'.  There is
ali@0
    81
     also a `make maintainer-clean' target, but that is intended mainly
ali@0
    82
     for the package's developers.  If you use it, you may have to get
ali@0
    83
     all sorts of other programs in order to regenerate files that came
ali@0
    84
     with the distribution.
ali@0
    85
ali@0
    86
  7. Often, you can also type `make uninstall' to remove the installed
ali@0
    87
     files again.  In practice, not all packages have tested that
ali@0
    88
     uninstallation works correctly, even though it is required by the
ali@0
    89
     GNU Coding Standards.
ali@0
    90
ali@0
    91
  8. Some packages, particularly those that use Automake, provide `make
ali@0
    92
     distcheck', which can by used by developers to test that all other
ali@0
    93
     targets like `make install' and `make uninstall' work correctly.
ali@0
    94
     This target is generally not run by end users.
ali@0
    95
ali@0
    96
Compilers and Options
ali@0
    97
=====================
ali@0
    98
ali@0
    99
   Some systems require unusual options for compilation or linking that
ali@0
   100
the `configure' script does not know about.  Run `./configure --help'
ali@0
   101
for details on some of the pertinent environment variables.
ali@0
   102
ali@0
   103
   You can give `configure' initial values for configuration parameters
ali@0
   104
by setting variables in the command line or in the environment.  Here
ali@0
   105
is an example:
ali@0
   106
ali@0
   107
     ./configure CC=c99 CFLAGS=-g LIBS=-lposix
ali@0
   108
ali@0
   109
   *Note Defining Variables::, for more details.
ali@0
   110
ali@0
   111
Compiling For Multiple Architectures
ali@0
   112
====================================
ali@0
   113
ali@0
   114
   You can compile the package for more than one kind of computer at the
ali@0
   115
same time, by placing the object files for each architecture in their
ali@0
   116
own directory.  To do this, you can use GNU `make'.  `cd' to the
ali@0
   117
directory where you want the object files and executables to go and run
ali@0
   118
the `configure' script.  `configure' automatically checks for the
ali@0
   119
source code in the directory that `configure' is in and in `..'.  This
ali@0
   120
is known as a "VPATH" build.
ali@0
   121
ali@0
   122
   With a non-GNU `make', it is safer to compile the package for one
ali@0
   123
architecture at a time in the source code directory.  After you have
ali@0
   124
installed the package for one architecture, use `make distclean' before
ali@0
   125
reconfiguring for another architecture.
ali@0
   126
ali@0
   127
   On MacOS X 10.5 and later systems, you can create libraries and
ali@0
   128
executables that work on multiple system types--known as "fat" or
ali@0
   129
"universal" binaries--by specifying multiple `-arch' options to the
ali@0
   130
compiler but only a single `-arch' option to the preprocessor.  Like
ali@0
   131
this:
ali@0
   132
ali@0
   133
     ./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
ali@0
   134
                 CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
ali@0
   135
                 CPP="gcc -E" CXXCPP="g++ -E"
ali@0
   136
ali@0
   137
   This is not guaranteed to produce working output in all cases, you
ali@0
   138
may have to build one architecture at a time and combine the results
ali@0
   139
using the `lipo' tool if you have problems.
ali@0
   140
ali@0
   141
Installation Names
ali@0
   142
==================
ali@0
   143
ali@0
   144
   By default, `make install' installs the package's commands under
ali@0
   145
`/usr/local/bin', include files under `/usr/local/include', etc.  You
ali@0
   146
can specify an installation prefix other than `/usr/local' by giving
ali@0
   147
`configure' the option `--prefix=PREFIX', where PREFIX must be an
ali@0
   148
absolute file name.
ali@0
   149
ali@0
   150
   You can specify separate installation prefixes for
ali@0
   151
architecture-specific files and architecture-independent files.  If you
ali@0
   152
pass the option `--exec-prefix=PREFIX' to `configure', the package uses
ali@0
   153
PREFIX as the prefix for installing programs and libraries.
ali@0
   154
Documentation and other data files still use the regular prefix.
ali@0
   155
ali@0
   156
   In addition, if you use an unusual directory layout you can give
ali@0
   157
options like `--bindir=DIR' to specify different values for particular
ali@0
   158
kinds of files.  Run `configure --help' for a list of the directories
ali@0
   159
you can set and what kinds of files go in them.  In general, the
ali@0
   160
default for these options is expressed in terms of `${prefix}', so that
ali@0
   161
specifying just `--prefix' will affect all of the other directory
ali@0
   162
specifications that were not explicitly provided.
ali@0
   163
ali@0
   164
   The most portable way to affect installation locations is to pass the
ali@0
   165
correct locations to `configure'; however, many packages provide one or
ali@0
   166
both of the following shortcuts of passing variable assignments to the
ali@0
   167
`make install' command line to change installation locations without
ali@0
   168
having to reconfigure or recompile.
ali@0
   169
ali@0
   170
   The first method involves providing an override variable for each
ali@0
   171
affected directory.  For example, `make install
ali@0
   172
prefix=/alternate/directory' will choose an alternate location for all
ali@0
   173
directory configuration variables that were expressed in terms of
ali@0
   174
`${prefix}'.  Any directories that were specified during `configure',
ali@0
   175
but not in terms of `${prefix}', must each be overridden at install
ali@0
   176
time for the entire installation to be relocated.  The approach of
ali@0
   177
makefile variable overrides for each directory variable is required by
ali@0
   178
the GNU Coding Standards, and ideally causes no recompilation.
ali@0
   179
However, some platforms have known limitations with the semantics of
ali@0
   180
shared libraries that end up requiring recompilation when using this
ali@0
   181
method, particularly noticeable in packages that use GNU Libtool.
ali@0
   182
ali@0
   183
   The second method involves providing the `DESTDIR' variable.  For
ali@0
   184
example, `make install DESTDIR=/alternate/directory' will prepend
ali@0
   185
`/alternate/directory' before all installation names.  The approach of
ali@0
   186
`DESTDIR' overrides is not required by the GNU Coding Standards, and
ali@0
   187
does not work on platforms that have drive letters.  On the other hand,
ali@0
   188
it does better at avoiding recompilation issues, and works well even
ali@0
   189
when some directory options were not specified in terms of `${prefix}'
ali@0
   190
at `configure' time.
ali@0
   191
ali@0
   192
Optional Features
ali@0
   193
=================
ali@0
   194
ali@0
   195
   If the package supports it, you can cause programs to be installed
ali@0
   196
with an extra prefix or suffix on their names by giving `configure' the
ali@0
   197
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
ali@0
   198
ali@0
   199
   Some packages pay attention to `--enable-FEATURE' options to
ali@0
   200
`configure', where FEATURE indicates an optional part of the package.
ali@0
   201
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
ali@0
   202
is something like `gnu-as' or `x' (for the X Window System).  The
ali@0
   203
`README' should mention any `--enable-' and `--with-' options that the
ali@0
   204
package recognizes.
ali@0
   205
ali@0
   206
   For packages that use the X Window System, `configure' can usually
ali@0
   207
find the X include and library files automatically, but if it doesn't,
ali@0
   208
you can use the `configure' options `--x-includes=DIR' and
ali@0
   209
`--x-libraries=DIR' to specify their locations.
ali@0
   210
ali@0
   211
   Some packages offer the ability to configure how verbose the
ali@0
   212
execution of `make' will be.  For these packages, running `./configure
ali@0
   213
--enable-silent-rules' sets the default to minimal output, which can be
ali@0
   214
overridden with `make V=1'; while running `./configure
ali@0
   215
--disable-silent-rules' sets the default to verbose, which can be
ali@0
   216
overridden with `make V=0'.
ali@0
   217
ali@0
   218
Particular systems
ali@0
   219
==================
ali@0
   220
ali@0
   221
   On HP-UX, the default C compiler is not ANSI C compatible.  If GNU
ali@0
   222
CC is not installed, it is recommended to use the following options in
ali@0
   223
order to use an ANSI C compiler:
ali@0
   224
ali@0
   225
     ./configure CC="cc -Ae -D_XOPEN_SOURCE=500"
ali@0
   226
ali@0
   227
and if that doesn't work, install pre-built binaries of GCC for HP-UX.
ali@0
   228
ali@0
   229
   On OSF/1 a.k.a. Tru64, some versions of the default C compiler cannot
ali@0
   230
parse its `<wchar.h>' header file.  The option `-nodtk' can be used as
ali@0
   231
a workaround.  If GNU CC is not installed, it is therefore recommended
ali@0
   232
to try
ali@0
   233
ali@0
   234
     ./configure CC="cc"
ali@0
   235
ali@0
   236
and if that doesn't work, try
ali@0
   237
ali@0
   238
     ./configure CC="cc -nodtk"
ali@0
   239
ali@0
   240
   On Solaris, don't put `/usr/ucb' early in your `PATH'.  This
ali@0
   241
directory contains several dysfunctional programs; working variants of
ali@0
   242
these programs are available in `/usr/bin'.  So, if you need `/usr/ucb'
ali@0
   243
in your `PATH', put it _after_ `/usr/bin'.
ali@0
   244
ali@0
   245
   On Haiku, software installed for all users goes in `/boot/common',
ali@0
   246
not `/usr/local'.  It is recommended to use the following options:
ali@0
   247
ali@0
   248
     ./configure --prefix=/boot/common
ali@0
   249
ali@0
   250
Specifying the System Type
ali@0
   251
==========================
ali@0
   252
ali@0
   253
   There may be some features `configure' cannot figure out
ali@0
   254
automatically, but needs to determine by the type of machine the package
ali@0
   255
will run on.  Usually, assuming the package is built to be run on the
ali@0
   256
_same_ architectures, `configure' can figure that out, but if it prints
ali@0
   257
a message saying it cannot guess the machine type, give it the
ali@0
   258
`--build=TYPE' option.  TYPE can either be a short name for the system
ali@0
   259
type, such as `sun4', or a canonical name which has the form:
ali@0
   260
ali@0
   261
     CPU-COMPANY-SYSTEM
ali@0
   262
ali@0
   263
where SYSTEM can have one of these forms:
ali@0
   264
ali@0
   265
     OS
ali@0
   266
     KERNEL-OS
ali@0
   267
ali@0
   268
   See the file `config.sub' for the possible values of each field.  If
ali@0
   269
`config.sub' isn't included in this package, then this package doesn't
ali@0
   270
need to know the machine type.
ali@0
   271
ali@0
   272
   If you are _building_ compiler tools for cross-compiling, you should
ali@0
   273
use the option `--target=TYPE' to select the type of system they will
ali@0
   274
produce code for.
ali@0
   275
ali@0
   276
   If you want to _use_ a cross compiler, that generates code for a
ali@0
   277
platform different from the build platform, you should specify the
ali@0
   278
"host" platform (i.e., that on which the generated programs will
ali@0
   279
eventually be run) with `--host=TYPE'.
ali@0
   280
ali@0
   281
Sharing Defaults
ali@0
   282
================
ali@0
   283
ali@0
   284
   If you want to set default values for `configure' scripts to share,
ali@0
   285
you can create a site shell script called `config.site' that gives
ali@0
   286
default values for variables like `CC', `cache_file', and `prefix'.
ali@0
   287
`configure' looks for `PREFIX/share/config.site' if it exists, then
ali@0
   288
`PREFIX/etc/config.site' if it exists.  Or, you can set the
ali@0
   289
`CONFIG_SITE' environment variable to the location of the site script.
ali@0
   290
A warning: not all `configure' scripts look for a site script.
ali@0
   291
ali@0
   292
Defining Variables
ali@0
   293
==================
ali@0
   294
ali@0
   295
   Variables not defined in a site shell script can be set in the
ali@0
   296
environment passed to `configure'.  However, some packages may run
ali@0
   297
configure again during the build, and the customized values of these
ali@0
   298
variables may be lost.  In order to avoid this problem, you should set
ali@0
   299
them in the `configure' command line, using `VAR=value'.  For example:
ali@0
   300
ali@0
   301
     ./configure CC=/usr/local2/bin/gcc
ali@0
   302
ali@0
   303
causes the specified `gcc' to be used as the C compiler (unless it is
ali@0
   304
overridden in the site shell script).
ali@0
   305
ali@0
   306
Unfortunately, this technique does not work for `CONFIG_SHELL' due to
ali@0
   307
an Autoconf bug.  Until the bug is fixed you can use this workaround:
ali@0
   308
ali@0
   309
     CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash
ali@0
   310
ali@0
   311
`configure' Invocation
ali@0
   312
======================
ali@0
   313
ali@0
   314
   `configure' recognizes the following options to control how it
ali@0
   315
operates.
ali@0
   316
ali@0
   317
`--help'
ali@0
   318
`-h'
ali@0
   319
     Print a summary of all of the options to `configure', and exit.
ali@0
   320
ali@0
   321
`--help=short'
ali@0
   322
`--help=recursive'
ali@0
   323
     Print a summary of the options unique to this package's
ali@0
   324
     `configure', and exit.  The `short' variant lists options used
ali@0
   325
     only in the top level, while the `recursive' variant lists options
ali@0
   326
     also present in any nested packages.
ali@0
   327
ali@0
   328
`--version'
ali@0
   329
`-V'
ali@0
   330
     Print the version of Autoconf used to generate the `configure'
ali@0
   331
     script, and exit.
ali@0
   332
ali@0
   333
`--cache-file=FILE'
ali@0
   334
     Enable the cache: use and save the results of the tests in FILE,
ali@0
   335
     traditionally `config.cache'.  FILE defaults to `/dev/null' to
ali@0
   336
     disable caching.
ali@0
   337
ali@0
   338
`--config-cache'
ali@0
   339
`-C'
ali@0
   340
     Alias for `--cache-file=config.cache'.
ali@0
   341
ali@0
   342
`--quiet'
ali@0
   343
`--silent'
ali@0
   344
`-q'
ali@0
   345
     Do not print messages saying which checks are being made.  To
ali@0
   346
     suppress all normal output, redirect it to `/dev/null' (any error
ali@0
   347
     messages will still be shown).
ali@0
   348
ali@0
   349
`--srcdir=DIR'
ali@0
   350
     Look for the package's source code in directory DIR.  Usually
ali@0
   351
     `configure' can determine that directory automatically.
ali@0
   352
ali@0
   353
`--prefix=DIR'
ali@0
   354
     Use DIR as the installation prefix.  *note Installation Names::
ali@0
   355
     for more details, including other options available for fine-tuning
ali@0
   356
     the installation locations.
ali@0
   357
ali@0
   358
`--no-create'
ali@0
   359
`-n'
ali@0
   360
     Run the configure checks, but stop before creating any output
ali@0
   361
     files.
ali@0
   362
ali@0
   363
`configure' also accepts some other, not widely useful, options.  Run
ali@0
   364
`configure --help' for more details.
ali@0
   365