More documentation for C++ global config.
Bug: 296606895
Test: presubmit
Change-Id: I19a4fa327bf1eac192067caf6d064a740124caf6
diff --git a/cc/config/global.go b/cc/config/global.go
index a586a3f..1af8159 100644
--- a/cc/config/global.go
+++ b/cc/config/global.go
@@ -29,83 +29,112 @@
// Flags used by lots of devices. Putting them in package static variables
// will save bytes in build.ninja so they aren't repeated for every file
commonGlobalCflags = []string{
- "-DANDROID",
- "-fmessage-length=0",
- "-W",
+ // Enable some optimization by default.
+ "-O2",
+
+ // Warnings enabled by default. Reference:
+ // https://clang.llvm.org/docs/DiagnosticsReference.html
"-Wall",
- "-Wno-unused",
+ "-Wextra",
"-Winit-self",
"-Wpointer-arith",
- "-Wunreachable-code-loop-increment",
+ "-Wunguarded-availability",
- // Make paths in deps files relative
- "-no-canonical-prefixes",
+ // Warnings treated as errors by default.
+ // See also noOverrideGlobalCflags for errors that cannot be disabled
+ // from Android.bp files.
- "-DNDEBUG",
- "-UDEBUG",
-
- "-fno-exceptions",
-
- "-O2",
- "-fdebug-default-version=5",
-
- "-fno-strict-aliasing",
-
+ // Using __DATE__/__TIME__ causes build nondeterminism.
"-Werror=date-time",
+ // Detects forgotten */& that usually cause a crash
+ "-Werror=int-conversion",
+ // Detects unterminated alignment modification pragmas, which often lead
+ // to ABI mismatch between modules and hard-to-debug crashes.
"-Werror=pragma-pack",
+ // Same as above, but detects alignment pragmas around a header
+ // inclusion.
"-Werror=pragma-pack-suspicious-include",
+ // Detects dividing an array size by itself, which is a common typo that
+ // leads to bugs.
+ "-Werror=sizeof-array-div",
+ // Detects a typo that cuts off a prefix from a string literal.
"-Werror=string-plus-int",
+ // Detects for loops that will never execute more than once (for example
+ // due to unconditional break), but have a non-empty loop increment
+ // clause. Often a mistake/bug.
"-Werror=unreachable-code-loop-increment",
- // Force deprecation warnings to be warnings for code that compiles with -Werror.
- // Making deprecated usages an error causes extreme pain when trying to deprecate anything.
- "-Wno-error=deprecated-declarations",
+ // Warnings that should not be errors even for modules with -Werror.
+ // Making deprecated usages an error causes extreme pain when trying to
+ // deprecate anything.
+ "-Wno-error=deprecated-declarations",
+ // This rarely indicates a bug. http://b/145210666
+ "-Wno-error=reorder-init-list",
+
+ // Warnings disabled by default.
+
+ // Designated initializer syntax is recommended by the Google C++ style
+ // and is OK to use even if not formally supported by the chosen C++
+ // version.
+ "-Wno-c99-designator",
+ // Detects uses of a GNU C extension equivalent to a limited form of
+ // constexpr. Enabling this would require replacing many constants with
+ // macros, which is not a good trade-off.
+ "-Wno-gnu-folding-constant",
+ // AIDL generated code redeclares pure virtual methods in each
+ // subsequent version of an interface, so this warning is currently
+ // infeasible to enable.
+ "-Wno-inconsistent-missing-override",
+ // Incompatible with the Google C++ style guidance to use 'int' for loop
+ // indices; poor signal to noise ratio.
+ "-Wno-sign-compare",
+ // Poor signal to noise ratio.
+ "-Wno-unused",
+
+ // Global preprocessor constants.
+
+ "-DANDROID",
+ "-DNDEBUG",
+ "-UDEBUG",
"-D__compiler_offsetof=__builtin_offsetof",
+ // Allows the bionic versioning.h to indirectly determine whether the
+ // option -Wunguarded-availability is on or not.
+ "-D__ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__",
+
+ // -f and -g options.
// Emit address-significance table which allows linker to perform safe ICF. Clang does
// not emit the table by default on Android since NDK still uses GNU binutils.
"-faddrsig",
- // Help catch common 32/64-bit errors.
- "-Werror=int-conversion",
+ // Emit debugging data in a modern format (DWARF v5).
+ "-fdebug-default-version=5",
// Force clang to always output color diagnostics. Ninja will strip the ANSI
// color codes if it is not running in a terminal.
"-fcolor-diagnostics",
- // -Wno-sign-compare is incompatible with the Google C++ style guidance
- // to use 'int' for loop indices, and the signal to noise ratio is poor
- // anyway.
- "-Wno-sign-compare",
-
- // AIDL generated code redeclares pure virtual methods in each
- // subsequent version of an interface, so this is currently infeasible
- // to enable.
- "-Wno-inconsistent-missing-override",
-
- // Designated initializer syntax is recommended by the Google C++ style
- // guide and should not be a warning, at least by default.
- "-Wno-c99-designator",
-
- // Warnings from clang-12
- "-Wno-gnu-folding-constant",
-
- // http://b/145210666
- "-Wno-error=reorder-init-list",
-
- // Calls to the APIs that are newer than the min sdk version of the caller should be
- // guarded with __builtin_available.
- "-Wunguarded-availability",
- // This macro allows the bionic versioning.h to indirectly determine whether the
- // option -Wunguarded-availability is on or not.
- "-D__ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__",
-
// Turn off FMA which got enabled by default in clang-r445002 (http://b/218805949)
"-ffp-contract=off",
+ // Google C++ style does not allow exceptions, turn them off by default.
+ "-fno-exceptions",
+
+ // Disable optimizations based on strict aliasing by default.
+ // The performance benefit of enabling them currently does not outweigh
+ // the risk of hard-to-reproduce bugs.
+ "-fno-strict-aliasing",
+
+ // Disable line wrapping for error messages - it interferes with
+ // displaying logs in web browsers.
+ "-fmessage-length=0",
+
// Using simple template names reduces the size of debug builds.
"-gsimple-template-names",
+
+ // Make paths in deps files relative.
+ "-no-canonical-prefixes",
}
commonGlobalConlyflags = []string{}
@@ -117,6 +146,7 @@
"-fdebug-default-version=4",
}
+ // Compilation flags for device code; not applied to host code.
deviceGlobalCflags = []string{
"-ffunction-sections",
"-fdata-sections",
@@ -152,6 +182,7 @@
"-fvisibility-inlines-hidden",
}
+ // Linking flags for device code; not applied to host binaries.
deviceGlobalLdflags = []string{
"-Wl,-z,noexecstack",
"-Wl,-z,relro",
@@ -194,6 +225,14 @@
// These flags are appended after the module's cflags, so they cannot be
// overridden from Android.bp files.
+ //
+ // NOTE: if you need to disable a warning to unblock a compiler upgrade
+ // and it is only triggered by third party code, add it to
+ // extraExternalCflags (if possible) or noOverrideExternalGlobalCflags
+ // (if the former doesn't work). If the new warning also occurs in first
+ // party code, try adding it to commonGlobalCflags first. Adding it here
+ // should be the last resort, because it prevents all code in Android from
+ // opting into the warning.
noOverrideGlobalCflags = []string{
"-Werror=bool-operation",
"-Werror=format-insufficient-args",
@@ -245,35 +284,9 @@
noOverride64GlobalCflags = []string{}
- // Similar to noOverrideGlobalCflags, but applies only to third-party code
- // (anything for which IsThirdPartyPath() in build/soong/android/paths.go
- // returns true - includes external/, most of vendor/ and most of hardware/)
- noOverrideExternalGlobalCflags = []string{
- // http://b/151457797
- "-fcommon",
- // http://b/191699019
- "-Wno-format-insufficient-args",
- // http://b/296321145
- // Indicates potential memory or stack corruption, so should be changed
- // to a hard error. Currently triggered by some vendor code.
- "-Wno-incompatible-function-pointer-types",
- // http://b/296321508
- // Introduced in response to a critical security vulnerability and
- // should be a hard error - it requires only whitespace changes to fix.
- "-Wno-misleading-indentation",
- // Triggered by old LLVM code in external/llvm. Likely not worth
- // enabling since it's a cosmetic issue.
- "-Wno-bitwise-instead-of-logical",
-
- "-Wno-unused-but-set-variable",
- "-Wno-unused-but-set-parameter",
- "-Wno-unqualified-std-cast-call",
- "-Wno-array-parameter",
- "-Wno-gnu-offsetof-extensions",
- }
-
- // Extra cflags for external third-party projects to disable warnings that
- // are infeasible to fix in all the external projects and their upstream repos.
+ // Extra cflags applied to third-party code (anything for which
+ // IsThirdPartyPath() in build/soong/android/paths.go returns true;
+ // includes external/, most of vendor/ and most of hardware/)
extraExternalCflags = []string{
"-Wno-enum-compare",
"-Wno-enum-compare-switch",
@@ -303,11 +316,41 @@
"-Wno-deprecated-non-prototype",
}
+ // Similar to noOverrideGlobalCflags, but applies only to third-party code
+ // (see extraExternalCflags).
+ // This section can unblock compiler upgrades when a third party module that
+ // enables -Werror and some group of warnings explicitly triggers newly
+ // added warnings.
+ noOverrideExternalGlobalCflags = []string{
+ // http://b/151457797
+ "-fcommon",
+ // http://b/191699019
+ "-Wno-format-insufficient-args",
+ // http://b/296321145
+ // Indicates potential memory or stack corruption, so should be changed
+ // to a hard error. Currently triggered by some vendor code.
+ "-Wno-incompatible-function-pointer-types",
+ // http://b/296321508
+ // Introduced in response to a critical security vulnerability and
+ // should be a hard error - it requires only whitespace changes to fix.
+ "-Wno-misleading-indentation",
+ // Triggered by old LLVM code in external/llvm. Likely not worth
+ // enabling since it's a cosmetic issue.
+ "-Wno-bitwise-instead-of-logical",
+
+ "-Wno-unused-but-set-variable",
+ "-Wno-unused-but-set-parameter",
+ "-Wno-unqualified-std-cast-call",
+ "-Wno-array-parameter",
+ "-Wno-gnu-offsetof-extensions",
+ }
+
llvmNextExtraCommonGlobalCflags = []string{
// Do not report warnings when testing with the top of trunk LLVM.
"-Wno-error",
}
+ // Flags that must not appear in any command line.
IllegalFlags = []string{
"-w",
}