aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2021-10-08 13:41:11 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2021-10-08 13:41:11 +0200
commitf56a7aca92027340df89a146b0b7671e609e93c9 (patch)
treeefe59c7fae166c42c2199af4c53de7fcb5f7a1d4 /doc
parent9a9967c78420f6b3aa7c4f446b8ce2f71bbb9809 (diff)
Add few notes to internal scope documentation
Diffstat (limited to 'doc')
-rw-r--r--doc/manual.cli24
1 files changed, 18 insertions, 6 deletions
diff --git a/doc/manual.cli b/doc/manual.cli
index 3318044..4f256c9 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -6810,13 +6810,16 @@ specified).
\N|While the aim of this functionality is to control warnings in external
libraries, the underlying mechanisms currently provided by compilers have
-undesirable side effects. In particular, \c{-isystem} paths are searched after
-\c{-I} so translating \c{-I} to \c{-isystem} alters the search order. This
-should normally be harmless when using a development build of a library but
-may result in a change of semantics for installed libraries. Also, marking the
-search path as system has additional (to warning suppression) effects, see
+limitations and undesirable side effects. In particular, \c{-isystem} paths
+are searched after \c{-I} so translating \c{-I} to \c{-isystem} alters the
+search order. This should normally be harmless when using a development build
+of a library but may result in a change of semantics for installed
+libraries. Also, marking the search path as system has additional (to warning
+suppression) effects, see
\l{https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html System Headers} in
-the GCC documentation for details.
+the GCC documentation for details. On the MSVC side, \c{/external:W0}
+currently does not suppress some warnings (refer to the MSVC documentation for
+details).
Another issue is warnings in template instantiations. Each such warning could
be either due to a (potential) issue in the template itself or due to the
@@ -6882,6 +6885,15 @@ priority list:
In particular, item #3 allows an amalgamation that bundles a project to
override its internal scope.
+\N|If no \c{*.internal.scope} is specified by the project, user, or bundle,
+then this functionality is disabled and all libraries are treated as internal
+regardless of their location.
+
+While it may seem natural to have this enabled by default, the limitations and
+side effects of the underlying mechanisms as well as cases where it would be
+undesirable (such as in separate \c{*-tests} projects, see below) all suggest
+that explicit opt-in is probably the correct choice.|
+
The recommended value for a typical project is \c{current}, meaning that only
headers inside the project will be considered internal. The \c{tests}
subproject, if present, will inherit its value from the project (which acts as