145 lines · plain
1.. _configure_options:2 3=================================4Adding new libc configure options5=================================6 7`There are a number of configure options <../configure.html>`_ which can be used8to configure the libc build. The config system is driven by a set of9hierarchical JSON files. At the top of the hierarchy is a JSON file by name10``config.json`` in the ``config`` directory. This JSON file lists the libc11options which affect all platforms. The default value for the option and a short12description about it listed against each option. For example:13 14.. code-block:: json15 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 25The above config indicates that the option ``LIBC_CONF_PRINTF_DISABLE_FLOAT``26has a value of ``false``. A platform, say the baremetal platform, can choose27to override this value in its ``config.json`` file in the ``config/baremetal``28directory with the following contents:29 30.. code-block:: json31 32 {33 "printf": {34 "LIBC_CONF_PRINTF_DISABLE_FLOAT": {35 "value": true36 }37 }38 }39 40Here, the config for the baremetal platform overrides the common ``false``41value of the ``LIBC_CONF_PRINTF_DISABLE_FLOAT`` with the ``true`` value.42 43Config JSON format44==================45 46Named tags47----------48 49As can be noted from the above examples, ``config.json`` files contains a50top-level dictionary. The keys of this dictionary are the names of51*grouping-tags*. A grouping-tag is nothing but a named tag to refer to a related52group of libc options. In the above example, a tag named ``printf`` is used to53group all libc options which affect the behavior of ``printf`` and friends.54 55Tag values56----------57 58The value corresponding to each grouping tag is also a dictionary called the59*option-dictionary*. The keys of the option-dictionary are the names of the libc60options belonging to that grouping tag. For the ``printf`` tag in the above61example, the option-dictionary is:62 63.. code-block:: json64 65 {66 "LIBC_CONF_PRINTF_DISABLE_FLOAT": {67 "value": false,68 "doc":69 }70 }71 72The value corresponding to an option key in the option-dictionary is another73dictionary with two keys: ``"value"`` and ``"doc"``. The ``"value"`` key has74the value of the option listed against it, and the ``"doc"`` key has a short75description of the option listed against it. Note that only the main config76file ``config/config.json`` includes the ``"doc"`` key. Options which are of77``ON``/``OFF`` kind take boolean values ``true``/``false``. Other types of78options can take an integral or string value as suitable for that option. In79the above option-dictionary, the option-key ``LIBC_CONF_PRINTF_DISABLE_FLOAT``80is of boolean type with value ``true``.81 82Option name format83------------------84 85The option names, or the keys of a option-dictionary, have the following format:86 87.. code-block:: none88 89 LIBC_CONF_<UPPER_CASE_TAG_NAME>_<ACTION_INDICATING_THE_INTENDED_SEMANTICS>90 91The option name used in the above examples, ``LIBC_CONF_PRINTF_DISABLE_FLOAT``92to disable printing of floating point numbers, follows this format: It has the93prefix ``LIBC_CONF_``, followed by the grouping-tag name ``PRINTF`` in upper94case, followed by the action to disable floating point number printing95``LIBC_CONF_PRINTF_DISABLE_FLOAT``.96 97Mechanics of config application98===============================99 100Config reading101--------------102 103At libc config time, three different ``config.json`` files are read in the104following order:105 1061. ``config/config.json``1072. ``config/<platform or OS>/config.json`` if present.1083. ``config/<platform or OS>/<target arch>/config.json`` if present.109 110Each successive ``config.json`` file overrides the option values set by111previously read ``config.json`` files. Likewise, a similarly named command line112option to the cmake command will override the option values specified in all or113any of these ``config.json`` files. That is, users will be able to override the114config options from the command line.115 116Config application117------------------118 119Local to the directory where an option group is relevant, suitable build logic120should convert the CMake config options to appropriate compiler and/or linker121flags. Those compile/link flags can be used in listing the affected targets as122follows:123 124.. code-block:: cmake125 126 add_object_library(127 ...128 COMPILE_OPTIONS129 ${common_printf_compile_options}130 ... # Other compile options affecting this target irrespective of the131 # libc config options132 )133 134Note that the above scheme is only an example and not a prescription.135Developers should employ a scheme appropriate to the option being added.136 137Automatic doc update138====================139 140The CMake configure step automatically generates the user document141``doc/configure.rst``, which contains user information about the libc configure142options, using the information in the main ``config/config.json`` file.143An update to ``config/config.json`` will trigger reconfiguration by CMake, which144in turn will regenerate the documentation in ``doc/configure.rst``.145