libc/docs/dev/config_options.rst

   1 .. _configure_options:
   2
   3 =================================
   4 Adding new libc configure options
   5 =================================
   6
   7 `There are a number of configure options <../configure.html>`_ which can be used
   8 to configure the libc build. The config system is driven by a set of
   9 hierarchical JSON files. At the top of the hierarchy is a JSON file by name
  10 ``config.json`` in the ``config`` directory. This JSON file lists the libc
  11 options which affect all platforms. The default value for the option and a short
  12 description about it listed against each option. For example:
  13
  14 .. code-block::
  15
  16    {
  17      "printf": {
  18        "LIBC_CONF_PRINTF_DISABLE_FLOAT": {
  19          "value": false,
  20          "doc": "Disable printing floating point values in printf and friends."
  21        },
  22        ...
  23      }
  24    }
  25
  26 The above config indicates that the option ``LIBC_CONF_PRINTF_DISABLE_FLOAT``
  27 has a value of ``false``. A platform, say the baremetal platform, can choose
  28 to override this value in its ``config.json`` file in the ``config/baremetal``
  29 directory with the following contents:
  30
  31 .. code-block::
  32
  33    {
  34      "printf": {
  35        "LIBC_CONF_PRINTF_DISABLE_FLOAT": {
  36          "value": true
  37        }
  38      }
  39    }
  40
  41 Here, the config for the baremetal platform overrides the common ``false``
  42 value of the ``LIBC_CONF_PRINTF_DISABLE_FLOAT`` with the ``true`` value.
  43
  44 Config JSON format
  45 ==================
  46
  47 Named tags
  48 ----------
  49
  50 As can be noted from the above examples, ``config.json`` files contains a
  51 top-level dictionary. The keys of this dictionary are the names of
  52 *grouping-tags*. A grouping-tag is nothing but a named tag to refer to a related
  53 group of libc options. In the above example, a tag named ``printf`` is used to
  54 group all libc options which affect the behavior of ``printf`` and friends.
  55
  56 Tag values
  57 ----------
  58
  59 The value corresponding to each grouping tag is also a dictionary called the
  60 *option-dictionary*. The keys of the option-dictionary are the names of the libc
  61 options belonging to that grouping tag. For the ``printf`` tag in the above
  62 example, the option-dictionary is:
  63
  64 .. code-block::
  65
  66    {
  67      "LIBC_CONF_PRINTF_DISABLE_FLOAT": {
  68        "value": false,
  69        "doc":
  70      },
  71      ...
  72    }
  73
  74 The value corresponding to an option key in the option-dictionary is another
  75 dictionary with two keys: ``"value"`` and ``"doc"``. The ``"value"`` key has
  76 the value of the option listed against it, and the ``"doc"`` key has a short
  77 description of the option listed against it. Note that only the main config
  78 file ``config/config.json`` includes the ``"doc"`` key. Options which are of
  79 ``ON``/``OFF`` kind take boolean values ``true``/``false``. Other types of
  80 options can take an integral or string value as suitable for that option. In
  81 the above option-dictionary, the option-key ``LIBC_CONF_PRINTF_DISABLE_FLOAT``
  82 is of boolean type with value ``true``.
  83
  84 Option name format
  85 ------------------
  86
  87 The option names, or the keys of a option-dictionary, have the following format:
  88
  89 .. code-block::
  90
  91    LIBC_CONF_<UPPER_CASE_TAG_NAME>_<ACTION_INDICATING_THE_INTENDED_SEMANTICS>
  92
  93 The option name used in the above examples, ``LIBC_CONF_PRINTF_DISABLE_FLOAT``
  94 to disable printing of floating point numbers, follows this format: It has the
  95 prefix ``LIBC_CONF_``, followed by the grouping-tag name ``PRINTF`` in upper
  96 case, followed by the action to disable floating point number printing
  97 ``LIBC_CONF_PRINTF_DISABLE_FLOAT``.
  98
  99 Mechanics of config application
 100 ===============================
 101
 102 Config reading
 103 --------------
 104
 105 At libc config time, three different ``config.json`` files are read in the
 106 following order:
 107
 108 1. ``config/config.json``
 109 2. ``config/<platform or OS>/config.json`` if present.
 110 3. ``config/<platform or OS>/<target arch>/config.json`` if present.
 111
 112 Each successive ``config.json`` file overrides the option values set by
 113 previously read ``config.json`` files. Likewise, a similarly named command line
 114 option to the cmake command will override the option values specified in all or
 115 any of these ``config.json`` files. That is, users will be able to override the
 116 config options from the command line.
 117
 118 Config application
 119 ------------------
 120
 121 Local to the directory where an option group is relevant, suitable build logic
 122 should convert the CMake config options to appropriate compiler and/or linker
 123 flags. Those compile/link flags can be used in listing the affected targets as
 124 follows:
 125
 126 .. code-block::
 127
 128    add_object_library(
 129     ...
 130     COMPILE_OPTIONS
 131       ${common_printf_compile_options}
 132       ... # Other compile options affecting this target irrespective of the
 133           # libc config options
 134    )
 135
 136 Note that the above scheme is only an example and not a prescription.
 137 Developers should employ a scheme appropriate to the option being added.
 138
 139 Automatic doc update
 140 ====================
 141
 142 The CMake configure step automatically generates the user document
 143 ``doc/configure.rst``, which contains user information about the libc configure
 144 options, using the information in the main ``config/config.json`` file.
 145 An update to ``config/config.json`` will trigger reconfiguration by CMake, which
 146 in turn will regenerate the documentation in ``doc/configure.rst``.