Debian Codegraph @

INSTALL

raw
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 <[email protected]>.
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.