1@c This file is included by autoconf.texi and is used to produce 2@c the INSTALL file. 3 4@ifclear autoconf 5 6@unnumbered Installation Instructions 7 8Copyright @copyright{} 1994-1996, 1999-2002, 2004-2013 Free Software 9Foundation, Inc. 10 11Copying and distribution of this file, with or without modification, are 12permitted in any medium without royalty provided the copyright notice 13and this notice are preserved. This file is offered as-is, without 14warranty of any kind. 15 16@end ifclear 17 18@node Basic Installation 19@section Basic Installation 20 21Briefly, the shell command 22@samp{./configure@tie{}&& make@tie{}&& make@tie{}install} 23should configure, build, and install this package. The following 24more-detailed instructions are generic; see the @file{README} file for 25instructions specific to this package. 26@ifclear autoconf 27Some packages provide this @file{INSTALL} file but do not implement all 28of the features documented below. The lack of an optional feature in a 29given package is not necessarily a bug. 30@end ifclear 31More recommendations for GNU packages can be found in 32@ref{Makefile Conventions, , Makefile Conventions, standards, 33GNU Coding Standards}. 34 35The @command{configure} shell script attempts to guess correct values 36for various system-dependent variables used during compilation. It uses 37those values to create a @file{Makefile} in each directory of the 38package. It may also create one or more @file{.h} files containing 39system-dependent definitions. Finally, it creates a shell script 40@file{config.status} that you can run in the future to recreate the 41current configuration, and a file @file{config.log} containing compiler 42output (useful mainly for debugging @command{configure}). 43 44It can also use an optional file (typically called @file{config.cache} 45and enabled with @option{--cache-file=config.cache} or simply 46@option{-C}) that saves the results of its tests to speed up 47reconfiguring. Caching is disabled by default to prevent problems with 48accidental use of stale cache files. 49 50If you need to do unusual things to compile the package, please try to 51figure out how @command{configure} could check whether to do them, and 52mail diffs or instructions to the address given in the @file{README} so 53they can be considered for the next release. If you are using the 54cache, and at some point @file{config.cache} contains results you don't 55want to keep, you may remove or edit it. 56 57The 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}. 61 62The simplest way to compile this package is: 63 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. 68 69Running @command{configure} might take a while. While running, it prints some 70messages telling which features it is checking for. 71 72@item 73Type @samp{make} to compile the package. 74 75@item 76Optionally, type @samp{make check} to run any self-tests that come with 77the package, generally using the just-built uninstalled binaries. 78 79@item 80Type @samp{make install} to install the programs and any data files and 81documentation. When installing into a prefix owned by root, it is 82recommended that the package be configured and built as a regular user, 83and only the @samp{make install} phase executed with root privileges. 84 85@item 86Optionally, type @samp{make installcheck} to repeat any self-tests, but 87this time using the binaries in their final installed location. This 88target does not install anything. Running this target as a regular 89user, particularly if the prior @samp{make install} required root 90privileges, verifies that the installation completed correctly. 91 92@item 93You can remove the program binaries and object files from the source 94code directory by typing @samp{make clean}. To also remove the files 95that @command{configure} created (so you can compile the package for a 96different kind of computer), type @samp{make distclean}. There is also 97a @samp{make maintainer-clean} target, but that is intended mainly for 98the package's developers. If you use it, you may have to get all sorts 99of other programs in order to regenerate files that came with the 100distribution. 101 102@item 103Often, you can also type @samp{make uninstall} to remove the installed 104files again. In practice, not all packages have tested that 105uninstallation works correctly, even though it is required by the 106GNU Coding Standards. 107 108@item 109Some packages, particularly those that use Automake, provide @samp{make 110distcheck}, which can by used by developers to test that all other 111targets like @samp{make install} and @samp{make uninstall} work 112correctly. This target is generally not run by end users. 113@end enumerate 114 115@node Compilers and Options 116@section Compilers and Options 117 118Some 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. 121 122You can give @command{configure} initial values for configuration 123parameters by setting variables in the command line or in the environment. 124Here is an example: 125 126@example 127./configure CC=c99 CFLAGS=-g LIBS=-lposix 128@end example 129 130@xref{Defining Variables}, for more details. 131 132 133@node Multiple Architectures 134@section Compiling For Multiple Architectures 135 136You can compile the package for more than one kind of computer at the 137same time, by placing the object files for each architecture in their 138own directory. To do this, you can use GNU @command{make}. 139@command{cd} to the directory where you want the object files and 140executables to go and run the @command{configure} script. 141@command{configure} automatically checks for the source code in the 142directory that @command{configure} is in and in @file{..}. This is 143known as a @dfn{VPATH} build. 144 145With a non-GNU @command{make}, 146it is safer to compile the package for one 147architecture at a time in the source code directory. After you have 148installed the package for one architecture, use @samp{make distclean} 149before reconfiguring for another architecture. 150 151On MacOS X 10.5 and later systems, you can create libraries and 152executables that work on multiple system types---known as @dfn{fat} or 153@dfn{universal} binaries---by specifying multiple @option{-arch} options 154to the compiler but only a single @option{-arch} option to the 155preprocessor. Like this: 156 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 162 163This is not guaranteed to produce working output in all cases, you may 164have to build one architecture at a time and combine the results 165using the @command{lipo} tool if you have problems. 166 167@node Installation Names 168@section Installation Names 169 170By default, @samp{make install} installs the package's commands under 171@file{/usr/local/bin}, include files under @file{/usr/local/include}, etc. 172You can specify an 173installation 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. 176 177You can specify separate installation prefixes for architecture-specific 178files and architecture-independent files. If you pass the option 179@option{--exec-prefix=@var{prefix}} to @command{configure}, the 180package uses @var{prefix} as the prefix for installing programs and 181libraries. Documentation and other data files still use the 182regular prefix. 183 184In addition, if you use an unusual directory layout you can give options 185like @option{--bindir=@var{dir}} to specify different values for 186particular kinds of files. Run @samp{configure --help} for a list of 187the directories you can set and what kinds of files go in them. In 188general, the default for these options is expressed in terms of 189@samp{$@{prefix@}}, so that specifying just @option{--prefix} will 190affect all of the other directory specifications that were not 191explicitly provided. 192 193The most portable way to affect installation locations is to pass the 194correct locations to @command{configure}; however, many packages provide 195one or both of the following shortcuts of passing variable assignments 196to the @samp{make install} command line to change installation locations 197without having to reconfigure or recompile. 198 199The first method involves providing an override variable for each 200affected directory. For example, @samp{make install 201prefix=/alternate/directory} will choose an alternate location for all 202directory 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 205overridden at install time for the entire 206installation to be relocated. The approach of makefile variable 207overrides for each directory variable is required by the GNU 208Coding Standards, and ideally causes no recompilation. However, some 209platforms have known limitations with the semantics of shared libraries 210that end up requiring recompilation when using this method, particularly 211noticeable in packages that use GNU Libtool. 212 213The second method involves providing the @samp{DESTDIR} variable. For 214example, @samp{make install DESTDIR=/alternate/directory} will prepend 215@samp{/alternate/directory} before all installation names. The approach 216of @samp{DESTDIR} overrides is not required by the GNU Coding 217Standards, and does not work on platforms that have drive letters. On 218the other hand, it does better at avoiding recompilation issues, and 219works well even when some directory options were not specified in terms 220of @samp{$@{prefix@}} at @command{configure} time. 221 222@node Optional Features 223@section Optional Features 224 225If the package supports it, you can cause programs to be installed with 226an extra prefix or suffix on their names by giving @command{configure} 227the option @option{--program-prefix=@var{PREFIX}} or 228@option{--program-suffix=@var{SUFFIX}}. 229 230Some packages pay attention to @option{--enable-@var{feature}} options 231to @command{configure}, where @var{feature} indicates an optional part 232of the package. They may also pay attention to 233@option{--with-@var{package}} options, where @var{package} is something 234like @samp{gnu-as} or @samp{x} (for the X Window System). The 235@file{README} should mention any @option{--enable-} and @option{--with-} 236options that the package recognizes. 237 238For packages that use the X Window System, @command{configure} can 239usually find the X include and library files automatically, but if it 240doesn't, you can use the @command{configure} options 241@option{--x-includes=@var{dir}} and @option{--x-libraries=@var{dir}} to 242specify their locations. 243 244Some packages offer the ability to configure how verbose the execution 245of @command{make} will be. For these packages, running 246@samp{./configure --enable-silent-rules} sets the default to minimal 247output, which can be overridden with @code{make V=1}; while running 248@samp{./configure --disable-silent-rules} sets the default to verbose, 249which can be overridden with @code{make V=0}. 250 251@node Particular Systems 252@section Particular systems 253 254On HP-UX, the default C compiler is not ANSI C compatible. If GNU CC is 255not installed, it is recommended to use the following options in order to 256use an ANSI C compiler: 257 258@example 259./configure CC="cc -Ae -D_XOPEN_SOURCE=500" 260@end example 261 262@noindent 263and if that doesn't work, install pre-built binaries of GCC for HP-UX. 264 265HP-UX @command{make} updates targets which have the same time stamps as 266their prerequisites, which makes it generally unusable when shipped 267generated files such as @command{configure} are involved. Use GNU 268@command{make} instead. 269 270On OSF/1 a.k.a.@: Tru64, some versions of the default C compiler cannot 271parse its @code{<wchar.h>} header file. The option @option{-nodtk} can be 272used as a workaround. If GNU CC is not installed, it is therefore 273recommended to try 274 275@example 276./configure CC="cc" 277@end example 278 279@noindent 280and if that doesn't work, try 281 282@example 283./configure CC="cc -nodtk" 284@end example 285 286On Solaris, don't put @code{/usr/ucb} early in your @env{PATH}. This 287directory contains several dysfunctional programs; working variants 288of these programs are available in @code{/usr/bin}. So, if you need 289@code{/usr/ucb} in your @env{PATH}, put it @emph{after} @code{/usr/bin}. 290 291On Haiku, software installed for all users goes in @file{/boot/common}, 292not @file{/usr/local}. It is recommended to use the following options: 293 294@example 295./configure --prefix=/boot/common 296@end example 297 298@node System Type 299@section Specifying the System Type 300 301There may be some features @command{configure} cannot figure out 302automatically, but needs to determine by the type of machine the package 303will run on. Usually, assuming the package is built to be run on the 304@emph{same} architectures, @command{configure} can figure that out, but 305if it prints a message saying it cannot guess the machine type, give it 306the @option{--build=@var{type}} option. @var{type} can either be a 307short name for the system type, such as @samp{sun4}, or a canonical name 308which has the form: 309 310@example 311@var{cpu}-@var{company}-@var{system} 312@end example 313 314@noindent 315where @var{system} can have one of these forms: 316 317@example 318@var{os} 319@var{kernel}-@var{os} 320@end example 321 322See the file @file{config.sub} for the possible values of each field. 323If @file{config.sub} isn't included in this package, then this package 324doesn't need to know the machine type. 325 326If you are @emph{building} compiler tools for cross-compiling, you 327should use the option @option{--target=@var{type}} to select the type of 328system they will produce code for. 329 330If you want to @emph{use} a cross compiler, that generates code for a 331platform different from the build platform, you should specify the 332@dfn{host} platform (i.e., that on which the generated programs will 333eventually be run) with @option{--host=@var{type}}. 334 335@node Sharing Defaults 336@section Sharing Defaults 337 338If you want to set default values for @command{configure} scripts to 339share, you can create a site shell script called @file{config.site} that 340gives default values for variables like @code{CC}, @code{cache_file}, 341and @code{prefix}. @command{configure} looks for 342@file{@var{prefix}/share/config.site} if it exists, then 343@file{@var{prefix}/etc/config.site} if it exists. Or, you can set the 344@code{CONFIG_SITE} environment variable to the location of the site 345script. A warning: not all @command{configure} scripts look for a site 346script. 347 348@node Defining Variables 349@section Defining Variables 350 351Variables not defined in a site shell script can be set in the 352environment passed to @command{configure}. However, some packages may 353run configure again during the build, and the customized values of these 354variables may be lost. In order to avoid this problem, you should set 355them in the @command{configure} command line, using @samp{VAR=value}. 356For example: 357 358@example 359./configure CC=/usr/local2/bin/gcc 360@end example 361 362@noindent 363causes the specified @command{gcc} to be used as the C compiler (unless it is 364overridden in the site shell script). 365 366@noindent 367Unfortunately, this technique does not work for @env{CONFIG_SHELL} due 368to an Autoconf limitation. Until the limitation is lifted, you can use 369this workaround: 370 371@example 372CONFIG_SHELL=/bin/bash ./configure CONFIG_SHELL=/bin/bash 373@end example 374 375@node configure Invocation 376@section @command{configure} Invocation 377 378@command{configure} recognizes the following options to control how it 379operates. 380 381@table @option 382@item --help 383@itemx -h 384Print a summary of all of the options to @command{configure}, and exit. 385 386@item --help=short 387@itemx --help=recursive 388Print a summary of the options unique to this package's 389@command{configure}, and exit. The @code{short} variant lists options 390used only in the top level, while the @code{recursive} variant lists 391options also present in any nested packages. 392 393@item --version 394@itemx -V 395Print the version of Autoconf used to generate the @command{configure} 396script, and exit. 397 398@item --cache-file=@var{file} 399@cindex Cache, enabling 400Enable the cache: use and save the results of the tests in @var{file}, 401traditionally @file{config.cache}. @var{file} defaults to 402@file{/dev/null} to disable caching. 403 404@item --config-cache 405@itemx -C 406Alias for @option{--cache-file=config.cache}. 407 408@item --quiet 409@itemx --silent 410@itemx -q 411Do not print messages saying which checks are being made. To suppress 412all normal output, redirect it to @file{/dev/null} (any error messages 413will still be shown). 414 415@item --srcdir=@var{dir} 416Look for the package's source code in directory @var{dir}. Usually 417@command{configure} can determine that directory automatically. 418 419@item --prefix=@var{dir} 420Use @var{dir} as the installation prefix. @ref{Installation Names} 421for more details, including other options available for fine-tuning 422the installation locations. 423 424@item --no-create 425@itemx -n 426Run the configure checks, but stop before creating any output files. 427@end table 428 429@noindent 430@command{configure} also accepts some other, not widely useful, options. 431Run @samp{configure --help} for more details. 432 433@c Local Variables: 434@c fill-column: 72 435@c ispell-local-dictionary: "american" 436@c indent-tabs-mode: nil 437@c whitespace-check-buffer-indent: nil 438@c End: 439