From 253616de7e8fa4f410e294867abe3ca4cbafdb79 Mon Sep 17 00:00:00 2001
From: Jeff Bailey <jbailey@raspberryginger.com>
Date: Wed, 18 Mar 2026 16:51:13 +0000
Subject: [PATCH] [libc][docs] Generate configure.rst in the build directory
 (#187266)

generate_config_doc() was writing configure.rst directly into the source
tree, which fails when building from a read-only source directory (e.g.
when the source is on a read-only filesystem or in a packaging
environment).

The Sphinx build in libc/docs/CMakeLists.txt already copies static .rst
files from the source tree into the build tree so that generated docs
don't pollute the source directory. Move configure.rst generation to
follow this same pattern by writing to LIBC_BUILD_DIR/docs/ instead of
LIBC_SOURCE_DIR/docs/.

This also removes configure.rst from the checked-in source tree, since
it was fully generated content that was being regenerated on every CMake
configure anyway.
---
 libc/CMakeLists.txt                 |  2 +-
 libc/cmake/modules/LibcConfig.cmake |  2 +
 libc/docs/configure.rst             | 80 -----------------------------
 3 files changed, 3 insertions(+), 81 deletions(-)
 delete mode 100644 libc/docs/configure.rst

diff --git a/libc/CMakeLists.txt b/libc/CMakeLists.txt
index 2d474f08841c..7a5ed88ef054 100644
--- a/libc/CMakeLists.txt
+++ b/libc/CMakeLists.txt
@@ -216,7 +216,7 @@ foreach(opt IN LISTS global_config)
   message(STATUS "${opt_name}: ${opt_value}")
   set(${opt_name} ${opt_value})
 endforeach()
-generate_config_doc(${main_config_file} ${LIBC_SOURCE_DIR}/docs/configure.rst)
+generate_config_doc(${main_config_file} ${LIBC_BUILD_DIR}/docs/configure.rst)
 
 # Load each target specific config.
 foreach(config_path IN LISTS LIBC_CONFIG_JSON_FILE_LIST)
diff --git a/libc/cmake/modules/LibcConfig.cmake b/libc/cmake/modules/LibcConfig.cmake
index da166dd6cc3f..19bdf44d96bf 100644
--- a/libc/cmake/modules/LibcConfig.cmake
+++ b/libc/cmake/modules/LibcConfig.cmake
@@ -139,6 +139,8 @@ function(generate_config_doc config_file doc_file)
   if(NOT EXISTS ${config_file})
     message(FATAL_ERROR "${config_file} does not exist")
   endif()
+  get_filename_component(doc_dir ${doc_file} DIRECTORY)
+  file(MAKE_DIRECTORY ${doc_dir})
   file(READ ${config_file} json_config)
   string(JSON group_count ERROR_VARIABLE json_error LENGTH ${json_config})
   if(json_error)
diff --git a/libc/docs/configure.rst b/libc/docs/configure.rst
deleted file mode 100644
index 06d20df261bc..000000000000
--- a/libc/docs/configure.rst
+++ /dev/null
@@ -1,80 +0,0 @@
-.. _configure:
-..
-   Do not edit this file directly. CMake will auto generate it.
-   If the changes are intended, add this file to your commit.
-
-==========================
-Configure Options
-==========================
-
-Below is the full set of options one can use to configure the libc build.
-An option can be given an explicit value on the CMake command line using
-the following syntax:
-
-.. code-block:: sh
-
-  $> cmake <other build options> -D<libc config option name>=<option value> <more options>
-
-For example:
-
-.. code-block:: sh
-
-  $> cmake <other build options> -DLIBC_CONF_PRINTF_DISABLE_FLOAT=ON <more options>
-
-See the main ``config/config.json``, and the platform and architecture specific
-overrides in ``config/<platform>/config.json`` and ``config/<platform>/<arch>/config.json,``
-to learn about the defaults for your platform and target.
-
-* **"codegen" options**
-    - ``LIBC_CONF_ENABLE_STRONG_STACK_PROTECTOR``: Enable -fstack-protector-strong to defend against stack smashing attack.
-    - ``LIBC_CONF_KEEP_FRAME_POINTER``: Keep frame pointer in functions for better debugging experience.
-* **"ctype" options**
-    - ``LIBC_CONF_CTYPE_SMALLER_ASCII``: Shrinks b36_char_to_int by assuming the character encoding is ASCII.
-* **"errno" options**
-    - ``LIBC_CONF_ERRNO_MODE``: The implementation used for errno, acceptable values are LIBC_ERRNO_MODE_DEFAULT, LIBC_ERRNO_MODE_UNDEFINED, LIBC_ERRNO_MODE_THREAD_LOCAL, LIBC_ERRNO_MODE_SHARED, LIBC_ERRNO_MODE_EXTERNAL, and LIBC_ERRNO_MODE_SYSTEM_INLINE.
-* **"fenv" options**
-    - ``LIBC_CONF_TRAP_ON_RAISE_FP_EXCEPT``: Trap with SIGFPE when feraiseexcept is called with unmasked floating point exceptions, similar to glibc's behavior.  This is currently working only on x86 with SSE.
-* **"general" options**
-    - ``LIBC_ADD_NULL_CHECKS``: Add nullptr checks in the library's implementations to some functions for which passing nullptr is undefined behavior.
-* **"math" options**
-    - ``LIBC_CONF_FREXP_INF_NAN_EXPONENT``: The value written back to the second parameter when calling frexp/frexpf/frexpl` with `+/-Inf`/`NaN` is unspecified.  Configure an explicit exp value for Inf/NaN inputs.
-    - ``LIBC_CONF_MATH_OPTIMIZATIONS``: Configure optimizations for math functions. Values accepted are LIBC_MATH_SKIP_ACCURATE_PASS, LIBC_MATH_SMALL_TABLES, LIBC_MATH_NO_ERRNO, LIBC_MATH_NO_EXCEPT, LIBC_MATH_FAST, and LIBC_MATH_INTERMEDIATE_COMP_IN_FLOAT.
-    - ``LIBC_CONF_MATH_USE_SYSTEM_FENV``: Use C standard fenv.h calls from the system libc instead our internal fenv implementations.
-* **"printf" options**
-    - ``LIBC_CONF_PRINTF_DISABLE_FIXED_POINT``: Disable printing fixed point values in printf and friends.
-    - ``LIBC_CONF_PRINTF_DISABLE_FLOAT``: Disable printing floating point values in printf and friends.
-    - ``LIBC_CONF_PRINTF_DISABLE_INDEX_MODE``: Disable index mode in the printf format string.
-    - ``LIBC_CONF_PRINTF_DISABLE_STRERROR``: Disable handling of %m to print strerror in printf and friends.
-    - ``LIBC_CONF_PRINTF_DISABLE_WIDE``: Disable handling wide characters for printf and friends.
-    - ``LIBC_CONF_PRINTF_DISABLE_WRITE_INT``: Disable handling of %n in printf format string.
-    - ``LIBC_CONF_PRINTF_FLOAT_TO_STR_NO_SPECIALIZE_LD``: Use the same mode for double and long double in printf.
-    - ``LIBC_CONF_PRINTF_FLOAT_TO_STR_USE_DYADIC_FLOAT``: Use dyadic float for faster and smaller but less accurate printf doubles.
-    - ``LIBC_CONF_PRINTF_FLOAT_TO_STR_USE_FLOAT320``: Use an alternative printf float implementation based on 320-bit floats
-    - ``LIBC_CONF_PRINTF_FLOAT_TO_STR_USE_MEGA_LONG_DOUBLE_TABLE``: Use large table for better printf long double performance.
-    - ``LIBC_CONF_PRINTF_RUNTIME_DISPATCH``: Use dynamic dispatch for the output mechanism to reduce code size.
-    - ``LIBC_COPT_PRINTF_DISABLE_BITINT``: Disable bitint length modifiers to reduce code size. Specifically the wNUM and wfNUM modifiers.
-* **"pthread" options**
-    - ``LIBC_CONF_RAW_MUTEX_DEFAULT_SPIN_COUNT``: Default number of spins before blocking if a mutex is in contention (default to 100).
-    - ``LIBC_CONF_RWLOCK_DEFAULT_SPIN_COUNT``: Default number of spins before blocking if a rwlock is in contention (default to 100).
-    - ``LIBC_CONF_TIMEOUT_ENSURE_MONOTONICITY``: Automatically adjust timeout to CLOCK_MONOTONIC (default to true). POSIX API may require CLOCK_REALTIME, which can be unstable and leading to unexpected behavior. This option will convert the real-time timestamp to monotonic timestamp relative to the time of call.
-* **"qsort" options**
-    - ``LIBC_CONF_QSORT_IMPL``: Configures sorting algorithm for qsort and qsort_r. Values accepted are LIBC_QSORT_QUICK_SORT, LIBC_QSORT_HEAP_SORT.
-* **"scanf" options**
-    - ``LIBC_CONF_SCANF_DISABLE_FLOAT``: Disable parsing floating point values in scanf and friends.
-    - ``LIBC_CONF_SCANF_DISABLE_INDEX_MODE``: Disable index mode in the scanf format string.
-* **"setjmp" options**
-    - ``LIBC_CONF_SETJMP_AARCH64_RESTORE_PLATFORM_REGISTER``: Make setjmp save the value of x18, and longjmp restore it. The AArch64 ABI delegates this register to platform ABIs, which can choose whether to make it caller-saved.
-* **"str_to_float" options**
-    - ``LIBC_CONF_STRTOFLOAT_DISABLE_CLINGER_FAST_PATH``: Disable Clinger's fast path for string to float conversion.
-    - ``LIBC_CONF_STRTOFLOAT_DISABLE_EISEL_LEMIRE``: Disable Eisel-Lemire algorithm for string to float conversion.
-    - ``LIBC_CONF_STRTOFLOAT_DISABLE_SIMPLE_DECIMAL_CONVERSION``: Disable simple decimal conversion for string to float conversion.
-* **"string" options**
-    - ``LIBC_CONF_FIND_FIRST_CHARACTER_IMPL``: Selects the implementation for find-first-character-related functions: 'element', 'word', 'clang_vector', or 'arch_vector'.
-    - ``LIBC_CONF_MEMSET_X86_USE_SOFTWARE_PREFETCHING``: Inserts prefetch for write instructions (PREFETCHW) for memset on x86 to recover performance when hardware prefetcher is disabled.
-    - ``LIBC_CONF_STRING_LENGTH_IMPL``: Selects the implementation for string-length: 'element', 'word', 'clang_vector', or 'arch_vector'.
-* **"threads" options**
-    - ``LIBC_CONF_THREAD_MODE``: The implementation used for Mutex, acceptable values are LIBC_THREAD_MODE_PLATFORM, LIBC_THREAD_MODE_SINGLE, and LIBC_THREAD_MODE_EXTERNAL.
-* **"time" options**
-    - ``LIBC_CONF_TIME_64BIT``: Force the size of time_t to 64 bits, even on platforms where compatibility considerations would otherwise make it 32-bit.
-* **"wctype" options**
-    - ``LIBC_CONF_WCTYPE_MODE``: The implementation used for wctype, acceptable values are LIBC_WCTYPE_MODE_ASCII and LIBC_WCTYPE_MODE_UTF8.