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