Skip to content

[Docs] Document freestanding requirements #132232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Mar 27, 2025
Merged

[Docs] Document freestanding requirements #132232

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5008e3c
[Docs] Document freestanding requirements
AaronBallman Mar 20, 2025
e6bcd39
Update based on review feedback
AaronBallman Mar 21, 2025
537dc66
Added a few more updates
AaronBallman Mar 21, 2025
d593347
Remove a mention about memcmp
AaronBallman Mar 21, 2025
6576792
Update based on review feedback
AaronBallman Mar 24, 2025
b88b4a0
Disabled -> diabled by default
AaronBallman Mar 25, 2025
74bbff4
Reword based on review feedback
AaronBallman Mar 26, 2025
bcd5db3
Slight rewording based on review feedback
AaronBallman Mar 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions clang/docs/CommandGuide/clang.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
29 changes: 29 additions & 0 deletions clang/docs/UsersManual.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------------------------------

Expand Down
5 changes: 0 additions & 5 deletions clang/www/c_status.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Comment on lines -537 to -541
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Although the PR description said:

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.

It seem to me that the status will become less clear due to removal of the entry.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't typically document anything which the compiler isn't required to provide (for example, we don't really list other things from the C standard library). We could add an N/A status like we have for DRs, but I think that would start to drown out the relevant information due to talking about editorial changes as well as library changes.

WDYT?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW we list all the LWG papers and issues in the libc++ docs, and IMO it's useful. That makes it clear whether we've considered the paper/issue and what our conclusion was. Since most papers by far require changes, it's also really not cluttering the list too much.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a bit different though -- libc++ lists library issues and papers, not Core issues and papers, because it's an implementation of the library. In this case, Clang doesn't provide any libc functionality, so we typically do not list any C Standard Library papers (just the core wording papers). But freestanding can either be "the compiler provides this" or "the library provides this". In this case, the library provides this, so I don't think it makes sense to list it as a feature the compiler needs to provide.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I found that c_status.html is currently listing some library-only changes (e.g. N2359 and possibly N2951). Perhaps a thorough cleanup (in a later PR) is desired?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

N2359 applies to the compiler because it introduces new potentially reserved identifiers we may want to diagnose and it changes behavior of limits.h which Clang provides.

N2951 applies to the compiler because it imposes some requirements on freestanding regarding FENV_ACCESS. It's questionable whether this one belongs on the list or not. It's marked as "Unknown" currently because I've not spent the time trying to figure out whether we have anything to do here or not.

But yes, cleaning these up in a later PR is a good idea. FWIW, I've been removing ones as I realize they don't impact the compiler.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, yeah. I guess the call what is compiler and library is a bit less explicit in C, since there isn't a CWG/LWG distinction. I guess we also only list CWG papers that affect the library in some way and not all of them.

<tr>
<td>Digit separators</td>
<td><a href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2626.pdf">N2626</a></td>
Expand Down