INSTALL revision 269851
1251883SpeterInstallation Instructions 2251883Speter************************* 3251883Speter 4269851SpeterCopyright (C) 1994-1996, 1999-2002, 2004-2011 Free Software Foundation, 5269851SpeterInc. 6251883Speter 7269851Speter Copying and distribution of this file, with or without modification, 8269851Speterare permitted in any medium without royalty provided the copyright 9269851Speternotice and this notice are preserved. This file is offered as-is, 10269851Speterwithout warranty of any kind. 11251883Speter 12251883SpeterBasic Installation 13251883Speter================== 14251883Speter 15269851Speter Briefly, the shell commands `./configure; make; make install' should 16269851Speterconfigure, build, and install this package. The following 17269851Spetermore-detailed instructions are generic; see the `README' file for 18269851Speterinstructions specific to this package. Some packages provide this 19269851Speter`INSTALL' file but do not implement all of the features documented 20269851Speterbelow. The lack of an optional feature in a given package is not 21269851Speternecessarily a bug. More recommendations for GNU packages can be found 22269851Speterin *note Makefile Conventions: (standards)Makefile Conventions. 23251883Speter 24251883Speter The `configure' shell script attempts to guess correct values for 25251883Spetervarious system-dependent variables used during compilation. It uses 26251883Speterthose values to create a `Makefile' in each directory of the package. 27251883SpeterIt may also create one or more `.h' files containing system-dependent 28251883Speterdefinitions. Finally, it creates a shell script `config.status' that 29251883Speteryou can run in the future to recreate the current configuration, and a 30251883Speterfile `config.log' containing compiler output (useful mainly for 31251883Speterdebugging `configure'). 32251883Speter 33251883Speter It can also use an optional file (typically called `config.cache' 34251883Speterand enabled with `--cache-file=config.cache' or simply `-C') that saves 35269851Speterthe results of its tests to speed up reconfiguring. Caching is 36251883Speterdisabled by default to prevent problems with accidental use of stale 37269851Spetercache files. 38251883Speter 39251883Speter If you need to do unusual things to compile the package, please try 40251883Speterto figure out how `configure' could check whether to do them, and mail 41251883Speterdiffs or instructions to the address given in the `README' so they can 42251883Speterbe considered for the next release. If you are using the cache, and at 43251883Spetersome point `config.cache' contains results you don't want to keep, you 44251883Spetermay remove or edit it. 45251883Speter 46251883Speter The file `configure.ac' (or `configure.in') is used to create 47269851Speter`configure' by a program called `autoconf'. You need `configure.ac' if 48269851Speteryou want to change it or regenerate `configure' using a newer version 49269851Speterof `autoconf'. 50251883Speter 51269851Speter The simplest way to compile this package is: 52251883Speter 53251883Speter 1. `cd' to the directory containing the package's source code and type 54269851Speter `./configure' to configure the package for your system. 55251883Speter 56269851Speter Running `configure' might take a while. While running, it prints 57269851Speter some messages telling which features it is checking for. 58251883Speter 59251883Speter 2. Type `make' to compile the package. 60251883Speter 61251883Speter 3. Optionally, type `make check' to run any self-tests that come with 62269851Speter the package, generally using the just-built uninstalled binaries. 63251883Speter 64251883Speter 4. Type `make install' to install the programs and any data files and 65269851Speter documentation. When installing into a prefix owned by root, it is 66269851Speter recommended that the package be configured and built as a regular 67269851Speter user, and only the `make install' phase executed with root 68269851Speter privileges. 69251883Speter 70269851Speter 5. Optionally, type `make installcheck' to repeat any self-tests, but 71269851Speter this time using the binaries in their final installed location. 72269851Speter This target does not install anything. Running this target as a 73269851Speter regular user, particularly if the prior `make install' required 74269851Speter root privileges, verifies that the installation completed 75269851Speter correctly. 76269851Speter 77269851Speter 6. You can remove the program binaries and object files from the 78251883Speter source code directory by typing `make clean'. To also remove the 79251883Speter files that `configure' created (so you can compile the package for 80251883Speter a different kind of computer), type `make distclean'. There is 81251883Speter also a `make maintainer-clean' target, but that is intended mainly 82251883Speter for the package's developers. If you use it, you may have to get 83251883Speter all sorts of other programs in order to regenerate files that came 84251883Speter with the distribution. 85251883Speter 86269851Speter 7. Often, you can also type `make uninstall' to remove the installed 87269851Speter files again. In practice, not all packages have tested that 88269851Speter uninstallation works correctly, even though it is required by the 89269851Speter GNU Coding Standards. 90269851Speter 91269851Speter 8. Some packages, particularly those that use Automake, provide `make 92269851Speter distcheck', which can by used by developers to test that all other 93269851Speter targets like `make install' and `make uninstall' work correctly. 94269851Speter This target is generally not run by end users. 95269851Speter 96251883SpeterCompilers and Options 97251883Speter===================== 98251883Speter 99269851Speter Some systems require unusual options for compilation or linking that 100269851Speterthe `configure' script does not know about. Run `./configure --help' 101269851Speterfor details on some of the pertinent environment variables. 102251883Speter 103251883Speter You can give `configure' initial values for configuration parameters 104251883Speterby setting variables in the command line or in the environment. Here 105251883Speteris an example: 106251883Speter 107269851Speter ./configure CC=c99 CFLAGS=-g LIBS=-lposix 108251883Speter 109251883Speter *Note Defining Variables::, for more details. 110251883Speter 111251883SpeterCompiling For Multiple Architectures 112251883Speter==================================== 113251883Speter 114269851Speter You can compile the package for more than one kind of computer at the 115251883Spetersame time, by placing the object files for each architecture in their 116269851Speterown directory. To do this, you can use GNU `make'. `cd' to the 117251883Speterdirectory where you want the object files and executables to go and run 118251883Speterthe `configure' script. `configure' automatically checks for the 119269851Spetersource code in the directory that `configure' is in and in `..'. This 120269851Speteris known as a "VPATH" build. 121251883Speter 122269851Speter With a non-GNU `make', it is safer to compile the package for one 123269851Speterarchitecture at a time in the source code directory. After you have 124269851Speterinstalled the package for one architecture, use `make distclean' before 125269851Speterreconfiguring for another architecture. 126251883Speter 127269851Speter On MacOS X 10.5 and later systems, you can create libraries and 128269851Speterexecutables that work on multiple system types--known as "fat" or 129269851Speter"universal" binaries--by specifying multiple `-arch' options to the 130269851Spetercompiler but only a single `-arch' option to the preprocessor. Like 131269851Speterthis: 132269851Speter 133269851Speter ./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \ 134269851Speter CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \ 135269851Speter CPP="gcc -E" CXXCPP="g++ -E" 136269851Speter 137269851Speter This is not guaranteed to produce working output in all cases, you 138269851Spetermay have to build one architecture at a time and combine the results 139269851Speterusing the `lipo' tool if you have problems. 140269851Speter 141251883SpeterInstallation Names 142251883Speter================== 143251883Speter 144269851Speter By default, `make install' installs the package's commands under 145251883Speter`/usr/local/bin', include files under `/usr/local/include', etc. You 146251883Spetercan specify an installation prefix other than `/usr/local' by giving 147269851Speter`configure' the option `--prefix=PREFIX', where PREFIX must be an 148269851Speterabsolute file name. 149251883Speter 150251883Speter You can specify separate installation prefixes for 151251883Speterarchitecture-specific files and architecture-independent files. If you 152251883Speterpass the option `--exec-prefix=PREFIX' to `configure', the package uses 153251883SpeterPREFIX as the prefix for installing programs and libraries. 154251883SpeterDocumentation and other data files still use the regular prefix. 155251883Speter 156251883Speter In addition, if you use an unusual directory layout you can give 157251883Speteroptions like `--bindir=DIR' to specify different values for particular 158251883Speterkinds of files. Run `configure --help' for a list of the directories 159269851Speteryou can set and what kinds of files go in them. In general, the 160269851Speterdefault for these options is expressed in terms of `${prefix}', so that 161269851Speterspecifying just `--prefix' will affect all of the other directory 162269851Speterspecifications that were not explicitly provided. 163251883Speter 164269851Speter The most portable way to affect installation locations is to pass the 165269851Spetercorrect locations to `configure'; however, many packages provide one or 166269851Speterboth of the following shortcuts of passing variable assignments to the 167269851Speter`make install' command line to change installation locations without 168269851Speterhaving to reconfigure or recompile. 169269851Speter 170269851Speter The first method involves providing an override variable for each 171269851Speteraffected directory. For example, `make install 172269851Speterprefix=/alternate/directory' will choose an alternate location for all 173269851Speterdirectory configuration variables that were expressed in terms of 174269851Speter`${prefix}'. Any directories that were specified during `configure', 175269851Speterbut not in terms of `${prefix}', must each be overridden at install 176269851Spetertime for the entire installation to be relocated. The approach of 177269851Spetermakefile variable overrides for each directory variable is required by 178269851Speterthe GNU Coding Standards, and ideally causes no recompilation. 179269851SpeterHowever, some platforms have known limitations with the semantics of 180269851Spetershared libraries that end up requiring recompilation when using this 181269851Spetermethod, particularly noticeable in packages that use GNU Libtool. 182269851Speter 183269851Speter The second method involves providing the `DESTDIR' variable. For 184269851Speterexample, `make install DESTDIR=/alternate/directory' will prepend 185269851Speter`/alternate/directory' before all installation names. The approach of 186269851Speter`DESTDIR' overrides is not required by the GNU Coding Standards, and 187269851Speterdoes not work on platforms that have drive letters. On the other hand, 188269851Speterit does better at avoiding recompilation issues, and works well even 189269851Speterwhen some directory options were not specified in terms of `${prefix}' 190269851Speterat `configure' time. 191269851Speter 192269851SpeterOptional Features 193269851Speter================= 194269851Speter 195251883Speter If the package supports it, you can cause programs to be installed 196251883Speterwith an extra prefix or suffix on their names by giving `configure' the 197251883Speteroption `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. 198251883Speter 199269851Speter Some packages pay attention to `--enable-FEATURE' options to 200251883Speter`configure', where FEATURE indicates an optional part of the package. 201251883SpeterThey may also pay attention to `--with-PACKAGE' options, where PACKAGE 202251883Speteris something like `gnu-as' or `x' (for the X Window System). The 203251883Speter`README' should mention any `--enable-' and `--with-' options that the 204251883Speterpackage recognizes. 205251883Speter 206251883Speter For packages that use the X Window System, `configure' can usually 207251883Speterfind the X include and library files automatically, but if it doesn't, 208251883Speteryou can use the `configure' options `--x-includes=DIR' and 209251883Speter`--x-libraries=DIR' to specify their locations. 210251883Speter 211269851Speter Some packages offer the ability to configure how verbose the 212269851Speterexecution of `make' will be. For these packages, running `./configure 213269851Speter--enable-silent-rules' sets the default to minimal output, which can be 214269851Speteroverridden with `make V=1'; while running `./configure 215269851Speter--disable-silent-rules' sets the default to verbose, which can be 216269851Speteroverridden with `make V=0'. 217269851Speter 218269851SpeterParticular systems 219269851Speter================== 220269851Speter 221269851Speter On HP-UX, the default C compiler is not ANSI C compatible. If GNU 222269851SpeterCC is not installed, it is recommended to use the following options in 223269851Speterorder to use an ANSI C compiler: 224269851Speter 225269851Speter ./configure CC="cc -Ae -D_XOPEN_SOURCE=500" 226269851Speter 227269851Speterand if that doesn't work, install pre-built binaries of GCC for HP-UX. 228269851Speter 229269851Speter HP-UX `make' updates targets which have the same time stamps as 230269851Spetertheir prerequisites, which makes it generally unusable when shipped 231269851Spetergenerated files such as `configure' are involved. Use GNU `make' 232269851Speterinstead. 233269851Speter 234269851Speter On OSF/1 a.k.a. Tru64, some versions of the default C compiler cannot 235269851Speterparse its `<wchar.h>' header file. The option `-nodtk' can be used as 236269851Spetera workaround. If GNU CC is not installed, it is therefore recommended 237269851Speterto try 238269851Speter 239269851Speter ./configure CC="cc" 240269851Speter 241269851Speterand if that doesn't work, try 242269851Speter 243269851Speter ./configure CC="cc -nodtk" 244269851Speter 245269851Speter On Solaris, don't put `/usr/ucb' early in your `PATH'. This 246269851Speterdirectory contains several dysfunctional programs; working variants of 247269851Speterthese programs are available in `/usr/bin'. So, if you need `/usr/ucb' 248269851Speterin your `PATH', put it _after_ `/usr/bin'. 249269851Speter 250269851Speter On Haiku, software installed for all users goes in `/boot/common', 251269851Speternot `/usr/local'. It is recommended to use the following options: 252269851Speter 253269851Speter ./configure --prefix=/boot/common 254269851Speter 255251883SpeterSpecifying the System Type 256251883Speter========================== 257251883Speter 258269851Speter There may be some features `configure' cannot figure out 259269851Speterautomatically, but needs to determine by the type of machine the package 260269851Speterwill run on. Usually, assuming the package is built to be run on the 261269851Speter_same_ architectures, `configure' can figure that out, but if it prints 262269851Spetera message saying it cannot guess the machine type, give it the 263251883Speter`--build=TYPE' option. TYPE can either be a short name for the system 264251883Spetertype, such as `sun4', or a canonical name which has the form: 265251883Speter 266251883Speter CPU-COMPANY-SYSTEM 267251883Speter 268251883Speterwhere SYSTEM can have one of these forms: 269251883Speter 270269851Speter OS 271269851Speter KERNEL-OS 272251883Speter 273251883Speter See the file `config.sub' for the possible values of each field. If 274251883Speter`config.sub' isn't included in this package, then this package doesn't 275251883Speterneed to know the machine type. 276251883Speter 277251883Speter If you are _building_ compiler tools for cross-compiling, you should 278251883Speteruse the option `--target=TYPE' to select the type of system they will 279251883Speterproduce code for. 280251883Speter 281251883Speter If you want to _use_ a cross compiler, that generates code for a 282251883Speterplatform different from the build platform, you should specify the 283251883Speter"host" platform (i.e., that on which the generated programs will 284251883Spetereventually be run) with `--host=TYPE'. 285251883Speter 286251883SpeterSharing Defaults 287251883Speter================ 288251883Speter 289269851Speter If you want to set default values for `configure' scripts to share, 290269851Speteryou can create a site shell script called `config.site' that gives 291269851Speterdefault values for variables like `CC', `cache_file', and `prefix'. 292251883Speter`configure' looks for `PREFIX/share/config.site' if it exists, then 293251883Speter`PREFIX/etc/config.site' if it exists. Or, you can set the 294251883Speter`CONFIG_SITE' environment variable to the location of the site script. 295251883SpeterA warning: not all `configure' scripts look for a site script. 296251883Speter 297251883SpeterDefining Variables 298251883Speter================== 299251883Speter 300269851Speter Variables not defined in a site shell script can be set in the 301251883Speterenvironment passed to `configure'. However, some packages may run 302251883Speterconfigure again during the build, and the customized values of these 303251883Spetervariables may be lost. In order to avoid this problem, you should set 304251883Speterthem in the `configure' command line, using `VAR=value'. For example: 305251883Speter 306251883Speter ./configure CC=/usr/local2/bin/gcc 307251883Speter 308251883Spetercauses the specified `gcc' to be used as the C compiler (unless it is 309269851Speteroverridden in the site shell script). 310251883Speter 311269851SpeterUnfortunately, this technique does not work for `CONFIG_SHELL' due to 312269851Speteran Autoconf bug. Until the bug is fixed you can use this workaround: 313251883Speter 314269851Speter CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash 315251883Speter 316251883Speter`configure' Invocation 317251883Speter====================== 318251883Speter 319269851Speter `configure' recognizes the following options to control how it 320269851Speteroperates. 321251883Speter 322251883Speter`--help' 323251883Speter`-h' 324269851Speter Print a summary of all of the options to `configure', and exit. 325251883Speter 326269851Speter`--help=short' 327269851Speter`--help=recursive' 328269851Speter Print a summary of the options unique to this package's 329269851Speter `configure', and exit. The `short' variant lists options used 330269851Speter only in the top level, while the `recursive' variant lists options 331269851Speter also present in any nested packages. 332269851Speter 333251883Speter`--version' 334251883Speter`-V' 335251883Speter Print the version of Autoconf used to generate the `configure' 336251883Speter script, and exit. 337251883Speter 338251883Speter`--cache-file=FILE' 339251883Speter Enable the cache: use and save the results of the tests in FILE, 340251883Speter traditionally `config.cache'. FILE defaults to `/dev/null' to 341251883Speter disable caching. 342251883Speter 343251883Speter`--config-cache' 344251883Speter`-C' 345251883Speter Alias for `--cache-file=config.cache'. 346251883Speter 347251883Speter`--quiet' 348251883Speter`--silent' 349251883Speter`-q' 350251883Speter Do not print messages saying which checks are being made. To 351251883Speter suppress all normal output, redirect it to `/dev/null' (any error 352251883Speter messages will still be shown). 353251883Speter 354251883Speter`--srcdir=DIR' 355251883Speter Look for the package's source code in directory DIR. Usually 356251883Speter `configure' can determine that directory automatically. 357251883Speter 358269851Speter`--prefix=DIR' 359269851Speter Use DIR as the installation prefix. *note Installation Names:: 360269851Speter for more details, including other options available for fine-tuning 361269851Speter the installation locations. 362269851Speter 363269851Speter`--no-create' 364269851Speter`-n' 365269851Speter Run the configure checks, but stop before creating any output 366269851Speter files. 367269851Speter 368251883Speter`configure' also accepts some other, not widely useful, options. Run 369251883Speter`configure --help' for more details. 370251883Speter 371