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