[libc-commits] [libc] [libc] Add a developer doc about adding new config options. (PR #66432)
Siva Chandra via libc-commits
libc-commits at lists.llvm.org
Fri Sep 15 12:25:27 PDT 2023
https://github.com/sivachandra updated https://github.com/llvm/llvm-project/pull/66432
>From 23a1e12498f78592194efd3d2cf69524a06a558d Mon Sep 17 00:00:00 2001
From: Siva Chandra Reddy <sivachandra at google.com>
Date: Thu, 14 Sep 2023 13:59:21 -0700
Subject: [PATCH 1/2] [libc] Add a developer doc about adding new config
options.
---
libc/docs/dev/config_options.rst | 138 +++++++++++++++++++++++++++++++
libc/docs/dev/index.rst | 1 +
2 files changed, 139 insertions(+)
create mode 100644 libc/docs/dev/config_options.rst
diff --git a/libc/docs/dev/config_options.rst b/libc/docs/dev/config_options.rst
new file mode 100644
index 000000000000000..507a5538918c909
--- /dev/null
+++ b/libc/docs/dev/config_options.rst
@@ -0,0 +1,138 @@
+.. _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::
+
+ {
+ "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::
+
+ {
+ "printf": {
+ "LIBC_CONF_PRINTF_DISABLE_FLOAT": {
+ "value": true
+ }
+ }
+ }
+
+As you can see, 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::
+
+ {
+ "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::
+
+ 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::
+
+ 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.
diff --git a/libc/docs/dev/index.rst b/libc/docs/dev/index.rst
index 158089929b3af40..87712afcae2ac6f 100644
--- a/libc/docs/dev/index.rst
+++ b/libc/docs/dev/index.rst
@@ -12,6 +12,7 @@ Navigate to the links below for information on the respective topics:
source_tree_layout
entrypoints
cmake_build_rules
+ config_options
clang_tidy_checks
fuzzing
ground_truth_specification
>From b896939f588ec51d6c88d7dc82d4cdd4ec801107 Mon Sep 17 00:00:00 2001
From: Siva Chandra Reddy <sivachandra at google.com>
Date: Fri, 15 Sep 2023 12:24:02 -0700
Subject: [PATCH 2/2] [libc] Address comments.
---
libc/docs/dev/config_options.rst | 18 +++++++++++++-----
1 file changed, 13 insertions(+), 5 deletions(-)
diff --git a/libc/docs/dev/config_options.rst b/libc/docs/dev/config_options.rst
index 507a5538918c909..db70342ed74ce98 100644
--- a/libc/docs/dev/config_options.rst
+++ b/libc/docs/dev/config_options.rst
@@ -24,8 +24,8 @@ description about it listed against each option. For example:
}
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``
+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::
@@ -38,9 +38,8 @@ directory with the following contents:
}
}
-As you can see, the config for the baremetal platform overrides the common
-``false`` value of the ``LIBC_CONF_PRINTF_DISABLE_FLOAT`` with the ``true``
-value.
+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
==================
@@ -136,3 +135,12 @@ follows:
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``.
More information about the libc-commits
mailing list