1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
.. _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``.
|
