[libc-commits] [libc] [libc] Add a developer doc about adding new config options. (PR #66432)

[via libc-commits]

================
@@ -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
----------------
michaelrj-google wrote:

this should also mention that the "doc" option will be copied into configure.rst when the docs are built.

https://github.com/llvm/llvm-project/pull/66432