1 @c This file is imported from GNU Autoconf and edited to produce
6 @unnumbered Installation Instructions
8 Copyright @copyright{} 1994-1996, 1999-2002, 2004-2013 Free Software
11 Copying and distribution of this file, with or without modification, are
12 permitted in any medium without royalty provided the copyright notice
13 and this notice are preserved. This file is offered as-is, without
18 @node Basic Installation
19 @section Basic Installation
21 Briefly, the shell command
22 @samp{./configure@tie{}&& make@tie{}&& make@tie{}install}
23 should configure, build, and install this package. The following
24 more-detailed instructions are generic; see the @file{README} file for
25 instructions specific to this package.
27 Some packages provide this @file{INSTALL} file but do not implement all
28 of the features documented below. The lack of an optional feature in a
29 given package is not necessarily a bug.
31 More recommendations for GNU packages can be found in
32 @ref{Makefile Conventions, , Makefile Conventions, standards,
33 GNU Coding Standards}.
35 The @command{configure} shell script attempts to guess correct values
36 for various system-dependent variables used during compilation. It uses
37 those values to create a @file{Makefile} in each directory of the
38 package. It may also create one or more @file{.h} files containing
39 system-dependent definitions. Finally, it creates a shell script
40 @file{config.status} that you can run in the future to recreate the
41 current configuration, and a file @file{config.log} containing compiler
42 output (useful mainly for debugging @command{configure}).
44 It can also use an optional file (typically called @file{config.cache}
45 and enabled with @option{--cache-file=config.cache} or simply
46 @option{-C}) that saves the results of its tests to speed up
47 reconfiguring. Caching is disabled by default to prevent problems with
48 accidental use of stale cache files.
50 If you need to do unusual things to compile the package, please try to
51 figure out how @command{configure} could check whether to do them, and
52 mail diffs or instructions to the address given in the @file{README} so
53 they can be considered for the next release. If you are using the
54 cache, and at some point @file{config.cache} contains results you don't
55 want to keep, you may remove or edit it.
57 The file @file{configure.ac} (or @file{configure.in}) is used to create
58 @file{configure} by a program called @command{autoconf}. You need
59 @file{configure.ac} if you want to change it or regenerate
60 @file{configure} using a newer version of @command{autoconf}.
62 The simplest way to compile this package is:
66 @command{cd} to the directory containing the package's source code and type
67 @samp{./configure} to configure the package for your system.
69 Running @command{configure} might take a while. While running, it prints some
70 messages telling which features it is checking for.
73 Type @samp{make} to compile the package.
76 Optionally, type @samp{make check} to run any self-tests that come with
77 the package, generally using the just-built uninstalled binaries.
80 Type @samp{make install} to install the programs and any data files and
81 documentation. When installing into a prefix owned by root, it is
82 recommended that the package be configured and built as a regular user,
83 and only the @samp{make install} phase executed with root privileges.
86 Optionally, type @samp{make installcheck} to repeat any self-tests, but
87 this time using the binaries in their final installed location. This
88 target does not install anything. Running this target as a regular
89 user, particularly if the prior @samp{make install} required root
90 privileges, verifies that the installation completed correctly.
93 You can remove the program binaries and object files from the source
94 code directory by typing @samp{make clean}. To also remove the files
95 that @command{configure} created (so you can compile the package for a
96 different kind of computer), type @samp{make distclean}. There is also
97 a @samp{make maintainer-clean} target, but that is intended mainly for
98 the package's developers. If you use it, you may have to get all sorts
99 of other programs in order to regenerate files that came with the
103 Often, you can also type @samp{make uninstall} to remove the installed
104 files again. In practice, not all packages have tested that
105 uninstallation works correctly, even though it is required by the
106 GNU Coding Standards.
109 Some packages, particularly those that use Automake, provide @samp{make
110 distcheck}, which can by used by developers to test that all other
111 targets like @samp{make install} and @samp{make uninstall} work
112 correctly. This target is generally not run by end users.
115 @node Compilers and Options
116 @section Compilers and Options
118 Some systems require unusual options for compilation or linking that the
119 @command{configure} script does not know about. Run @samp{./configure
120 --help} for details on some of the pertinent environment variables.
122 You can give @command{configure} initial values for configuration
123 parameters by setting variables in the command line or in the environment.
127 ./configure CC=c99 CFLAGS=-g LIBS=-lposix
130 @xref{Defining Variables}, for more details.
133 @node Installation Names
134 @section Installation Names
136 By default, @samp{make install} installs the package's commands under
137 @file{/usr/local/bin}, include files under @file{/usr/local/include}, etc.
139 installation prefix other than @file{/usr/local} by giving
140 @command{configure} the option @option{--prefix=@var{prefix}}, where
141 @var{prefix} must be an absolute file name.
143 You can specify separate installation prefixes for architecture-specific
144 files and architecture-independent files. If you pass the option
145 @option{--exec-prefix=@var{prefix}} to @command{configure}, the
146 package uses @var{prefix} as the prefix for installing programs and
147 libraries. Documentation and other data files still use the
150 In addition, if you use an unusual directory layout you can give options
151 like @option{--bindir=@var{dir}} to specify different values for
152 particular kinds of files. Run @samp{configure --help} for a list of
153 the directories you can set and what kinds of files go in them. In
154 general, the default for these options is expressed in terms of
155 @samp{$@{prefix@}}, so that specifying just @option{--prefix} will
156 affect all of the other directory specifications that were not
159 The most portable way to affect installation locations is to pass the
160 correct locations to @command{configure}; however, many packages provide
161 one or both of the following shortcuts of passing variable assignments
162 to the @samp{make install} command line to change installation locations
163 without having to reconfigure or recompile.
165 The first method involves providing an override variable for each
166 affected directory. For example, @samp{make install
167 prefix=/alternate/directory} will choose an alternate location for all
168 directory configuration variables that were expressed in terms of
169 @samp{$@{prefix@}}. Any directories that were specified during
170 @command{configure}, but not in terms of @samp{$@{prefix@}}, must each be
171 overridden at install time for the entire
172 installation to be relocated. The approach of makefile variable
173 overrides for each directory variable is required by the GNU
174 Coding Standards, and ideally causes no recompilation. However, some
175 platforms have known limitations with the semantics of shared libraries
176 that end up requiring recompilation when using this method, particularly
177 noticeable in packages that use GNU Libtool.
179 The second method involves providing the @samp{DESTDIR} variable. For
180 example, @samp{make install DESTDIR=/alternate/directory} will prepend
181 @samp{/alternate/directory} before all installation names. The approach
182 of @samp{DESTDIR} overrides is not required by the GNU Coding
183 Standards, and does not work on platforms that have drive letters. On
184 the other hand, it does better at avoiding recompilation issues, and
185 works well even when some directory options were not specified in terms
186 of @samp{$@{prefix@}} at @command{configure} time.
188 @node Optional Features
189 @section Optional Features
191 If the package supports it, you can cause programs to be installed with
192 an extra prefix or suffix on their names by giving @command{configure}
193 the option @option{--program-prefix=@var{PREFIX}} or
194 @option{--program-suffix=@var{SUFFIX}}.
196 Some packages pay attention to @option{--enable-@var{feature}} options
197 to @command{configure}, where @var{feature} indicates an optional part
198 of the package. They may also pay attention to
199 @option{--with-@var{package}} options, where @var{package} is something
200 like @samp{gnu-as} or @samp{x} (for the X Window System). The
201 @file{README} should mention any @option{--enable-} and @option{--with-}
202 options that the package recognizes.
204 For packages that use the X Window System, @command{configure} can
205 usually find the X include and library files automatically, but if it
206 doesn't, you can use the @command{configure} options
207 @option{--x-includes=@var{dir}} and @option{--x-libraries=@var{dir}} to
208 specify their locations.
210 Some packages offer the ability to configure how verbose the execution
211 of @command{make} will be. For these packages, running
212 @samp{./configure --enable-silent-rules} sets the default to minimal
213 output, which can be overridden with @code{make V=1}; while running
214 @samp{./configure --disable-silent-rules} sets the default to verbose,
215 which can be overridden with @code{make V=0}.
218 @section Specifying the System Type
220 There may be some features @command{configure} cannot figure out
221 automatically, but needs to determine by the type of machine the package
222 will run on. Usually, assuming the package is built to be run on the
223 @emph{same} architectures, @command{configure} can figure that out, but
224 if it prints a message saying it cannot guess the machine type, give it
225 the @option{--build=@var{type}} option. @var{type} can either be a
226 short name for the system type, such as @samp{sun4}, or a canonical name
230 @var{cpu}-@var{company}-@var{system}
234 where @var{system} can have one of these forms:
238 @var{kernel}-@var{os}
241 See the file @file{config.sub} for the possible values of each field.
242 If @file{config.sub} isn't included in this package, then this package
243 doesn't need to know the machine type.
245 If you are @emph{building} compiler tools for cross-compiling, you
246 should use the option @option{--target=@var{type}} to select the type of
247 system they will produce code for.
249 If you want to @emph{use} a cross compiler, that generates code for a
250 platform different from the build platform, you should specify the
251 @dfn{host} platform (i.e., that on which the generated programs will
252 eventually be run) with @option{--host=@var{type}}.
254 @node Sharing Defaults
255 @section Sharing Defaults
257 If you want to set default values for @command{configure} scripts to
258 share, you can create a site shell script called @file{config.site} that
259 gives default values for variables like @code{CC}, @code{cache_file},
260 and @code{prefix}. @command{configure} looks for
261 @file{@var{prefix}/share/config.site} if it exists, then
262 @file{@var{prefix}/etc/config.site} if it exists. Or, you can set the
263 @code{CONFIG_SITE} environment variable to the location of the site
264 script. A warning: not all @command{configure} scripts look for a site
267 @node Defining Variables
268 @section Defining Variables
270 Variables not defined in a site shell script can be set in the
271 environment passed to @command{configure}. However, some packages may
272 run configure again during the build, and the customized values of these
273 variables may be lost. In order to avoid this problem, you should set
274 them in the @command{configure} command line, using @samp{VAR=value}.
278 ./configure CC=/usr/local2/bin/gcc
282 causes the specified @command{gcc} to be used as the C compiler (unless it is
283 overridden in the site shell script).
286 Unfortunately, this technique does not work for @env{CONFIG_SHELL} due
287 to an Autoconf limitation. Until the limitation is lifted, you can use
291 CONFIG_SHELL=/bin/bash ./configure CONFIG_SHELL=/bin/bash
294 @node configure Invocation
295 @section @command{configure} Invocation
297 @command{configure} recognizes the following options to control how it
303 Print a summary of all of the options to @command{configure}, and exit.
306 @itemx --help=recursive
307 Print a summary of the options unique to this package's
308 @command{configure}, and exit. The @code{short} variant lists options
309 used only in the top level, while the @code{recursive} variant lists
310 options also present in any nested packages.
314 Print the version of Autoconf used to generate the @command{configure}
317 @item --cache-file=@var{file}
318 @cindex Cache, enabling
319 Enable the cache: use and save the results of the tests in @var{file},
320 traditionally @file{config.cache}. @var{file} defaults to
321 @file{/dev/null} to disable caching.
325 Alias for @option{--cache-file=config.cache}.
330 Do not print messages saying which checks are being made. To suppress
331 all normal output, redirect it to @file{/dev/null} (any error messages
332 will still be shown).
334 @item --srcdir=@var{dir}
335 Look for the package's source code in directory @var{dir}. Usually
336 @command{configure} can determine that directory automatically.
338 @item --prefix=@var{dir}
339 Use @var{dir} as the installation prefix. @ref{Installation Names}
340 for more details, including other options available for fine-tuning
341 the installation locations.
345 Run the configure checks, but stop before creating any output files.
349 @command{configure} also accepts some other, not widely useful, options.
350 Run @samp{configure --help} for more details.
354 @c ispell-local-dictionary: "american"
355 @c indent-tabs-mode: nil
356 @c whitespace-check-buffer-indent: nil