Fix typo in previous patch.
[autoconf.git] / doc / install.texi
blob6dd4a571f69e3a7a07a2377414f07343fba801b8
1 @c This file is included by autoconf.texi and is used to produce
2 @c the INSTALL file.
4 @ifclear autoconf
5 @firstparagraphindent insert
7 @unnumbered Installation Instructions
9 Copyright @copyright{} 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004,
10 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
12 Copying and distribution of this file, with or without modification, are
13 permitted in any medium without royalty provided the copyright notice
14 and this notice are preserved.  This file is offered as-is, without
15 warranty of any kind.
17 @end ifclear
19 @node Basic Installation
20 @section Basic Installation
22 Briefly, the shell commands @samp{./configure; make; make 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.
26 @ifclear autoconf
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.
30 @end ifclear
31 More recommendations for @acronym{GNU} packages can be found in
32 @ref{Makefile Conventions, , Makefile Conventions, standards,
33 @acronym{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:
64 @enumerate
65 @item
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.
72 @item
73 Type @samp{make} to compile the package.
75 @item
76 Optionally, type @samp{make check} to run any self-tests that come with
77 the package, generally using the just-built uninstalled binaries.
79 @item
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.
85 @item
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.
92 @item
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
100 distribution.
102 @item
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 @acronym{GNU} Coding Standards.
108 @item
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.
113 @end enumerate
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.
124 Here is an example:
126 @example
127 ./configure CC=c99 CFLAGS=-g LIBS=-lposix
128 @end example
130 @xref{Defining Variables}, for more details.
133 @node Multiple Architectures
134 @section Compiling For Multiple Architectures
136 You can compile the package for more than one kind of computer at the
137 same time, by placing the object files for each architecture in their
138 own directory.  To do this, you can use @acronym{GNU} @command{make}.
139 @command{cd} to the directory where you want the object files and
140 executables to go and run the @command{configure} script.
141 @command{configure} automatically checks for the source code in the
142 directory that @command{configure} is in and in @file{..}.  This is
143 known as a @dfn{VPATH} build.
145 With a non-@acronym{GNU} @command{make},
146 it is safer to compile the package for one
147 architecture at a time in the source code directory.  After you have
148 installed the package for one architecture, use @samp{make distclean}
149 before reconfiguring for another architecture.
151 On MacOS X 10.5 and later systems, you can create libraries and
152 executables that work on multiple system types---known as @dfn{fat} or
153 @dfn{universal} binaries---by specifying multiple @option{-arch} options
154 to the compiler but only a single @option{-arch} option to the
155 preprocessor.  Like this:
157 @example
158 ./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
159             CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
160             CPP="gcc -E" CXXCPP="g++ -E"
161 @end example
163 This is not guaranteed to produce working output in all cases, you may
164 have to build one architecture at a time and combine the results
165 using the @command{lipo} tool if you have problems.
167 @node Installation Names
168 @section Installation Names
170 By default, @samp{make install} installs the package's commands under
171 @file{/usr/local/bin}, include files under @file{/usr/local/include}, etc.
172 You can specify an
173 installation prefix other than @file{/usr/local} by giving
174 @command{configure} the option @option{--prefix=@var{prefix}}, where
175 @var{prefix} must be an absolute file name.
177 You can specify separate installation prefixes for architecture-specific
178 files and architecture-independent files.  If you pass the option
179 @option{--exec-prefix=@var{prefix}} to @command{configure}, the
180 package uses @var{prefix} as the prefix for installing programs and
181 libraries.  Documentation and other data files still use the
182 regular prefix.
184 In addition, if you use an unusual directory layout you can give options
185 like @option{--bindir=@var{dir}} to specify different values for
186 particular kinds of files.  Run @samp{configure --help} for a list of
187 the directories you can set and what kinds of files go in them.  In
188 general, the default for these options is expressed in terms of
189 @samp{$@{prefix@}}, so that specifying just @option{--prefix} will
190 affect all of the other directory specifications that were not
191 explicitly provided.
193 The most portable way to affect installation locations is to pass the
194 correct locations to @command{configure}; however, many packages provide
195 one or both of the following shortcuts of passing variable assignments
196 to the @samp{make install} command line to change installation locations
197 without having to reconfigure or recompile.
199 The first method involves providing an override variable for each
200 affected directory.  For example, @samp{make install
201 prefix=/alternate/directory} will choose an alternate location for all
202 directory configuration variables that were expressed in terms of
203 @samp{$@{prefix@}}.  Any directories that were specified during
204 @command{configure}, but not in terms of @samp{$@{prefix@}}, must each be
205 overridden at install time for the entire
206 installation to be relocated.  The approach of makefile variable
207 overrides for each directory variable is required by the @acronym{GNU}
208 Coding Standards, and ideally causes no recompilation.  However, some
209 platforms have known limitations with the semantics of shared libraries
210 that end up requiring recompilation when using this method, particularly
211 noticeable in packages that use @acronym{GNU} Libtool.
213 The second method involves providing the @samp{DESTDIR} variable.  For
214 example, @samp{make install DESTDIR=/alternate/directory} will prepend
215 @samp{/alternate/directory} before all installation names.  The approach
216 of @samp{DESTDIR} overrides is not required by the @acronym{GNU} Coding
217 Standards, and does not work on platforms that have drive letters.  On
218 the other hand, it does better at avoiding recompilation issues, and
219 works well even when some directory options were not specified in terms
220 of @samp{$@{prefix@}} at @command{configure} time.
222 @node Optional Features
223 @section Optional Features
225 If the package supports it, you can cause programs to be installed with
226 an extra prefix or suffix on their names by giving @command{configure}
227 the option @option{--program-prefix=@var{PREFIX}} or
228 @option{--program-suffix=@var{SUFFIX}}.
230 Some packages pay attention to @option{--enable-@var{feature}} options
231 to @command{configure}, where @var{feature} indicates an optional part
232 of the package.  They may also pay attention to
233 @option{--with-@var{package}} options, where @var{package} is something
234 like @samp{gnu-as} or @samp{x} (for the X Window System).  The
235 @file{README} should mention any @option{--enable-} and @option{--with-}
236 options that the package recognizes.
238 For packages that use the X Window System, @command{configure} can
239 usually find the X include and library files automatically, but if it
240 doesn't, you can use the @command{configure} options
241 @option{--x-includes=@var{dir}} and @option{--x-libraries=@var{dir}} to
242 specify their locations.
244 Some packages offer the ability to configure how verbose the execution
245 of @command{make} will be.  For these packages, running
246 @samp{./configure --enable-silent-rules} sets the default to minimal
247 output, which can be overridden with @code{make V=1}; while running
248 @samp{./configure --disable-silent-rules} sets the default to verbose,
249 which can be overridden with @code{make V=0}.
251 @node Particular Systems
252 @section Particular systems
254 On HP-UX, the default C compiler is not ANSI C compatible.  If GNU CC is
255 not installed, it is recommended to use the following options in order to
256 use an ANSI C compiler:
258 @example
259 ./configure CC="cc -Ae -D_XOPEN_SOURCE=500"
260 @end example
262 @noindent
263 and if that doesn't work, install pre-built binaries of GCC for HP-UX.
265 On OSF/1 a.k.a.@: Tru64, some versions of the default C compiler cannot
266 parse its @code{<wchar.h>} header file.  The option @option{-nodtk} can be
267 used as a workaround.  If GNU CC is not installed, it is therefore
268 recommended to try
270 @example
271 ./configure CC="cc"
272 @end example
274 @noindent
275 and if that doesn't work, try
277 @example
278 ./configure CC="cc -nodtk"
279 @end example
281 On Solaris, don't put @code{/usr/ucb} early in your @env{PATH}.  This
282 directory contains several dysfunctional programs; working variants
283 of these programs are available in @code{/usr/bin}.  So, if you need
284 @code{/usr/ucb} in your @env{PATH}, put it @emph{after} @code{/usr/bin}.
286 On Haiku, software installed for all users goes in @file{/boot/common},
287 not @file{/usr/local}.  It is recommended to use the following options:
289 @example
290 ./configure --prefix=/boot/common
291 @end example
293 @node System Type
294 @section Specifying the System Type
296 There may be some features @command{configure} cannot figure out
297 automatically, but needs to determine by the type of machine the package
298 will run on.  Usually, assuming the package is built to be run on the
299 @emph{same} architectures, @command{configure} can figure that out, but
300 if it prints a message saying it cannot guess the machine type, give it
301 the @option{--build=@var{type}} option.  @var{type} can either be a
302 short name for the system type, such as @samp{sun4}, or a canonical name
303 which has the form:
305 @example
306 @var{cpu}-@var{company}-@var{system}
307 @end example
309 @noindent
310 where @var{system} can have one of these forms:
312 @example
313 @var{os}
314 @var{kernel}-@var{os}
315 @end example
317 See the file @file{config.sub} for the possible values of each field.
318 If @file{config.sub} isn't included in this package, then this package
319 doesn't need to know the machine type.
321 If you are @emph{building} compiler tools for cross-compiling, you
322 should use the option @option{--target=@var{type}} to select the type of
323 system they will produce code for.
325 If you want to @emph{use} a cross compiler, that generates code for a
326 platform different from the build platform, you should specify the
327 @dfn{host} platform (i.e., that on which the generated programs will
328 eventually be run) with @option{--host=@var{type}}.
330 @node Sharing Defaults
331 @section Sharing Defaults
333 If you want to set default values for @command{configure} scripts to
334 share, you can create a site shell script called @file{config.site} that
335 gives default values for variables like @code{CC}, @code{cache_file},
336 and @code{prefix}.  @command{configure} looks for
337 @file{@var{prefix}/share/config.site} if it exists, then
338 @file{@var{prefix}/etc/config.site} if it exists.  Or, you can set the
339 @code{CONFIG_SITE} environment variable to the location of the site
340 script.  A warning: not all @command{configure} scripts look for a site
341 script.
343 @node Defining Variables
344 @section Defining Variables
346 Variables not defined in a site shell script can be set in the
347 environment passed to @command{configure}.  However, some packages may
348 run configure again during the build, and the customized values of these
349 variables may be lost.  In order to avoid this problem, you should set
350 them in the @command{configure} command line, using @samp{VAR=value}.
351 For example:
353 @example
354 ./configure CC=/usr/local2/bin/gcc
355 @end example
357 @noindent
358 causes the specified @command{gcc} to be used as the C compiler (unless it is
359 overridden in the site shell script).
361 @noindent
362 Unfortunately, this technique does not work for @env{CONFIG_SHELL} due
363 to an Autoconf bug.  Until the bug is fixed you can use this
364 workaround:
366 @example
367 CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash
368 @end example
370 @node configure Invocation
371 @section @command{configure} Invocation
373 @command{configure} recognizes the following options to control how it
374 operates.
376 @table @option
377 @item --help
378 @itemx -h
379 Print a summary of all of the options to @command{configure}, and exit.
381 @item --help=short
382 @itemx --help=recursive
383 Print a summary of the options unique to this package's
384 @command{configure}, and exit.  The @code{short} variant lists options
385 used only in the top level, while the @code{recursive} variant lists
386 options also present in any nested packages.
388 @item --version
389 @itemx -V
390 Print the version of Autoconf used to generate the @command{configure}
391 script, and exit.
393 @item --cache-file=@var{file}
394 @cindex Cache, enabling
395 Enable the cache: use and save the results of the tests in @var{file},
396 traditionally @file{config.cache}.  @var{file} defaults to
397 @file{/dev/null} to disable caching.
399 @item --config-cache
400 @itemx -C
401 Alias for @option{--cache-file=config.cache}.
403 @item --quiet
404 @itemx --silent
405 @itemx -q
406 Do not print messages saying which checks are being made.  To suppress
407 all normal output, redirect it to @file{/dev/null} (any error messages
408 will still be shown).
410 @item --srcdir=@var{dir}
411 Look for the package's source code in directory @var{dir}.  Usually
412 @command{configure} can determine that directory automatically.
414 @item --prefix=@var{dir}
415 Use @var{dir} as the installation prefix.  @ref{Installation Names}
416 for more details, including other options available for fine-tuning
417 the installation locations.
419 @item --no-create
420 @itemx -n
421 Run the configure checks, but stop before creating any output files.
422 @end table
424 @noindent
425 @command{configure} also accepts some other, not widely useful, options.
426 Run @samp{configure --help} for more details.
428 @c Local Variables:
429 @c fill-column: 72
430 @c ispell-local-dictionary: "american"
431 @c indent-tabs-mode: nil
432 @c whitespace-check-buffer-indent: nil
433 @c End: