INSTALL (16377B)
1 Installation Instructions 2 ************************* 3 4 Basic Installation 5 ================== 6 7 The following shell commands: 8 9 test -f configure || ./bootstrap 10 ./configure 11 make 12 make install 13 14 should configure, build, and install this package. The first line, 15 which bootstraps, is intended for developers; when building from 16 distribution tarballs it does nothing and can be skipped. 17 18 The following more-detailed instructions are generic; see the 19 ‘README’ file for instructions specific to this package. Some packages 20 provide this ‘INSTALL’ file but do not implement all of the features 21 documented below. The lack of an optional feature in a given package is 22 not necessarily a bug. More recommendations for GNU packages can be 23 found in the GNU Coding Standards. 24 25 Many packages have scripts meant for developers instead of ordinary 26 builders, as they may use developer tools that are less commonly 27 installed, or they may access the network, which has privacy 28 implications. If the ‘bootstrap’ shell script exists, it attempts to 29 build the ‘configure’ shell script and related files, possibly using 30 developer tools or the network. Because the output of ‘bootstrap’ is 31 system-independent, it is normally run by a package developer so that 32 its output can be put into the distribution tarball and ordinary 33 builders and users need not run ‘bootstrap’. Some packages have 34 commands like ‘./autopull.sh’ and ‘./autogen.sh’ that you can run 35 instead of ‘./bootstrap’, for more fine-grained control over 36 bootstrapping. 37 38 The ‘configure’ shell script attempts to guess correct values for 39 various system-dependent variables used during compilation. It uses 40 those values to create a ‘Makefile’ in each directory of the package. 41 It may also create one or more ‘.h’ files containing system-dependent 42 definitions. Finally, it creates a shell script ‘config.status’ that 43 you can run in the future to recreate the current configuration, and a 44 file ‘config.log’ containing output useful for debugging ‘configure’. 45 46 It can also use an optional file (typically called ‘config.cache’ and 47 enabled with ‘--cache-file=config.cache’ or simply ‘-C’) that saves the 48 results of its tests to speed up reconfiguring. Caching is disabled by 49 default to prevent problems with accidental use of stale cache files. 50 51 If you need to do unusual things to compile the package, please try 52 to figure out how ‘configure’ could check whether to do them, and mail 53 diffs or instructions to the address given in the ‘README’ so they can 54 be considered for the next release. If you are using the cache, and at 55 some point ‘config.cache’ contains results you don’t want to keep, you 56 may remove or edit it. 57 58 The ‘autoconf’ program generates ‘configure’ from the file 59 ‘configure.ac’. Normally you should edit ‘configure.ac’ instead of 60 editing ‘configure’ directly. 61 62 The simplest way to compile this package is: 63 64 1. ‘cd’ to the directory containing the package’s source code. 65 66 2. If this is a developer checkout and file ‘configure’ does not yet 67 exist, type ‘./bootstrap’ to create it. You may need special 68 developer tools and network access to bootstrap, and the network 69 access may have privacy implications. 70 71 3. Type ‘./configure’ to configure the package for your system. This 72 might take a while. While running, ‘configure’ prints messages 73 telling which features it is checking for. 74 75 4. Type ‘make’ to compile the package. 76 77 5. Optionally, type ‘make check’ to run any self-tests that come with 78 the package, generally using the just-built uninstalled binaries. 79 80 6. Type ‘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 83 user, and only the ‘make install’ phase executed with root 84 privileges. 85 86 7. Optionally, type ‘make installcheck’ to repeat any self-tests, but 87 this time using the binaries in their final installed location. 88 This target does not install anything. Running this target as a 89 regular user, particularly if the prior ‘make install’ required 90 root privileges, verifies that the installation completed 91 correctly. 92 93 8. You can remove the program binaries and object files from the 94 source code directory by typing ‘make clean’. To also remove the 95 files that ‘configure’ created (so you can compile the package for 96 a different kind of computer), type ‘make distclean’. There is 97 also a ‘make maintainer-clean’ target, but that is intended mainly 98 for the package’s developers. If you use it, you may have to 99 bootstrap again. 100 101 9. If the package follows the GNU Coding Standards, you can type ‘make 102 uninstall’ to remove the installed files. 103 104 Compilers and Options 105 ===================== 106 107 Some systems require unusual options for compilation or linking that 108 the ‘configure’ script does not know about. Run ‘./configure --help’ 109 for details on some of the pertinent environment variables. 110 111 You can give ‘configure’ initial values for configuration parameters 112 by setting variables in the command line or in the environment. Here is 113 an example: 114 115 ./configure CC=gcc CFLAGS=-g LIBS=-lposix 116 117 See “Defining Variables” for more details. 118 119 Compiling For Multiple Architectures 120 ==================================== 121 122 You can compile the package for more than one kind of computer at the 123 same time, by placing the object files for each system in their own 124 directory. To do this, you can use GNU ‘make’. ‘cd’ to the directory 125 where you want the object files and executables to go and run the 126 ‘configure’ script. ‘configure’ automatically checks for the source 127 code in the directory that ‘configure’ is in and in ‘..’. This is known 128 as a “VPATH” build. 129 130 With a non-GNU ‘make’, it is safer to compile the package for one 131 system at a time in the source code directory. After you have installed 132 the package for one system, use ‘make distclean’ before reconfiguring 133 for another system. 134 135 Some platforms, notably macOS, support “fat” or “universal” binaries, 136 where a single binary can execute on different architectures. On these 137 platforms you can configure and compile just once, with options specific 138 to that platform. 139 140 Installation Names 141 ================== 142 143 By default, ‘make install’ installs the package’s commands under 144 ‘/usr/local/bin’, include files under ‘/usr/local/include’, etc. You 145 can specify an installation prefix other than ‘/usr/local’ by giving 146 ‘configure’ the option ‘--prefix=PREFIX’, where PREFIX must be an 147 absolute file name. 148 149 You can specify separate installation prefixes for 150 architecture-specific files and architecture-independent files. If you 151 pass the option ‘--exec-prefix=PREFIX’ to ‘configure’, the package uses 152 PREFIX as the prefix for installing programs and libraries. 153 Documentation and other data files still use the regular prefix. 154 155 In addition, if you use an unusual directory layout you can give 156 options like ‘--bindir=DIR’ to specify different values for particular 157 kinds of files. Run ‘configure --help’ for a list of the directories 158 you can set and what kinds of files go in them. In general, the default 159 for these options is expressed in terms of ‘${prefix}’, so that 160 specifying just ‘--prefix’ will affect all of the other directory 161 specifications that were not explicitly provided. 162 163 The most portable way to affect installation locations is to pass the 164 correct locations to ‘configure’; however, many packages provide one or 165 both of the following shortcuts of passing variable assignments to the 166 ‘make install’ command line to change installation locations without 167 having to reconfigure or recompile. 168 169 The first method involves providing an override variable for each 170 affected directory. For example, ‘make install 171 prefix=/alternate/directory’ will choose an alternate location for all 172 directory configuration variables that were expressed in terms of 173 ‘${prefix}’. Any directories that were specified during ‘configure’, 174 but not in terms of ‘${prefix}’, must each be overridden at install time 175 for the entire installation to be relocated. The approach of makefile 176 variable overrides for each directory variable is required by the GNU 177 Coding Standards, and ideally causes no recompilation. However, some 178 platforms have known limitations with the semantics of shared libraries 179 that end up requiring recompilation when using this method, particularly 180 noticeable in packages that use GNU Libtool. 181 182 The second method involves providing the ‘DESTDIR’ variable. For 183 example, ‘make install DESTDIR=/alternate/directory’ will prepend 184 ‘/alternate/directory’ before all installation names. The approach of 185 ‘DESTDIR’ overrides is not required by the GNU Coding Standards, and 186 does not work on platforms that have drive letters. On the other hand, 187 it does better at avoiding recompilation issues, and works well even 188 when some directory options were not specified in terms of ‘${prefix}’ 189 at ‘configure’ time. 190 191 Optional Features 192 ================= 193 194 If the package supports it, you can cause programs to be installed 195 with an extra prefix or suffix on their names by giving ‘configure’ the 196 option ‘--program-prefix=PREFIX’ or ‘--program-suffix=SUFFIX’. 197 198 Some packages pay attention to ‘--enable-FEATURE’ and 199 ‘--disable-FEATURE’ options to ‘configure’, where FEATURE indicates an 200 optional part of the package. They may also pay attention to 201 ‘--with-PACKAGE’ and ‘--without-PACKAGE’ options, where PACKAGE is 202 something like ‘gnu-ld’. ‘./configure --help’ should mention the 203 ‘--enable-...’ and ‘--with-...’ options that the package recognizes. 204 205 Some packages offer the ability to configure how verbose the 206 execution of ‘make’ will be. For these packages, running ‘./configure 207 --enable-silent-rules’ sets the default to minimal output, which can be 208 overridden with ‘make V=1’; while running ‘./configure 209 --disable-silent-rules’ sets the default to verbose, which can be 210 overridden with ‘make V=0’. 211 212 Specifying a System Type 213 ======================== 214 215 By default ‘configure’ builds for the current system. To create 216 binaries that can run on a different system type, specify a 217 ‘--host=TYPE’ option along with compiler variables that specify how to 218 generate object code for TYPE. For example, to create binaries intended 219 to run on a 64-bit ARM processor: 220 221 ./configure --host=aarch64-linux-gnu \ 222 CC=aarch64-linux-gnu-gcc \ 223 CXX=aarch64-linux-gnu-g++ 224 225 If done on a machine that can execute these binaries (e.g., via 226 ‘qemu-aarch64’, ‘$QEMU_LD_PREFIX’, and Linux’s ‘binfmt_misc’ 227 capability), the build behaves like a native build. Otherwise it is a 228 cross-build: ‘configure’ will make cross-compilation guesses instead of 229 running test programs, and ‘make check’ will not work. 230 231 A system type can either be a short name like ‘mingw64’, or a 232 canonical name like ‘x86_64-pc-linux-gnu’. Canonical names have the 233 form CPU-COMPANY-SYSTEM where SYSTEM is either OS or KERNEL-OS. To 234 canonicalize and validate a system type, you can run the command 235 ‘config.sub’, which is often squirreled away in a subdirectory like 236 ‘build-aux’. For example: 237 238 $ build-aux/config.sub arm64-linux 239 aarch64-unknown-linux-gnu 240 $ build-aux/config.sub riscv-lnx 241 Invalid configuration 'riscv-lnx': OS 'lnx' not recognized 242 243 You can look at the ‘config.sub’ file to see which types are recognized. 244 If the file is absent, this package does not need the system type. 245 246 If ‘configure’ fails with the diagnostic “cannot guess build type”. 247 ‘config.sub’ did not recognize your system’s type. In this case, first 248 fetch the newest versions of these files from the GNU config package 249 (https://savannah.gnu.org/projects/config). If that fixes things, 250 please report it to the maintainers of the package containing 251 ‘configure’. Otherwise, you can try the configure option ‘--build=TYPE’ 252 where TYPE comes close to your system type; also, please report the 253 problem to <config-patches@gnu.org>. 254 255 For more details about configuring system types, see the Autoconf 256 documentation. 257 258 Sharing Defaults 259 ================ 260 261 If you want to set default values for ‘configure’ scripts to share, 262 you can create a site shell script called ‘config.site’ that gives 263 default values for variables like ‘CC’, ‘cache_file’, and ‘prefix’. 264 ‘configure’ looks for ‘PREFIX/share/config.site’ if it exists, then 265 ‘PREFIX/etc/config.site’ if it exists. Or, you can set the 266 ‘CONFIG_SITE’ environment variable to the location of the site script. 267 A warning: not all ‘configure’ scripts look for a site script. 268 269 Defining Variables 270 ================== 271 272 Variables not defined in a site shell script can be set in the 273 environment passed to ‘configure’. However, some packages may run 274 configure again during the build, and the customized values of these 275 variables may be lost. In order to avoid this problem, you should set 276 them in the ‘configure’ command line, using ‘VAR=value’. For example: 277 278 ./configure CC=/usr/local2/bin/gcc 279 280 causes the specified ‘gcc’ to be used as the C compiler (unless it is 281 overridden in the site shell script). 282 283 Unfortunately, this technique does not work for ‘CONFIG_SHELL’ due to an 284 Autoconf limitation. Until the limitation is lifted, you can use this 285 workaround: 286 287 CONFIG_SHELL=/bin/bash ./configure CONFIG_SHELL=/bin/bash 288 289 ‘configure’ Invocation 290 ====================== 291 292 ‘configure’ recognizes the following options to control how it 293 operates. 294 295 ‘--help’ 296 ‘-h’ 297 Print a summary of all of the options to ‘configure’, and exit. 298 299 ‘--help=short’ 300 ‘--help=recursive’ 301 Print a summary of the options unique to this package’s 302 ‘configure’, and exit. The ‘short’ variant lists options used only 303 in the top level, while the ‘recursive’ variant lists options also 304 present in any nested packages. 305 306 ‘--version’ 307 ‘-V’ 308 Print the version of Autoconf used to generate the ‘configure’ 309 script, and exit. 310 311 ‘--cache-file=FILE’ 312 Enable the cache: use and save the results of the tests in FILE, 313 traditionally ‘config.cache’. FILE defaults to ‘/dev/null’ to 314 disable caching. 315 316 ‘--config-cache’ 317 ‘-C’ 318 Alias for ‘--cache-file=config.cache’. 319 320 ‘--srcdir=DIR’ 321 Look for the package’s source code in directory DIR. Usually 322 ‘configure’ can determine that directory automatically. 323 324 ‘--prefix=DIR’ 325 Use DIR as the installation prefix. See “Installation Names” for 326 more details, including other options available for fine-tuning the 327 installation locations. 328 329 ‘--host=TYPE’ 330 Build binaries for system TYPE. See “Specifying a System Type”. 331 332 ‘--enable-FEATURE’ 333 ‘--disable-FEATURE’ 334 Enable or disable the optional FEATURE. See “Optional Features”. 335 336 ‘--with-PACKAGE’ 337 ‘--without-PACKAGE’ 338 Use or omit PACKAGE when building. See “Optional Features”. 339 340 ‘--quiet’ 341 ‘--silent’ 342 ‘-q’ 343 Do not print messages saying which checks are being made. To 344 suppress all normal output, redirect it to ‘/dev/null’ (any error 345 messages will still be shown). 346 347 ‘--no-create’ 348 ‘-n’ 349 Run the configure checks, but stop before creating any output 350 files. 351 352 ‘configure’ also recognizes several environment variables, and accepts 353 some other, less widely useful, options. Run ‘configure --help’ for 354 more details. 355 356 Copyright notice 357 ================ 358 359 Copyright © 1994–1996, 1999–2002, 2004–2017, 2020–2024 Free Software 360 Foundation, Inc. 361 362 Copying and distribution of this file, with or without modification, 363 are permitted in any medium without royalty provided the copyright 364 notice and this notice are preserved. This file is offered as-is, 365 without warranty of any kind.