path: root/doc/manual.cli
diff options
authorBoris Kolpackov <boris@codesynthesis.com>2021-10-05 07:29:02 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2021-10-05 07:29:02 +0200
commit2572a7015d9c2524a9d8299b2aa0b30ab8c880f5 (patch)
treea8b0989aa9402e3c61aac5fb94b964d7de8dbdab /doc/manual.cli
parent198e73e1cff1e0fd1aa14483dddb11b7fd31dd01 (diff)
Add note to internal scope documentation
Diffstat (limited to 'doc/manual.cli')
1 files changed, 19 insertions, 0 deletions
diff --git a/doc/manual.cli b/doc/manual.cli
index 46181ef..3318044 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -6808,6 +6808,25 @@ particular, this suppresses compiler warnings in such external headers
(\c{/external:W0} is automatically added unless a custom \c{/external:Wn} is
+\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
+\l{https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html System Headers} in
+the GCC 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
+template arguments we are instantiating it with. By default, all such warnings
+are suppressed and there is currently no way to change this with GCC/Clang
+\c{-isystem}. While MSVC provides \c{/external:templates-}, it cannot be
+applied on the library by library basis, only globally for the entire
+compilation. See MSVC \c{/external:templates-} documentation for more
+background on this issue.|
\N|In the future this functionality will be extended to side-building BMIs for
external module interfaces and header units.|