Great discussion, so before answering all your questions, please let's assume for a second that we don't have #pragma once. Also the name of the discussion is a little bit deceiving and it should be "introducing a new pp-token for single inclusion" to be specific.

1) What is this proposal trying to achieve?

The C++ preprocessor have a way to include files (header or source), but it doesn't have a mechanism to specify that a specific file (header or source) once included it shall not be included again in the current translation unit.

2) Don't we already have that?

No we don't, the only way we have is the inclusion guard which isn't efficient because it doesn't stop the compiler from further including the file, all it does is to guard the content to not being included again. yet the compiler shall test that file somehow to be sure of that.

3) How are we going to achieve that without breaking current implementations, each compiler detect file uniqueness in a different way?

The standard didn't specify a way for that and nor shall we. The standard explicitly stating that "How the places are specified or the header identified is implementation-defined." this is from [cpp.include] in the last statement in second paragraph.

what we going to do is extend the 4th paragraph in [lex.phases] from

> Preprocessing directives are executed, macro invocations are expanded, and _Pragma unary operator

expressions are executed. A #include preprocessing directive causes the named header or source file to

be processed from phase 1 through phase 4, recursively. All preprocessing directives are then deleted.

to be something like

> Preprocessing directives are executed, macro invocations are expanded, and _Pragma unary operator

expressions are executed. A #include preprocessing directive causes the named header or source file to

be processed from phase 1 through phase 4, recursively unless a previous execution for the preprocessing

statement #include once was done for that named header or source file. All preprocessing directives are then deleted.

As you can see we only introducing a way for the compiler to stop further inclusion of a specific header or source file once that statement is executed.

Also it is important to note that stopping further inclusion of the file doesn't mean stopping processing it. see this example

// a.hpp

#include once

#include "c.hpp"

#define A 1

// b.hpp

#include once

#include "a.hpp"

#define B 2

// c.hpp

#include "b.hpp"

#include "a.hpp"

#include once

#define C 2

let's see how the inclusion of c.hpp will work based on #include once

#include "c.hpp"

 |

+-- #include "b.hpp"

      |

     +-- #include once // current file "b.hpp" is now marked to not get included again

     +-- #include "a.hpp"

           |

          +-- #include once // current file "a.hpp" is now marked to not get included again

          +-- #define A 1 // we have a macro A with content equals to numeric 1

     +-- #define B 2 // we have a macro B with content equals to numeric 2

+-- #include "a.hpp" // don't expand already marked to not get included again

+-- #include once // current file "c.hpp" is now marked to not get included again

+-- #define C 3 // we have a macro A with content equals to numeric 3

Last thing about #include once, As with all preprocessing directive it get affected with the conditional #if family of preprocessing directive, for example:

//d.hpp

#ifdef D_HPP

#   include once

#endif

The file d.hpp will get included every time it appears in the #include until the macro D_HPP gets defined.

4) Why #include once and not #once or #include_once?

The #include syntax already allow for pp-tokens after it, so it will become easier for the implementations and more convenient to preserve the token "once" (all lower case unlike macros convention which will make it easy to spot it) rather than adding new directives.

5) Wait, isn't that behavior mostly how the #pragma once is working, and if so what benefit from adding this #include once?

Yes and no. Yes in the essence of marking the file for no more inclusion, and No in how it is implemented.

The #include once like other parts of the #include rules don't go on HOW the implementation should do it, but rather WHAT is the expected outcome from it.

The benefit come from adding such directive:

1) pragma is compiler specific and cannot be standardized.

2) it is a unified way to "include a header once" with minimal change to the standard (the parts to update mostly in [lex.phases] and [cpp.include] as well as the grammer).

3) it shall not break existing implementations, the general rules discussed here already implemented by major compilers (Clang, GCC and MSVC).

Hopefully this address the questions asked. 

------ Original Message ------

From "Peter Bindels via Std-Proposals" <std-proposals_at_[hidden]>

To std-proposals_at_[hidden]

Cc "Peter Bindels" <dascandy_at_[hidden]>

Date 3/23/2025 2:19:12 PM

Subject Re: [std-proposals] #pragma once safer alternative

On Sun, Mar 23, 2025 at 1:09 PM Sebastian Wittmeier via Std-Proposals <std-proposals_at_[hidden]> wrote:

Again the same question as Thiago asked Muhammad:

Is it only another name for #pragma once?

 

There were reasons, why #pragma once has not been standardized so far.

There were three major categories of objections to it.

One, we do not standardize pragmas. Not even when major implementations pretty much agree on the intent behind it, and what it's supposed to do (from a user point of view).

Two, "#pragma once" is not well-specified in what it does, and in those corner cases major implementations differ. They are the kinds of corner cases that your build environment should prevent, but when they do happen, different tools do something else.

Three, "#pragma once" is not well-specifyable in the C++ standard. The standard does not refer to "files" anywhere other than in std::filesystem (library), and has no good definition of "the same file". Adding that would be a *lot* of additional wording, a lot of churn and a lot of meetings in getting the words correct to mean what it should mean.

And in the end, what does that get us? The ability for people that use "#pragma once" to keep using it? The ability to say "it's in the standard now!"?

None of those are sufficient to explain the cost of making it happen. And *that* is why it was voted down last time.

It'd be great if, when we have a new attempt at this, we propose something that addresses *all* concerns that make it fail. Yes, this fixes #1, but at best it's the 5th attempt to do so. It doesn't even start on 2 or 3, which were the main reasons it was not voted in.

--
Std-Proposals mailing list
Std-Proposals_at_[hidden]
https://lists.isocpp.org/mailman/listinfo.cgi/std-proposals