libc/docs/dev/config_options.rst

.. _configure_options:

=================================
Adding new libc configure options
=================================

`There are a number of configure options <../configure.html>`_ which can be used
to configure the libc build. The config system is driven by a set of
hierarchical JSON files. At the top of the hierarchy is a JSON file by name
``config.json`` in the ``config`` directory. This JSON file lists the libc
options which affect all platforms. The default value for the option and a short
description about it listed against each option. For example:

.. code-block:: json

   {
     "printf": {
       "LIBC_CONF_PRINTF_DISABLE_FLOAT": {
         "value": false,
         "doc": "Disable printing floating point values in printf and friends."
       }
     }
   }

The above config indicates that the option ``LIBC_CONF_PRINTF_DISABLE_FLOAT``
has a value of ``false``. A platform, say the baremetal platform, can choose
to override this value in its ``config.json`` file in the ``config/baremetal``
directory with the following contents:

.. code-block:: json

   {
     "printf": {
       "LIBC_CONF_PRINTF_DISABLE_FLOAT": {
         "value": true
       }
     }
   }

Here, the config for the baremetal platform overrides the common ``false``
value of the ``LIBC_CONF_PRINTF_DISABLE_FLOAT`` with the ``true`` value.

Config JSON format
==================

Named tags
----------

As can be noted from the above examples, ``config.json`` files contains a
top-level dictionary. The keys of this dictionary are the names of
*grouping-tags*. A grouping-tag is nothing but a named tag to refer to a related
group of libc options. In the above example, a tag named ``printf`` is used to
group all libc options which affect the behavior of ``printf`` and friends.

Tag values
----------

The value corresponding to each grouping tag is also a dictionary called the
*option-dictionary*. The keys of the option-dictionary are the names of the libc
options belonging to that grouping tag. For the ``printf`` tag in the above
example, the option-dictionary is:

.. code-block:: json

   {
     "LIBC_CONF_PRINTF_DISABLE_FLOAT": {
       "value": false,
       "doc":
     }
   }

The value corresponding to an option key in the option-dictionary is another
dictionary with two keys: ``"value"`` and ``"doc"``. The ``"value"`` key has
the value of the option listed against it, and the ``"doc"`` key has a short
description of the option listed against it. Note that only the main config
file ``config/config.json`` includes the ``"doc"`` key. Options which are of
``ON``/``OFF`` kind take boolean values ``true``/``false``. Other types of
options can take an integral or string value as suitable for that option. In
the above option-dictionary, the option-key ``LIBC_CONF_PRINTF_DISABLE_FLOAT``
is of boolean type with value ``true``.

Option name format
------------------

The option names, or the keys of a option-dictionary, have the following format:

.. code-block:: none

   LIBC_CONF_<UPPER_CASE_TAG_NAME>_<ACTION_INDICATING_THE_INTENDED_SEMANTICS>

The option name used in the above examples, ``LIBC_CONF_PRINTF_DISABLE_FLOAT``
to disable printing of floating point numbers, follows this format: It has the
prefix ``LIBC_CONF_``, followed by the grouping-tag name ``PRINTF`` in upper
case, followed by the action to disable floating point number printing
``LIBC_CONF_PRINTF_DISABLE_FLOAT``.

Mechanics of config application
===============================

Config reading
--------------

At libc config time, three different ``config.json`` files are read in the
following order:

1. ``config/config.json``
2. ``config/<platform or OS>/config.json`` if present.
3. ``config/<platform or OS>/<target arch>/config.json`` if present.

Each successive ``config.json`` file overrides the option values set by
previously read ``config.json`` files. Likewise, a similarly named command line
option to the cmake command will override the option values specified in all or
any of these ``config.json`` files. That is, users will be able to override the
config options from the command line.

Config application
------------------

Local to the directory where an option group is relevant, suitable build logic
should convert the CMake config options to appropriate compiler and/or linker
flags. Those compile/link flags can be used in listing the affected targets as
follows:

.. code-block:: cmake

   add_object_library(
    ...
    COMPILE_OPTIONS
      ${common_printf_compile_options}
      ... # Other compile options affecting this target irrespective of the
          # libc config options
   )

Note that the above scheme is only an example and not a prescription.
Developers should employ a scheme appropriate to the option being added.

Automatic doc update
====================

The CMake configure step automatically generates the user document
``doc/configure.rst``, which contains user information about the libc configure
options, using the information in the main ``config/config.json`` file.
An update to ``config/config.json`` will trigger reconfiguration by CMake, which
in turn will regenerate the documentation in ``doc/configure.rst``.