X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Finstall.texi;fp=doc%2Finstall.texi;h=4f3301f2e6da79085236c057d8631f8a472164e0;hb=8ec8f4b42e39d3aaf2dda06c38b8db00efcc69f5;hp=3fc429854fecd9c6e4585f1c42c7bd9634be7ee5;hpb=b504d8a2e9ffaab93147d2937ae4e74d6409e084;p=gnulib.git diff --git a/doc/install.texi b/doc/install.texi index 3fc429854..4f3301f2e 100644 --- a/doc/install.texi +++ b/doc/install.texi @@ -23,6 +23,14 @@ Briefly, the shell commands @samp{./configure; make; make 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 @acronym{GNU} packages can be found in +@ref{Makefile Conventions, , Makefile Conventions, standards, +@acronym{GNU} Coding Standards}. The @command{configure} shell script attempts to guess correct values for various system-dependent variables used during compilation. It uses @@ -47,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 -@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 @@ -67,11 +74,17 @@ Type @samp{make} to compile the package. @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. @item You can remove the program binaries and object files from the source @@ -85,7 +98,15 @@ distribution. @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 +@acronym{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 @@ -115,7 +136,8 @@ own directory. To do this, you can use @acronym{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}, it is safer to compile the package for one @@ -146,7 +168,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 -@command{configure} the option @option{--prefix=@var{prefix}}. +@command{configure} the option @option{--prefix=@var{prefix}}, where +@var{prefix} must be an absolute path. You can specify separate installation prefixes for architecture-specific files and architecture-independent files. If you pass the option @@ -158,16 +181,51 @@ 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 -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. + +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=/path/to/alternate} will choose an alternate location, as well as +influencing all other directory configuration variables that were +expressed in terms of @samp{$@{prefix@}} (or, put another way, all +directories specified during @command{configure} but not in terms of the +common 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 @acronym{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 @acronym{GNU} Libtool. + +The second method involves providing the @samp{DESTDIR} variable. For +example, @samp{make install DESTDIR=/path/to/alternate} will prepend +@samp{/path/to/alternate} before all installation paths. The approach +of @samp{DESTDIR} overrides is not required by the @acronym{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. For packages which +support @samp{DESTDIR}, the variable should remain undefined during +@command{configure} and @samp{make all}, and only be specified during +@samp{make install}. + +@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 @@ -182,6 +240,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. +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