Treat Haiku like BeOS.
[gnulib.git] / doc / install.texi
1 @c This file is included by autoconf.texi and is used to produce
2 @c the INSTALL file.
3
4 @ifclear autoconf
5 @firstparagraphindent insert
6
7 @unnumbered Installation Instructions
8
9 Copyright @copyright{} 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004,
10 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
11
12 This file is free documentation; the Free Software Foundation gives
13 unlimited permission to copy, distribute and modify it.
14
15 @end ifclear
16
17 @node Basic Installation
18 @section Basic Installation
19
20 Briefly, the shell commands @samp{./configure; make; make install}
21 should configure, build, and install this package.  The following
22 more-detailed instructions are generic; see the @file{README} file for
23 instructions specific to this package.
24
25 The @command{configure} shell script attempts to guess correct values
26 for various system-dependent variables used during compilation.  It uses
27 those values to create a @file{Makefile} in each directory of the
28 package.  It may also create one or more @file{.h} files containing
29 system-dependent definitions.  Finally, it creates a shell script
30 @file{config.status} that you can run in the future to recreate the
31 current configuration, and a file @file{config.log} containing compiler
32 output (useful mainly for debugging @command{configure}).
33
34 It can also use an optional file (typically called @file{config.cache}
35 and enabled with @option{--cache-file=config.cache} or simply
36 @option{-C}) that saves the results of its tests to speed up
37 reconfiguring.  Caching is disabled by default to prevent problems with
38 accidental use of stale cache files.
39
40 If you need to do unusual things to compile the package, please try to
41 figure out how @command{configure} could check whether to do them, and
42 mail diffs or instructions to the address given in the @file{README} so
43 they can be considered for the next release.  If you are using the
44 cache, and at some point @file{config.cache} contains results you don't
45 want to keep, you may remove or edit it.
46
47 The file @file{configure.ac} (or @file{configure.in}) is used to create
48 @file{configure} by a program called @code{autoconf}.  You need
49 @file{configure.ac} if you want to change it or regenerate
50 @file{configure} using a newer version of @code{autoconf}.
51
52 @noindent
53 The simplest way to compile this package is:
54
55 @enumerate
56 @item
57 @code{cd} to the directory containing the package's source code and type
58 @samp{./configure} to configure the package for your system.
59
60 Running @command{configure} might take a while.  While running, it prints some
61 messages telling which features it is checking for.
62
63 @item
64 Type @samp{make} to compile the package.
65
66 @item
67 Optionally, type @samp{make check} to run any self-tests that come with
68 the package.
69
70 @item
71 Type @samp{make install} to install the programs and any data files and
72 documentation.
73
74 @item
75 You can remove the program binaries and object files from the source
76 code directory by typing @samp{make clean}.  To also remove the files
77 that @command{configure} created (so you can compile the package for a
78 different kind of computer), type @samp{make distclean}.  There is also
79 a @samp{make maintainer-clean} target, but that is intended mainly for
80 the package's developers.  If you use it, you may have to get all sorts
81 of other programs in order to regenerate files that came with the
82 distribution.
83
84 @item
85 Often, you can also type @samp{make uninstall} to remove the installed
86 files again.
87 @end enumerate
88
89 @node Compilers and Options
90 @section Compilers and Options
91
92 Some systems require unusual options for compilation or linking that the
93 @command{configure} script does not know about.  Run @samp{./configure
94 --help} for details on some of the pertinent environment variables.
95
96 You can give @command{configure} initial values for configuration
97 parameters by setting variables in the command line or in the environment.
98 Here is an example:
99
100 @example
101 ./configure CC=c99 CFLAGS=-g LIBS=-lposix
102 @end example
103
104 @xref{Defining Variables}, for more details.
105
106
107 @node Multiple Architectures
108 @section Compiling For Multiple Architectures
109
110 You can compile the package for more than one kind of computer at the
111 same time, by placing the object files for each architecture in their
112 own directory.  To do this, you can use @acronym{GNU} @command{make}.
113 @command{cd} to the directory where you want the object files and
114 executables to go and run the @command{configure} script.
115 @command{configure} automatically checks for the source code in the
116 directory that @command{configure} is in and in @file{..}.
117
118 With a non-@acronym{GNU} @command{make},
119 it is safer to compile the package for one
120 architecture at a time in the source code directory.  After you have
121 installed the package for one architecture, use @samp{make distclean}
122 before reconfiguring for another architecture.
123
124 On MacOS X 10.5 and later systems, you can create libraries and
125 executables that work on multiple system types---known as @dfn{fat} or
126 @dfn{universal} binaries---by specifying multiple @option{-arch} options
127 to the compiler but only a single @option{-arch} option to the
128 preprocessor.  Like this:
129
130 @example
131 ./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
132             CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
133             CPP="gcc -E" CXXCPP="g++ -E"
134 @end example
135
136 This is not guaranteed to produce working output in all cases, you may
137 have to build one architecture at a time and combine the results
138 using the @command{lipo} tool if you have problems.
139
140 @node Installation Names
141 @section Installation Names
142
143 By default, @samp{make install} installs the package's commands under
144 @file{/usr/local/bin}, include files under @file{/usr/local/include}, etc.
145 You can specify an
146 installation prefix other than @file{/usr/local} by giving
147 @command{configure} the option @option{--prefix=@var{prefix}}.
148
149 You can specify separate installation prefixes for architecture-specific
150 files and architecture-independent files.  If you pass the option
151 @option{--exec-prefix=@var{prefix}} to @command{configure}, the
152 package uses @var{prefix} as the prefix for installing programs and
153 libraries.  Documentation and other data files still use the
154 regular prefix.
155
156 In addition, if you use an unusual directory layout you can give options
157 like @option{--bindir=@var{dir}} to specify different values for
158 particular kinds of files.  Run @samp{configure --help} for a list of
159 the directories you can set and what kinds of files go in them.
160
161 If the package supports it, you can cause programs to be installed with
162 an extra prefix or suffix on their names by giving @command{configure}
163 the option @option{--program-prefix=@var{PREFIX}} or
164 @option{--program-suffix=@var{SUFFIX}}.
165
166 @node Optional Features
167 @section Optional Features
168
169 Some packages pay attention to @option{--enable-@var{feature}} options
170 to @command{configure}, where @var{feature} indicates an optional part
171 of the package.  They may also pay attention to
172 @option{--with-@var{package}} options, where @var{package} is something
173 like @samp{gnu-as} or @samp{x} (for the X Window System).  The
174 @file{README} should mention any @option{--enable-} and @option{--with-}
175 options that the package recognizes.
176
177 For packages that use the X Window System, @command{configure} can
178 usually find the X include and library files automatically, but if it
179 doesn't, you can use the @command{configure} options
180 @option{--x-includes=@var{dir}} and @option{--x-libraries=@var{dir}} to
181 specify their locations.
182
183 @node Particular Systems
184 @section Particular systems
185
186 On HP-UX, the default C compiler is not ANSI C compatible.  If GNU CC is
187 not installed, it is recommended to use the following options in order to
188 use an ANSI C compiler:
189
190 @example
191 ./configure CC="cc -Ae"
192 @end example
193
194 @noindent
195 and if that doesn't work, install pre-built binaries of GCC for HP-UX.
196
197 On OSF/1 a.k.a.@: Tru64, some versions of the default C compiler cannot
198 parse its @code{<wchar.h>} header file.  The option @option{-nodtk} can be
199 used as a workaround.  If GNU CC is not installed, it is therefore
200 recommended to try
201
202 @example
203 ./configure CC="cc"
204 @end example
205
206 @noindent
207 and if that doesn't work, try
208
209 @example
210 ./configure CC="cc -nodtk"
211 @end example
212
213 On Solaris, don't put @code{/usr/ucb} early in your @env{PATH}.  This
214 directory contains several dysfunctional programs; working variants
215 of these programs are available in @code{/usr/bin}.  So, if you need
216 @code{/usr/ucb} in your @env{PATH}, put it @emph{after} @code{/usr/bin}.
217
218 @node System Type
219 @section Specifying the System Type
220
221 There may be some features @command{configure} cannot figure out
222 automatically, but needs to determine by the type of machine the package
223 will run on.  Usually, assuming the package is built to be run on the
224 @emph{same} architectures, @command{configure} can figure that out, but
225 if it prints a message saying it cannot guess the machine type, give it
226 the @option{--build=@var{type}} option.  @var{type} can either be a
227 short name for the system type, such as @samp{sun4}, or a canonical name
228 which has the form:
229
230 @example
231 @var{cpu}-@var{company}-@var{system}
232 @end example
233
234 @noindent
235 where @var{system} can have one of these forms:
236
237 @example
238 @var{os} @var{kernel}-@var{os}
239 @end example
240
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.
244
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.
248
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}}.
253
254 @node Sharing Defaults
255 @section Sharing Defaults
256
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
265 script.
266
267 @node Defining Variables
268 @section Defining Variables
269
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}.
275 For example:
276
277 @example
278 ./configure CC=/usr/local2/bin/gcc
279 @end example
280
281 @noindent
282 causes the specified @command{gcc} to be used as the C compiler (unless it is
283 overridden in the site shell script).
284
285 @noindent
286 Unfortunately, this technique does not work for @env{CONFIG_SHELL} due
287 to an Autoconf bug.  Until the bug is fixed you can use this
288 workaround:
289
290 @example
291 CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash
292 @end example
293
294 @node configure Invocation
295 @section @command{configure} Invocation
296
297 @command{configure} recognizes the following options to control how it
298 operates.
299
300 @table @option
301 @item --help
302 @itemx -h
303 Print a summary of all of the options to @command{configure}, and exit.
304
305 @item --help=short
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.
311
312 @item --version
313 @itemx -V
314 Print the version of Autoconf used to generate the @command{configure}
315 script, and exit.
316
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.
322
323 @item --config-cache
324 @itemx -C
325 Alias for @option{--cache-file=config.cache}.
326
327 @item --quiet
328 @itemx --silent
329 @itemx -q
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).
333
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.
337
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.
342
343 @item --no-create
344 @itemx -n
345 Run the configure checks, but stop before creating any output files.
346 @end table
347
348 @noindent
349 @command{configure} also accepts some other, not widely useful, options.
350 Run @samp{configure --help} for more details.
351
352 @c Local Variables:
353 @c fill-column: 72
354 @c ispell-local-dictionary: "american"
355 @c indent-tabs-mode: nil
356 @c whitespace-check-buffer-indent: nil
357 @c End: