[clang] 85c54a5 - [Docs] Document freestanding requirements (#132232)

[via cfe-commits]

Author: Aaron Ballman
Date: 2025-03-27T13:17:05-04:00
New Revision: 85c54a519fa6856b3e9a462445633ed4535eafa4

URL: https://github.com/llvm/llvm-project/commit/85c54a519fa6856b3e9a462445633ed4535eafa4
DIFF: https://github.com/llvm/llvm-project/commit/85c54a519fa6856b3e9a462445633ed4535eafa4.diff

LOG: [Docs] Document freestanding requirements (#132232)

This adds some initial documentation about freestanding requirements for
Clang. The most critical part of the documentation is spelling out that
a conforming freestanding C Standard Library is required; Clang will not
be providing the headers for <string.h> in C23 which expose a number of
symbols in freestanding mode.

The docs also make it clear that in addition to a conforming
freestanding C standard library, the library must provide some
additional symbols which LLVM requires.

These docs are not comprehensive, this is just getting the bare bones in
place so that they can be expanded later.

This also updates the C status page to make it clear that we don't have
anything to do for WG14 N2524 which adds string interfaces to
freestanding mode.

Added: 
    

Modified: 
    clang/docs/CommandGuide/clang.rst
    clang/docs/UsersManual.rst
    clang/www/c_status.html

Removed: 
    


################################################################################
diff  --git a/clang/docs/CommandGuide/clang.rst b/clang/docs/CommandGuide/clang.rst
index f0d94a4e628b0..42aac7b25d93c 100644
--- a/clang/docs/CommandGuide/clang.rst
+++ b/clang/docs/CommandGuide/clang.rst
@@ -262,9 +262,10 @@ Language Selection and Mode Options
 .. option:: -ffreestanding
 
  Indicate that the file should be compiled for a freestanding, not a hosted,
- environment. Note that it is assumed that a freestanding environment will
- additionally provide `memcpy`, `memmove`, `memset` and `memcmp`
- implementations, as these are needed for efficient codegen for many programs.
+ environment. Note that a freestanding build still requires linking against a C
+ Standard Library which supports the freestanding interfaces for the specified
+ language mode and target environment. This includes functions like `memcpy`,
+ `memmove`, and `memset`.
 
 .. option:: -fno-builtin
 

diff  --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 2ea4b9d90ad34..2a93c2552d7dc 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -1073,6 +1073,35 @@ inputs. Here is some example of ``$``-prefixed options:
 Language and Target-Independent Features
 ========================================
 
+Freestanding Builds
+-------------------
+Passing the ``-ffreestanding`` flag causes Clang to build for a freestanding
+(rather than a hosted) environment. The flag has the following effects:
+
+* the ``__STDC_HOSTED__`` predefined macro will expand to ``0``,
+* builtin functions are disabled by default (``-fno-builtins``),
+* unwind tables are disabled by default 
+  (``fno-asynchronous-unwind-tables -fno-unwind-tables``), and
+* does not treat the global ``main`` function as a special function.
+
+An implementation of the following runtime library functions must always be
+provided with the usual semantics, as Clang will generate calls to them:
+
+* ``memcpy``,
+* ``memmove``, and
+* ``memset``.
+
+Clang does not, by itself, provide a full "conforming freestanding
+implementation". If you wish to have a conforming freestanding implementation,
+you must provide a freestanding C library. While Clang provides some of the
+required header files, it does not provide all of them, nor any library
+implementations.
+
+Conversely, when ``-ffreestanding`` is specified, Clang does not require you to
+provide a conforming freestanding implementation library. Clang will not make
+any assumptions as to the availability or semantics of standard-library
+functions other than those mentioned above.
+
 Controlling Errors and Warnings
 -------------------------------
 

diff  --git a/clang/www/c_status.html b/clang/www/c_status.html
index c9e2eda4304f3..ee0cd057916ba 100644
--- a/clang/www/c_status.html
+++ b/clang/www/c_status.html
@@ -534,11 +534,6 @@ <h2 id="c2x">C23 implementation status</h2>
       <td class="full" align="center">Clang 16</td>
     </tr>
     <!-- Apr 2021 Papers -->
-    <tr>
-      <td>String functions for freestanding implementations</td>
-      <td><a href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2524.htm">N2524</a></td>
-      <td class="none" align="center">No</td>
-    </tr>
     <tr>
       <td>Digit separators</td>
       <td><a href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2626.pdf">N2626</a></td>