INSTALL.md (16940B)
1 Building Taler 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 to set the environment variables 11 - `TALER_EXCHANGE_PREFIX` 12 - `TALER_MERCHANT_PREFIX` 13 - `TALER_BANK_PREFIX` 14 - `TALER_AUDITOR_PREFIX` 15 to the directory where Taler's libraries are installed. 16 17 **NOTE:** Before running any testcases, you must complete the 18 installation. 19 20 Quick summary: 21 22 ``` 23 $ ./bootstrap # needed after each git pull 24 $ ./configure --prefix=$SOMEWHERE 25 $ make 26 $ make install 27 $ export TALER_EXCHANGE_PREFIX=$SOMEWHERE 28 $ export TALER_MERCHANT_PREFIX=$SOMEWHERE 29 $ export TALER_BANK_PREFIX=$SOMEWHERE 30 $ export TALER_AUDITOR_PREFIX=$SOMEWHERE 31 $ make check 32 ``` 33 34 The build system is meson; `./configure` and `make` are a thin wrapper 35 around it. See [README.meson.md](README.meson.md) for using meson 36 directly, the test suites and setups, and the nix development shell. 37 38 General Installation Instructions (autoconf) 39 -------------------------------------------- 40 41 *Copyright (C) 1994-1996, 1999-2002, 2004-2017, 2020-2021 Free 42 Software Foundation, Inc.* 43 44 Copying and distribution of this file, with or without modification, 45 are permitted in any medium without royalty provided the copyright 46 notice and this notice are preserved. This file is offered as-is, 47 without warranty of any kind. 48 49 ### Basic Installation 50 51 Briefly, the shell command `./configure && make && make install` 52 should configure, build, and install this package. The following 53 more-detailed instructions are generic; see the `README.md` file for 54 instructions specific to this package. Some packages provide this 55 `INSTALL.md` file but do not implement all of the features documented 56 below. The lack of an optional feature in a given package is not 57 necessarily a bug. More recommendations for GNU packages can be found 58 in [Makefile Conventions](https://www.gnu.org/prep/standards/html_node/Makefile-Conventions.html). 59 60 The `configure` shell script attempts to guess correct values for 61 various system-dependent variables used during compilation. It uses 62 those values to create a `Makefile` in each directory of the package. 63 It may also create one or more `.h` files containing system-dependent 64 definitions. Finally, it creates a shell script `config.status` that 65 you can run in the future to recreate the current configuration, and a 66 file `config.log` containing compiler output (useful mainly for 67 debugging `configure`). 68 69 It can also use an optional file (typically called `config.cache` and 70 enabled with `--cache-file=config.cache` or simply `-C`) that saves the 71 results of its tests to speed up reconfiguring. Caching is disabled by 72 default to prevent problems with accidental use of stale cache files. 73 74 If you need to do unusual things to compile the package, please try 75 to figure out how `configure` could check whether to do them, and mail 76 diffs or instructions to the address given in the `README` so they can 77 be considered for the next release. If you are using the cache, and at 78 some point `config.cache` contains results you don't want to keep, you 79 may remove or edit it. 80 81 The file `configure.ac` (or `configure.in`) is used to create 82 `configure` by a program called `autoconf`. You need `configure.ac` if 83 you want to change it or regenerate `configure` using a newer version of 84 `autoconf`. 85 86 The simplest way to compile this package is: 87 88 1. `cd` to the directory containing the package's source code and type 89 `./configure` to configure the package for your system. 90 91 Running `configure` might take a while. While running, it prints 92 some messages telling which features it is checking for. 93 94 2. Type `make` to compile the package. 95 96 3. Optionally, type `make check` to run any self-tests that come with 97 the package, generally using the just-built uninstalled binaries. 98 99 4. Type `make install` to install the programs and any data files and 100 documentation. When installing into a prefix owned by root, it is 101 recommended that the package be configured and built as a regular 102 user, and only the `make install` phase executed with root 103 privileges. 104 105 5. Optionally, type `make installcheck` to repeat any self-tests, but 106 this time using the binaries in their final installed location. 107 This target does not install anything. Running this target as a 108 regular user, particularly if the prior `make install` required 109 root privileges, verifies that the installation completed 110 correctly. 111 112 6. You can remove the program binaries and object files from the 113 source code directory by typing `make clean`. To also remove the 114 files that `configure` created (so you can compile the package for 115 a different kind of computer), type `make distclean`. There is 116 also a `make maintainer-clean` target, but that is intended mainly 117 for the package's developers. If you use it, you may have to get 118 all sorts of other programs in order to regenerate files that came 119 with the distribution. 120 121 7. Often, you can also type `make uninstall` to remove the installed 122 files again. In practice, not all packages have tested that 123 uninstallation works correctly, even though it is required by the 124 GNU Coding Standards. 125 126 8. Some packages, particularly those that use Automake, provide 127 `make distcheck`, which can by used by developers to test that all 128 other targets like `make install` and `make uninstall` work 129 correctly. This target is generally not run by end users. 130 131 132 ### Compilers and Options 133 134 Some systems require unusual options for compilation or linking that 135 the `configure` script does not know about. Run `./configure --help` 136 for details on some of the pertinent environment variables. 137 138 You can give `configure` initial values for configuration parameters 139 by setting variables in the command line or in the environment. 140 Here is an example: `./configure CC=c99 CFLAGS=-g LIBS=-lposix` 141 142 For more details, see 143 [Defining Variables](https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.72/autoconf.html#Defining-Variables). 144 145 146 ### Compiling For Multiple Architectures 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 architecture in their 150 own directory. To do this, you can use GNU `make`. `cd` to the 151 directory where you want the object files and executables to go and run 152 the `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 architecture at a time in the source code directory. After you have 158 installed the package for one architecture, use `make distclean` before 159 reconfiguring for another architecture. 160 161 On MacOS X 10.5 and later systems, you can create libraries and 162 executables that work on multiple system types--known as "fat" or 163 "universal" binaries--by specifying multiple `-arch` options to the 164 compiler but only a single `-arch` option to the preprocessor. Like 165 this: 166 167 ``` 168 ./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \ 169 CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \ 170 CPP="gcc -E" CXXCPP="g++ -E" 171 ``` 172 173 This is not guaranteed to produce working output in all cases, you 174 may have to build one architecture at a time and combine the results 175 using the `lipo` tool if you have problems. 176 177 178 ### Installation Names 179 180 By default, `make install` installs the package's commands under 181 `/usr/local/bin`, include files under `/usr/local/include`, etc. You 182 can specify an installation prefix other than `/usr/local` by giving 183 `configure` the option `--prefix=PREFIX`, where PREFIX must be an 184 absolute file name. 185 186 You can specify separate installation prefixes for 187 architecture-specific files and architecture-independent files. If you 188 pass the option `--exec-prefix=PREFIX` to `configure`, the package uses 189 PREFIX as the prefix for installing programs and libraries. 190 Documentation and other data files still use the regular prefix. 191 192 In addition, if you use an unusual directory layout you can give 193 options like `--bindir=DIR` to specify different values for particular 194 kinds of files. Run `configure --help` for a list of the directories 195 you can set and what kinds of files go in them. In general, the default 196 for these options is expressed in terms of `${prefix}`, so that 197 specifying just `--prefix` will affect all of the other directory 198 specifications that were not explicitly provided. 199 200 The most portable way to affect installation locations is to pass the 201 correct locations to `configure`; however, many packages provide one or 202 both of the following shortcuts of passing variable assignments to the 203 `make install` command line to change installation locations without 204 having to reconfigure or recompile. 205 206 The first method involves providing an override variable for each 207 affected directory. For example, 208 `make install prefix=/alternate/directory` 209 will choose an alternate location for all directory configuration 210 variables that were expressed in terms of `${prefix}`. Any directories 211 that were specified during `configure`, but not in terms of `${prefix}`, 212 must each be overridden at install time for the entire installation to 213 be relocated. The approach of makefile variable overrides for each 214 directory variable is required by the GNU Coding Standards, and ideally 215 causes no recompilation. However, some platforms have known limitations 216 with the semantics of shared libraries that end up requiring 217 recompilation when using this method, particularly noticeable in 218 packages that use GNU Libtool. 219 220 The second method involves providing the `DESTDIR` variable. For 221 example, `make install DESTDIR=/alternate/directory` will prepend 222 `/alternate/directory` before all installation names. The approach of 223 `DESTDIR` overrides is not required by the GNU Coding Standards, and 224 does not work on platforms that have drive letters. On the other hand, 225 it does better at avoiding recompilation issues, and works well even 226 when some directory options were not specified in terms of `${prefix}` 227 at `configure` time. 228 229 230 ### Optional Features 231 232 If the package supports it, you can cause programs to be installed 233 with an extra prefix or suffix on their names by giving `configure` the 234 option `--program-prefix=PREFIX` or `--program-suffix=SUFFIX`. 235 236 Some packages pay attention to `--enable-FEATURE` options to 237 `configure`, where FEATURE indicates an optional part of the package. 238 They may also pay attention to `--with-PACKAGE` options, where PACKAGE 239 is something like `gnu-as` or `x` (for the X Window System). The 240 `README` should mention any `--enable-` and `--with-` options that the 241 package recognizes. 242 243 For packages that use the X Window System, `configure` can usually 244 find the X include and library files automatically, but if it doesn't, 245 you can use the `configure` options `--x-includes=DIR` and 246 `--x-libraries=DIR` to specify their locations. 247 248 Some packages offer the ability to configure how verbose the 249 execution of `make` will be. For these packages, running 250 `./configure --enable-silent-rules` 251 sets the default to minimal output, which can be 252 overridden with `make V=1`; while running 253 `./configure --disable-silent-rules` 254 sets the default to verbose, which can be overridden with `make V=0`. 255 256 257 258 ### Particular systems 259 260 On HP-UX, the default C compiler is not ANSI C compatible. If GNU CC 261 is not installed, it is recommended to use the following options in 262 order to use an ANSI C compiler: 263 264 ``` 265 ./configure CC="cc -Ae -D_XOPEN_SOURCE=500" 266 ``` 267 268 and if that doesn't work, install pre-built binaries of GCC for HP-UX. 269 270 HP-UX `make` updates targets which have the same timestamps as their 271 prerequisites, which makes it generally unusable when shipped generated 272 files such as `configure` are involved. Use GNU `make` instead. 273 274 On OSF/1 a.k.a. Tru64, some versions of the default C compiler cannot 275 parse its `<wchar.h>` header file. The option `-nodtk` can be used as a 276 workaround. If GNU CC is not installed, it is therefore recommended to 277 try 278 279 ``` 280 ./configure CC="cc" 281 ``` 282 283 and if that doesn't work, try 284 285 ``` 286 ./configure CC="cc -nodtk" 287 ``` 288 289 On Solaris, don't put `/usr/ucb` early in your `PATH`. This 290 directory contains several dysfunctional programs; working variants of 291 these programs are available in `/usr/bin`. So, if you need `/usr/ucb` 292 in your `PATH`, put it _after_ `/usr/bin`. 293 294 On Haiku, software installed for all users goes in `/boot/common`, 295 not `/usr/local`. It is recommended to use the following options: 296 297 ``` 298 ./configure --prefix=/boot/common 299 ``` 300 301 302 ### Specifying the System Type 303 304 There may be some features `configure` cannot figure out 305 automatically, but needs to determine by the type of machine the package 306 will run on. Usually, assuming the package is built to be run on the 307 _same_ architectures, `configure` can figure that out, but if it prints 308 a message saying it cannot guess the machine type, give it the 309 `--build=TYPE` option. TYPE can either be a short name for the system 310 type, such as `sun4`, or a canonical name which has the form: 311 312 ``` 313 CPU-COMPANY-SYSTEM 314 ``` 315 316 where SYSTEM can have one of these forms: 317 318 ``` 319 OS 320 KERNEL-OS 321 ``` 322 323 See the file `config.sub` for the possible values of each field. If 324 `config.sub` isn't included in this package, then this package doesn't 325 need to know the machine type. 326 327 If you are _building_ compiler tools for cross-compiling, you should 328 use the option `--target=TYPE` to select the type of system they will 329 produce code for. 330 331 If you want to _use_ a cross compiler, that generates code for a 332 platform different from the build platform, you should specify the 333 "host" platform (i.e., that on which the generated programs will 334 eventually be run) with `--host=TYPE`. 335 336 Sharing Defaults 337 ================ 338 339 If you want to set default values for `configure` scripts to share, 340 you can create a site shell script called `config.site` that gives 341 default values for variables like `CC`, `cache_file`, and `prefix`. 342 `configure` looks for `PREFIX/share/config.site` if it exists, then 343 `PREFIX/etc/config.site` if it exists. Or, you can set the 344 `CONFIG_SITE` environment variable to the location of the site script. 345 A warning: not all `configure` scripts look for a site script. 346 347 Defining Variables 348 ================== 349 350 Variables not defined in a site shell script can be set in the 351 environment passed to `configure`. However, some packages may run 352 configure again during the build, and the customized values of these 353 variables may be lost. In order to avoid this problem, you should set 354 them in the `configure` command line, using `VAR=value`. For example: 355 356 ``` 357 ./configure CC=/usr/local2/bin/gcc 358 ``` 359 360 causes the specified `gcc` to be used as the C compiler (unless it is 361 overridden in the site shell script). 362 363 Unfortunately, this technique does not work for `CONFIG_SHELL` due to an 364 Autoconf limitation. Until the limitation is lifted, you can use this 365 workaround: 366 367 ``` 368 CONFIG_SHELL=/bin/bash ./configure CONFIG_SHELL=/bin/bash 369 ``` 370 371 372 ### `configure` Invocation 373 374 `configure` recognizes the following options to control how it operates. 375 376 ``` 377 --help 378 -h 379 Print a summary of all of the options to configure, and exit. 380 381 --help=short 382 --help=recursive 383 Print a summary of the options unique to this packages 384 configure, and exit. The short variant lists options used only 385 in the top level, while the recursive variant lists options also 386 present in any nested packages. 387 388 --version 389 -V 390 Print the version of Autoconf used to generate the configure 391 script, and exit. 392 393 --cache-file=FILE 394 Enable the cache: use and save the results of the tests in FILE, 395 traditionally config.cache. FILE defaults to /dev/null to 396 disable caching. 397 398 --config-cache 399 -C 400 Alias for --cache-file=config.cache. 401 402 --quiet 403 --silent 404 -q 405 Do not print messages saying which checks are being made. To 406 suppress all normal output, redirect it to /dev/null (any error 407 messages will still be shown). 408 409 --srcdir=DIR 410 Look for the packages source code in directory DIR. Usually 411 configure can determine that directory automatically. 412 413 --prefix=DIR 414 Use DIR as the installation prefix. *note Installation Names:: for 415 more details, including other options available for fine-tuning the 416 installation locations. 417 418 --no-create 419 -n 420 Run the configure checks, but stop before creating any output 421 files. 422 ``` 423 424 `configure` also accepts some other, not widely useful, options. Run 425 `configure --help` for more details. 426