xref: /llvm-project/libc/docs/dev/config_options.rst (revision 2a2e21cd2bc4db9ec579d1c53bd11fc4bb0e7714) 
1.. _configure_options:
2
3=================================
4Adding new libc configure options
5=================================
6
7`There are a number of configure options <../configure.html>`_ which can be used
8to configure the libc build. The config system is driven by a set of
9hierarchical 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
11options which affect all platforms. The default value for the option and a short
12description about it listed against each option. For example:
13
14.. code-block:: json
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
25The above config indicates that the option ``LIBC_CONF_PRINTF_DISABLE_FLOAT``
26has a value of ``false``. A platform, say the baremetal platform, can choose
27to override this value in its ``config.json`` file in the ``config/baremetal``
28directory with the following contents:
29
30.. code-block:: json
31
32   {
33     "printf": {
34       "LIBC_CONF_PRINTF_DISABLE_FLOAT": {
35         "value": true
36       }
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 format
44==================
45
46Named tags
47----------
48
49As can be noted from the above examples, ``config.json`` files contains a
50top-level dictionary. The keys of this dictionary are the names of
51*grouping-tags*. A grouping-tag is nothing but a named tag to refer to a related
52group of libc options. In the above example, a tag named ``printf`` is used to
53group all libc options which affect the behavior of ``printf`` and friends.
54
55Tag values
56----------
57
58The value corresponding to each grouping tag is also a dictionary called the
59*option-dictionary*. The keys of the option-dictionary are the names of the libc
60options belonging to that grouping tag. For the ``printf`` tag in the above
61example, the option-dictionary is:
62
63.. code-block:: json
64
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 another
73dictionary with two keys: ``"value"`` and ``"doc"``. The ``"value"`` key has
74the value of the option listed against it, and the ``"doc"`` key has a short
75description of the option listed against it. Note that only the main config
76file ``config/config.json`` includes the ``"doc"`` key. Options which are of
77``ON``/``OFF`` kind take boolean values ``true``/``false``. Other types of
78options can take an integral or string value as suitable for that option. In
79the above option-dictionary, the option-key ``LIBC_CONF_PRINTF_DISABLE_FLOAT``
80is of boolean type with value ``true``.
81
82Option name format
83------------------
84
85The option names, or the keys of a option-dictionary, have the following format:
86
87.. code-block:: none
88
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 the
93prefix ``LIBC_CONF_``, followed by the grouping-tag name ``PRINTF`` in upper
94case, followed by the action to disable floating point number printing
95``LIBC_CONF_PRINTF_DISABLE_FLOAT``.
96
97Mechanics of config application
98===============================
99
100Config reading
101--------------
102
103At libc config time, three different ``config.json`` files are read in the
104following 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 by
111previously read ``config.json`` files. Likewise, a similarly named command line
112option to the cmake command will override the option values specified in all or
113any of these ``config.json`` files. That is, users will be able to override the
114config options from the command line.
115
116Config application
117------------------
118
119Local to the directory where an option group is relevant, suitable build logic
120should convert the CMake config options to appropriate compiler and/or linker
121flags. Those compile/link flags can be used in listing the affected targets as
122follows:
123
124.. code-block:: cmake
125
126   add_object_library(
127    ...
128    COMPILE_OPTIONS
129      ${common_printf_compile_options}
130      ... # Other compile options affecting this target irrespective of the
131          # libc config options
132   )
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 update
138====================
139
140The CMake configure step automatically generates the user document
141``doc/configure.rst``, which contains user information about the libc configure
142options, using the information in the main ``config/config.json`` file.
143An update to ``config/config.json`` will trigger reconfiguration by CMake, which
144in turn will regenerate the documentation in ``doc/configure.rst``.
145