Skip to content
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.

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

Use portable header identifiers #2149

Merged
merged 10 commits into from
Oct 12, 2023
Merged
Changes from all commits
Commits
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
31 changes: 30 additions & 1 deletion CppCoreGuidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -19208,6 +19208,7 @@ Source file rule summary:
* [SF.10: Avoid dependencies on implicitly `#include`d names](#Rs-implicit)
* [SF.11: Header files should be self-contained](#Rs-contained)
* [SF.12: Prefer the quoted form of `#include` for files relative to the including file and the angle bracket form everywhere else](#Rs-incform)
* [SF.13: Use portable header identifiers in `#include` statements](#Rs-portable-header-id)

* [SF.20: Use `namespace`s to express logical structure](#Rs-namespace)
* [SF.21: Don't use an unnamed (anonymous) namespace in a header](#Rs-unnamed)
Expand Down Expand Up @@ -19618,7 +19619,7 @@ Nevertheless, the guidance is to use the quoted form for including files that ex
#include <string> // From the standard library, requires the <> form
#include <some_library/common.h> // A file that is not locally relative, included from another library; use the <> form
#include "foo.h" // A file locally relative to foo.cpp in the same project, use the "" form
#include "foo_utils/utils.h" // A file locally relative to foo.cpp in the same project, use the "" form
#include "util/util.h" // A file locally relative to foo.cpp in the same project, use the "" form
#include <component_b/bar.h> // A file in the same project located via a search path, use the <> form

##### Note
Expand All @@ -19631,6 +19632,34 @@ Library creators should put their headers in a folder and have clients include t

A test should identify whether headers referenced via `""` could be referenced with `<>`.

### <a name="Rs-portable-header-id"></a>SF.13: Use portable header identifiers in `#include` statements

##### Reason

The [standard](http://eel.is/c++draft/cpp.include) does not specify how compilers uniquely locate headers from an identifier in an `#include` directive, nor does it specify what constitutes uniqueness. For example, whether the implementation considers the identifiers to be case-sensitive, or whether the identifiers are file system paths to a header file, and if so, how a hierarchical file system path is delimited.

To maximize the portability of `#include` directives across compilers, guidance is to:

* use case-sensitivity for the header identifier, matching how the header is defined by the standard, specification, implementation, or file that provides the header.
* when the header identifier is a hierarchical file path, use forward-slash `/` to delimit path components as this is the most widely-accepted path-delimiting character.

##### Example

// good examples
#include <vector>
#include <string>
#include "util/util.h"

// bad examples
#include <VECTOR> // bad: the standard library defines a header identified as <vector>, not <VECTOR>
#include <String> // bad: the standard library defines a header identified as <string>, not <String>
#include "Util/Util.H" // bad: the header file exists on the file system as "util/util.h"
#include "util\util.h" // bad: may not work if the implementation interprets `\u` as an escape sequence, or where '\' is not a valid path separator

##### Enforcement

It is only possible to enforce on implementations where header identifiers are case-sensitive and which only support `/` as a file path delimiter.

### <a name="Rs-namespace"></a>SF.20: Use `namespace`s to express logical structure

##### Reason
Expand Down