From 933bee2b4a1c691900ac6792690453b3186de7e2 Mon Sep 17 00:00:00 2001 From: John Ciolfi Date: Fri, 18 Apr 2025 10:02:07 -0400 Subject: [PATCH 1/2] Rs-incform: clarify what a relative path is and offer implementation suggestion - Add and example clarifying that #include "utilities.hpp" or #include "../module1/utilities.hpp" can resolve to same file and are both relative. - With this clarification, enforcement becomes very easy because compilers can report the absolute path of the file being reference. --- CppCoreGuidelines.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/CppCoreGuidelines.md b/CppCoreGuidelines.md index 8b3c2b022..b9c8113b3 100644 --- a/CppCoreGuidelines.md +++ b/CppCoreGuidelines.md @@ -19629,9 +19629,18 @@ Failing to follow this results in difficult to diagnose errors due to picking up Library creators should put their headers in a folder and have clients include those files using the relative path `#include ` +##### Project Example + +Consider a project with modules where src/module2/foo.cpp is using src/module1/utilities.hpp: + + projectRoot/src/module1/utilities.hpp + projectRoot/src/module2/foo.cpp // #include "../module1/utilities.hpp" OR #include "utilities.hpp" with -I../module1 + +foo.cpp can `#include "../module1/utilities.hpp"` or it can `#include "utilities.hpp"` and provide the compiler with the relative path to module1 (e.g. `g++ -o foo.o -I../module1 foo.cpp`). Using either quoted form, makes it clear that utilities.hpp is part of the project and will remain with the project when it is cloned. Likewise, headers included using angle brackets such as `#include ` cannot be modified in the project. If an angle-bracket header is modified, it can impact many projects including those of other users on the system. + ##### Enforcement -A test should identify whether headers referenced via `""` could be referenced with `<>`. +A test should identify whether headers referenced via `""` could be referenced with `<>`. Compilers can report the absolute path of file being referenced in a `#include` directive and using this information, the test can verify that all includes of headers within the project root are included using quotes. ### SF.13: Use portable header identifiers in `#include` statements From 57e3257b9e71e14233daca02679be920c68a186e Mon Sep 17 00:00:00 2001 From: John Ciolfi Date: Sat, 19 Apr 2025 08:54:21 -0400 Subject: [PATCH 2/2] Rs-incform: in project example use generic component term, add newline before enforcement tip --- CppCoreGuidelines.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/CppCoreGuidelines.md b/CppCoreGuidelines.md index b9c8113b3..57737f68d 100644 --- a/CppCoreGuidelines.md +++ b/CppCoreGuidelines.md @@ -19631,16 +19631,18 @@ Library creators should put their headers in a folder and have clients include t ##### Project Example -Consider a project with modules where src/module2/foo.cpp is using src/module1/utilities.hpp: +Consider a project with two components where src/component2/foo.cpp is using src/component1/utilities.hpp: - projectRoot/src/module1/utilities.hpp - projectRoot/src/module2/foo.cpp // #include "../module1/utilities.hpp" OR #include "utilities.hpp" with -I../module1 + projectRoot/src/component1/utilities.hpp + projectRoot/src/component2/foo.cpp // #include "../component1/utilities.hpp" OR #include "utilities.hpp" with -I../component1 -foo.cpp can `#include "../module1/utilities.hpp"` or it can `#include "utilities.hpp"` and provide the compiler with the relative path to module1 (e.g. `g++ -o foo.o -I../module1 foo.cpp`). Using either quoted form, makes it clear that utilities.hpp is part of the project and will remain with the project when it is cloned. Likewise, headers included using angle brackets such as `#include ` cannot be modified in the project. If an angle-bracket header is modified, it can impact many projects including those of other users on the system. +foo.cpp can `#include "../component1/utilities.hpp"` or it can `#include "utilities.hpp"` and provide the compiler with the relative path to component1 (e.g. `g++ -o foo.o -I../component1 foo.cpp`). Using either quoted form, makes it clear that utilities.hpp is part of the project and will remain with the project when it is cloned. Likewise, headers included using angle brackets such as `#include ` cannot be modified in the project. If an angle-bracket header is modified, it can impact many projects including those of other users on the system. ##### Enforcement -A test should identify whether headers referenced via `""` could be referenced with `<>`. Compilers can report the absolute path of file being referenced in a `#include` directive and using this information, the test can verify that all includes of headers within the project root are included using quotes. +A test should identify whether headers referenced via `""` could be referenced with `<>`. + +Compilers can report the absolute path of file being referenced in a `#include` directive and using this information, the test can verify that all includes of headers within the project root are included using quotes. ### SF.13: Use portable header identifiers in `#include` statements