@unnumbered Installation Instructions
-Copyright @copyright{} 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004,
-2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+Copyright @copyright{} 1994-1996, 1999-2002, 2004-2013 Free Software
+Foundation, Inc.
-This file is free documentation; the Free Software Foundation gives
-unlimited permission to copy, distribute and modify it.
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty provided the copyright notice
+and this notice are preserved. This file is offered as-is, without
+warranty of any kind.
@end ifclear
@node Basic Installation
@section Basic Installation
-Briefly, the shell commands @samp{./configure; make; make install}
+Briefly, the shell command
+@samp{./configure@tie{}&& make@tie{}&& make@tie{}install}
should configure, build, and install this package. The following
more-detailed instructions are generic; see the @file{README} file for
instructions specific to this package.
+@ifclear autoconf
+Some packages provide this @file{INSTALL} file but do not implement all
+of the features documented below. The lack of an optional feature in a
+given package is not necessarily a bug.
+@end ifclear
+More recommendations for GNU packages can be found in
+@ref{Makefile Conventions, , Makefile Conventions, standards,
+GNU Coding Standards}.
The @command{configure} shell script attempts to guess correct values
for various system-dependent variables used during compilation. It uses
want to keep, you may remove or edit it.
The file @file{configure.ac} (or @file{configure.in}) is used to create
-@file{configure} by a program called @code{autoconf}. You need
+@file{configure} by a program called @command{autoconf}. You need
@file{configure.ac} if you want to change it or regenerate
-@file{configure} using a newer version of @code{autoconf}.
+@file{configure} using a newer version of @command{autoconf}.
-@noindent
The simplest way to compile this package is:
@enumerate
@item
-@code{cd} to the directory containing the package's source code and type
+@command{cd} to the directory containing the package's source code and type
@samp{./configure} to configure the package for your system.
Running @command{configure} might take a while. While running, it prints some
@item
Optionally, type @samp{make check} to run any self-tests that come with
-the package.
+the package, generally using the just-built uninstalled binaries.
@item
Type @samp{make install} to install the programs and any data files and
-documentation.
+documentation. When installing into a prefix owned by root, it is
+recommended that the package be configured and built as a regular user,
+and only the @samp{make install} phase executed with root privileges.
+
+@item
+Optionally, type @samp{make installcheck} to repeat any self-tests, but
+this time using the binaries in their final installed location. This
+target does not install anything. Running this target as a regular
+user, particularly if the prior @samp{make install} required root
+privileges, verifies that the installation completed correctly.
@item
You can remove the program binaries and object files from the source
@item
Often, you can also type @samp{make uninstall} to remove the installed
-files again.
+files again. In practice, not all packages have tested that
+uninstallation works correctly, even though it is required by the
+GNU Coding Standards.
+
+@item
+Some packages, particularly those that use Automake, provide @samp{make
+distcheck}, which can by used by developers to test that all other
+targets like @samp{make install} and @samp{make uninstall} work
+correctly. This target is generally not run by end users.
@end enumerate
@node Compilers and Options
You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
-own directory. To do this, you can use @acronym{GNU} @command{make}.
+own directory. To do this, you can use GNU @command{make}.
@command{cd} to the directory where you want the object files and
executables to go and run the @command{configure} script.
@command{configure} automatically checks for the source code in the
-directory that @command{configure} is in and in @file{..}.
+directory that @command{configure} is in and in @file{..}. This is
+known as a @dfn{VPATH} build.
-With a non-@acronym{GNU} @command{make},
+With a non-GNU @command{make},
it is safer to compile the package for one
architecture at a time in the source code directory. After you have
installed the package for one architecture, use @samp{make distclean}
@file{/usr/local/bin}, include files under @file{/usr/local/include}, etc.
You can specify an
installation prefix other than @file{/usr/local} by giving
-@command{configure} the option @option{--prefix=@var{prefix}}.
+@command{configure} the option @option{--prefix=@var{prefix}}, where
+@var{prefix} must be an absolute file name.
You can specify separate installation prefixes for architecture-specific
files and architecture-independent files. If you pass the option
In addition, if you use an unusual directory layout you can give options
like @option{--bindir=@var{dir}} to specify different values for
particular kinds of files. Run @samp{configure --help} for a list of
-the directories you can set and what kinds of files go in them.
+the directories you can set and what kinds of files go in them. In
+general, the default for these options is expressed in terms of
+@samp{$@{prefix@}}, so that specifying just @option{--prefix} will
+affect all of the other directory specifications that were not
+explicitly provided.
+
+The most portable way to affect installation locations is to pass the
+correct locations to @command{configure}; however, many packages provide
+one or both of the following shortcuts of passing variable assignments
+to the @samp{make install} command line to change installation locations
+without having to reconfigure or recompile.
+
+The first method involves providing an override variable for each
+affected directory. For example, @samp{make install
+prefix=/alternate/directory} will choose an alternate location for all
+directory configuration variables that were expressed in terms of
+@samp{$@{prefix@}}. Any directories that were specified during
+@command{configure}, but not in terms of @samp{$@{prefix@}}, must each be
+overridden at install time for the entire
+installation to be relocated. The approach of makefile variable
+overrides for each directory variable is required by the GNU
+Coding Standards, and ideally causes no recompilation. However, some
+platforms have known limitations with the semantics of shared libraries
+that end up requiring recompilation when using this method, particularly
+noticeable in packages that use GNU Libtool.
+
+The second method involves providing the @samp{DESTDIR} variable. For
+example, @samp{make install DESTDIR=/alternate/directory} will prepend
+@samp{/alternate/directory} before all installation names. The approach
+of @samp{DESTDIR} overrides is not required by the GNU Coding
+Standards, and does not work on platforms that have drive letters. On
+the other hand, it does better at avoiding recompilation issues, and
+works well even when some directory options were not specified in terms
+of @samp{$@{prefix@}} at @command{configure} time.
+
+@node Optional Features
+@section Optional Features
If the package supports it, you can cause programs to be installed with
an extra prefix or suffix on their names by giving @command{configure}
the option @option{--program-prefix=@var{PREFIX}} or
@option{--program-suffix=@var{SUFFIX}}.
-@node Optional Features
-@section Optional Features
-
Some packages pay attention to @option{--enable-@var{feature}} options
to @command{configure}, where @var{feature} indicates an optional part
of the package. They may also pay attention to
@option{--x-includes=@var{dir}} and @option{--x-libraries=@var{dir}} to
specify their locations.
+Some packages offer the ability to configure how verbose the execution
+of @command{make} will be. For these packages, running
+@samp{./configure --enable-silent-rules} sets the default to minimal
+output, which can be overridden with @code{make V=1}; while running
+@samp{./configure --disable-silent-rules} sets the default to verbose,
+which can be overridden with @code{make V=0}.
+
@node Particular Systems
@section Particular systems
use an ANSI C compiler:
@example
-./configure CC="cc -Ae"
+./configure CC="cc -Ae -D_XOPEN_SOURCE=500"
@end example
@noindent
and if that doesn't work, install pre-built binaries of GCC for HP-UX.
+HP-UX @command{make} updates targets which have the same time stamps as
+their prerequisites, which makes it generally unusable when shipped
+generated files such as @command{configure} are involved. Use GNU
+@command{make} instead.
+
On OSF/1 a.k.a.@: Tru64, some versions of the default C compiler cannot
parse its @code{<wchar.h>} header file. The option @option{-nodtk} can be
used as a workaround. If GNU CC is not installed, it is therefore
./configure CC="cc -nodtk"
@end example
+On Solaris, don't put @code{/usr/ucb} early in your @env{PATH}. This
+directory contains several dysfunctional programs; working variants
+of these programs are available in @code{/usr/bin}. So, if you need
+@code{/usr/ucb} in your @env{PATH}, put it @emph{after} @code{/usr/bin}.
+
+On Haiku, software installed for all users goes in @file{/boot/common},
+not @file{/usr/local}. It is recommended to use the following options:
+
+@example
+./configure --prefix=/boot/common
+@end example
+
@node System Type
@section Specifying the System Type
where @var{system} can have one of these forms:
@example
-@var{os} @var{kernel}-@var{os}
+@var{os}
+@var{kernel}-@var{os}
@end example
See the file @file{config.sub} for the possible values of each field.
@noindent
Unfortunately, this technique does not work for @env{CONFIG_SHELL} due
-to an Autoconf bug. Until the bug is fixed you can use this
-workaround:
+to an Autoconf limitation. Until the limitation is lifted, you can use
+this workaround:
@example
-CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash
+CONFIG_SHELL=/bin/bash ./configure CONFIG_SHELL=/bin/bash
@end example
@node configure Invocation
@table @option
@item --help
@itemx -h
-Print a summary of the options to @command{configure}, and exit.
+Print a summary of all of the options to @command{configure}, and exit.
+
+@item --help=short
+@itemx --help=recursive
+Print a summary of the options unique to this package's
+@command{configure}, and exit. The @code{short} variant lists options
+used only in the top level, while the @code{recursive} variant lists
+options also present in any nested packages.
@item --version
@itemx -V
@item --srcdir=@var{dir}
Look for the package's source code in directory @var{dir}. Usually
@command{configure} can determine that directory automatically.
+
+@item --prefix=@var{dir}
+Use @var{dir} as the installation prefix. @ref{Installation Names}
+for more details, including other options available for fine-tuning
+the installation locations.
+
+@item --no-create
+@itemx -n
+Run the configure checks, but stop before creating any output files.
@end table
@noindent
@command{configure} also accepts some other, not widely useful, options.
Run @samp{configure --help} for more details.
+
+@c Local Variables:
+@c fill-column: 72
+@c ispell-local-dictionary: "american"
+@c indent-tabs-mode: nil
+@c whitespace-check-buffer-indent: nil
+@c End:
projects / gnulib.git / blobdiff