md5, sha1, sha256, sha512: add gl_SET_CRYPTO_CHECK_DEFAULT

[gnulib.git] / doc / install.texi

diff --git a/doc/install.texi b/doc/install.texi
index a344b28..b58c9ed 100644 (file)
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -2,25 +2,35 @@
 @c the INSTALL file.
 
 @ifclear autoconf
 @c the INSTALL file.
 
 @ifclear autoconf

-@firstparagraphindent insert

 
 @unnumbered Installation Instructions
 
 
 @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
 
 
 @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.
 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
 
 The @command{configure} shell script attempts to guess correct values
 for various system-dependent variables used during compilation.  It uses


@@ -45,16 +55,15 @@ cache, and at some point @file{config.cache} contains results you don't
 want to keep, you may remove or edit it.
 
 The file @file{configure.ac} (or @file{configure.in}) is used to create
 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.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
 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
 @samp{./configure} to configure the package for your system.
 
 Running @command{configure} might take a while.  While running, it prints some


@@ -65,11 +74,20 @@ Type @samp{make} to compile the package.
 
 @item
 Optionally, type @samp{make check} to run any self-tests that come with
 
 @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
 
 @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
 You can remove the program binaries and object files from the source


@@ -83,7 +101,15 @@ distribution.
 
 @item
 Often, you can also type @samp{make uninstall} to remove the installed
 
 @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
 @end enumerate
 
 @node Compilers and Options


@@ -109,13 +135,14 @@ Here is an example:
 
 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
 
 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
 @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}
 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}


@@ -144,7 +171,8 @@ By default, @samp{make install} installs the package's commands under
 @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
 @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
 
 You can specify separate installation prefixes for architecture-specific
 files and architecture-independent files.  If you pass the option


@@ -156,16 +184,49 @@ regular prefix.
 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
 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}}.
 
 
 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
 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


@@ -180,6 +241,13 @@ doesn't, you can use the @command{configure} options
 @option{--x-includes=@var{dir}} and @option{--x-libraries=@var{dir}} to
 specify their locations.
 
 @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
 
 @node Particular Systems
 @section Particular systems
 


@@ -188,12 +256,17 @@ not installed, it is recommended to use the following options in order to
 use an ANSI C compiler:
 
 @example
 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.
 
 @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
 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


@@ -210,6 +283,18 @@ and if that doesn't work, try
 ./configure CC="cc -nodtk"
 @end example
 
 ./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
 
 @node System Type
 @section Specifying the System Type
 


@@ -230,7 +315,8 @@ which has the form:
 where @var{system} can have one of these forms:
 
 @example
 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.
 @end example
 
 See the file @file{config.sub} for the possible values of each field.


@@ -279,11 +365,11 @@ overridden in the site shell script).
 
 @noindent
 Unfortunately, this technique does not work for @env{CONFIG_SHELL} due
 
 @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
 
 @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
 @end example
 
 @node configure Invocation