exchange

Base system with REST service to issue digital coins, run by the payment service provider
Log | Files | Refs | Submodules | README | LICENSE

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