From f56a7aca92027340df89a146b0b7671e609e93c9 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Fri, 8 Oct 2021 13:41:11 +0200 Subject: Add few notes to internal scope documentation --- doc/manual.cli | 24 ++++++++++++++++++------ 1 file 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 -- cgit v1.1