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