common-conf-syntax.rst (3503B)
1 The configuration file is line-oriented. Blank lines and whitespace at the 2 beginning and end of a line are ignored. Comments start with ``#`` or ``%`` 3 in the first column (after any beginning-of-line whitespace) and go to the end 4 of the line. 5 6 The file is split into sections. Every section begins with ``[SECTIONNAME]`` 7 and contains a number of options of the form ``OPTION=VALUE``. There may be 8 whitespace around the ``=`` (equal sign). Section names and options are 9 *case-insensitive*. 10 11 The values, however, are *case-sensitive*. In particular, boolean values are 12 one of ``YES`` or ``NO``. Values can include whitespace by surrounding the 13 entire value with ``"`` (double quote). Note, however, that there are no 14 escape characters in such strings; all characters between the double quotes 15 (including other double quotes) are taken verbatim. 16 17 Values that represent a time duration are represented as a series 18 of one or more ``NUMBER UNIT`` pairs, e.g. ``60 s``, ``4 weeks 1 day``, 19 ``5 years 2 minutes``. 20 21 Values that represent an amount are in the usual amount syntax: 22 ``CURRENCY:VALUE.FRACTION``, e.g. ``EUR:1.50``. 23 The ``FRACTION`` portion may extend up to 8 places. 24 25 Values that represent filenames can begin with a ``/bin/sh``-like variable 26 reference. This can be simple, such as ``$TMPDIR/foo``, or complex, such as 27 ``${TMPDIR:-${TMP:-/tmp}}/foo``. The variables are expanded either using 28 key-values from the ``[PATHS]`` section (see below) or from the environment 29 (``getenv()``). The values from ``[PATHS]`` take precedence over those from 30 the environment. If the variable name is found in neither ``[PATHS]`` nor the 31 environment, a warning is printed and the value is left unchanged. Variables (including those from the environment) are expanded recursively, so if ``FOO=$BAR`` and ``BAR=buzz`` then the result is ``FOO=buzz``. Recursion is bounded to at most 128 levels to avoid undefined behavior for mutually recursive expansions like if ``BAR=$FOO`` in the example above. 32 33 The ``[PATHS]`` section is special in that it contains paths that can be 34 referenced using ``$`` in other configuration values that specify 35 *filenames*. Note that configuration options that are not specifically 36 retrieved by the application as *filenames* will not see “$”-expressions 37 expanded. To expand ``$``-expressions when using ``taler-config``, you must pass 38 the ``-f`` command-line option. 39 40 The system automatically pre-populates the ``[PATHS]`` section with a few values 41 at run-time (in addition to the values that are in the actual configuration 42 file and automatically overwriting those values if they are present). 43 These automatically generated values refer to installation properties 44 from `GNU autoconf 45 <https://www.gnu.org/prep/standards/html_node/Directory-Variables.html>`_. The 46 values are usually dependent on an ``INSTALL_PREFIX`` which is determined by 47 the ``--prefix`` option given to configure. The canonical values are: 48 49 * LIBEXECDIR = $INSTALL_PREFIX/taler/libexec/ 50 * DOCDIR = $INSTALL_PREFIX/share/doc/taler/ 51 * ICONDIR = $INSTALL_PREFIX/share/icons/ 52 * LOCALEDIR = $INSTALL_PREFIX/share/locale/ 53 * PREFIX = $INSTALL_PREFIX/ 54 * BINDIR = $INSTALL_PREFIX/bin/ 55 * LIBDIR = $INSTALL_PREFIX/lib/taler/ 56 * DATADIR = $INSTALL_PREFIX/share/taler/ 57 58 Note that on some platforms, the given paths may differ depending 59 on how the system was compiled or installed, the above are just the 60 canonical locations of the various resources. These 61 automatically generated values are never written to disk.