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