1 // Copyright 2019 The Abseil Authors. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 // 15 // ----------------------------------------------------------------------------- 16 // File: options.h 17 // ----------------------------------------------------------------------------- 18 // 19 // This file contains Abseil configuration options for setting specific 20 // implementations instead of letting Abseil determine which implementation to 21 // use at compile-time. Setting these options may be useful for package or build 22 // managers who wish to guarantee ABI stability within binary builds (which are 23 // otherwise difficult to enforce). 24 // 25 // *** IMPORTANT NOTICE FOR PACKAGE MANAGERS: It is important that 26 // maintainers of package managers who wish to package Abseil read and 27 // understand this file! *** 28 // 29 // Abseil contains a number of possible configuration endpoints, based on 30 // parameters such as the detected platform, language version, or command-line 31 // flags used to invoke the underlying binary. As is the case with all 32 // libraries, binaries which contain Abseil code must ensure that separate 33 // packages use the same compiled copy of Abseil to avoid a diamond dependency 34 // problem, which can occur if two packages built with different Abseil 35 // configuration settings are linked together. Diamond dependency problems in 36 // C++ may manifest as violations to the One Definition Rule (ODR) (resulting in 37 // linker errors), or undefined behavior (resulting in crashes). 38 // 39 // Diamond dependency problems can be avoided if all packages utilize the same 40 // exact version of Abseil. Building from source code with the same compilation 41 // parameters is the easiest way to avoid such dependency problems. However, for 42 // package managers who cannot control such compilation parameters, we are 43 // providing the file to allow you to inject ABI (Application Binary Interface) 44 // stability across builds. Settings options in this file will neither change 45 // API nor ABI, providing a stable copy of Abseil between packages. 46 // 47 // Care must be taken to keep options within these configurations isolated 48 // from any other dynamic settings, such as command-line flags which could alter 49 // these options. This file is provided specifically to help build and package 50 // managers provide a stable copy of Abseil within their libraries and binaries; 51 // other developers should not have need to alter the contents of this file. 52 // 53 // ----------------------------------------------------------------------------- 54 // Usage 55 // ----------------------------------------------------------------------------- 56 // 57 // For any particular package release, set the appropriate definitions within 58 // this file to whatever value makes the most sense for your package(s). Note 59 // that, by default, most of these options, at the moment, affect the 60 // implementation of types; future options may affect other implementation 61 // details. 62 // 63 // NOTE: the defaults within this file all assume that Abseil can select the 64 // proper Abseil implementation at compile-time, which will not be sufficient 65 // to guarantee ABI stability to package managers. 66 67 #ifndef ABSL_BASE_OPTIONS_H_ 68 #define ABSL_BASE_OPTIONS_H_ 69 70 // ----------------------------------------------------------------------------- 71 // Type Compatibility Options 72 // ----------------------------------------------------------------------------- 73 // 74 // ABSL_OPTION_USE_STD_ANY 75 // 76 // This option controls whether absl::any is implemented as an alias to 77 // std::any, or as an independent implementation. 78 // 79 // A value of 0 means to use Abseil's implementation. This requires only C++11 80 // support, and is expected to work on every toolchain we support. 81 // 82 // A value of 1 means to use an alias to std::any. This requires that all code 83 // using Abseil is built in C++17 mode or later. 84 // 85 // A value of 2 means to detect the C++ version being used to compile Abseil, 86 // and use an alias only if a working std::any is available. This option is 87 // useful when you are building your entire program, including all of its 88 // dependencies, from source. It should not be used otherwise -- for example, 89 // if you are distributing Abseil in a binary package manager -- since in 90 // mode 2, absl::any will name a different type, with a different mangled name 91 // and binary layout, depending on the compiler flags passed by the end user. 92 // For more info, see https://abseil.io/about/design/dropin-types. 93 // 94 // User code should not inspect this macro. To check in the preprocessor if 95 // absl::any is a typedef of std::any, use the feature macro ABSL_USES_STD_ANY. 96 97 #define ABSL_OPTION_USE_STD_ANY 2 98 99 100 // ABSL_OPTION_USE_STD_OPTIONAL 101 // 102 // This option controls whether absl::optional is implemented as an alias to 103 // std::optional, or as an independent implementation. 104 // 105 // A value of 0 means to use Abseil's implementation. This requires only C++11 106 // support, and is expected to work on every toolchain we support. 107 // 108 // A value of 1 means to use an alias to std::optional. This requires that all 109 // code using Abseil is built in C++17 mode or later. 110 // 111 // A value of 2 means to detect the C++ version being used to compile Abseil, 112 // and use an alias only if a working std::optional is available. This option 113 // is useful when you are building your program from source. It should not be 114 // used otherwise -- for example, if you are distributing Abseil in a binary 115 // package manager -- since in mode 2, absl::optional will name a different 116 // type, with a different mangled name and binary layout, depending on the 117 // compiler flags passed by the end user. For more info, see 118 // https://abseil.io/about/design/dropin-types. 119 120 // User code should not inspect this macro. To check in the preprocessor if 121 // absl::optional is a typedef of std::optional, use the feature macro 122 // ABSL_USES_STD_OPTIONAL. 123 124 #define ABSL_OPTION_USE_STD_OPTIONAL 0 125 126 127 // ABSL_OPTION_USE_STD_STRING_VIEW 128 // 129 // This option controls whether absl::string_view is implemented as an alias to 130 // std::string_view, or as an independent implementation. 131 // 132 // A value of 0 means to use Abseil's implementation. This requires only C++11 133 // support, and is expected to work on every toolchain we support. 134 // 135 // A value of 1 means to use an alias to std::string_view. This requires that 136 // all code using Abseil is built in C++17 mode or later. 137 // 138 // A value of 2 means to detect the C++ version being used to compile Abseil, 139 // and use an alias only if a working std::string_view is available. This 140 // option is useful when you are building your program from source. It should 141 // not be used otherwise -- for example, if you are distributing Abseil in a 142 // binary package manager -- since in mode 2, absl::string_view will name a 143 // different type, with a different mangled name and binary layout, depending on 144 // the compiler flags passed by the end user. For more info, see 145 // https://abseil.io/about/design/dropin-types. 146 // 147 // User code should not inspect this macro. To check in the preprocessor if 148 // absl::string_view is a typedef of std::string_view, use the feature macro 149 // ABSL_USES_STD_STRING_VIEW. 150 151 #define ABSL_OPTION_USE_STD_STRING_VIEW 2 152 153 // ABSL_OPTION_USE_STD_VARIANT 154 // 155 // This option controls whether absl::variant is implemented as an alias to 156 // std::variant, or as an independent implementation. 157 // 158 // A value of 0 means to use Abseil's implementation. This requires only C++11 159 // support, and is expected to work on every toolchain we support. 160 // 161 // A value of 1 means to use an alias to std::variant. This requires that all 162 // code using Abseil is built in C++17 mode or later. 163 // 164 // A value of 2 means to detect the C++ version being used to compile Abseil, 165 // and use an alias only if a working std::variant is available. This option 166 // is useful when you are building your program from source. It should not be 167 // used otherwise -- for example, if you are distributing Abseil in a binary 168 // package manager -- since in mode 2, absl::variant will name a different 169 // type, with a different mangled name and binary layout, depending on the 170 // compiler flags passed by the end user. For more info, see 171 // https://abseil.io/about/design/dropin-types. 172 // 173 // User code should not inspect this macro. To check in the preprocessor if 174 // absl::variant is a typedef of std::variant, use the feature macro 175 // ABSL_USES_STD_VARIANT. 176 177 #define ABSL_OPTION_USE_STD_VARIANT 0 178 179 180 // ABSL_OPTION_USE_INLINE_NAMESPACE 181 // ABSL_OPTION_INLINE_NAMESPACE_NAME 182 // 183 // These options controls whether all entities in the absl namespace are 184 // contained within an inner inline namespace. This does not affect the 185 // user-visible API of Abseil, but it changes the mangled names of all symbols. 186 // 187 // This can be useful as a version tag if you are distributing Abseil in 188 // precompiled form. This will prevent a binary library build of Abseil with 189 // one inline namespace being used with headers configured with a different 190 // inline namespace name. Binary packagers are reminded that Abseil does not 191 // guarantee any ABI stability in Abseil, so any update of Abseil or 192 // configuration change in such a binary package should be combined with a 193 // new, unique value for the inline namespace name. 194 // 195 // A value of 0 means not to use inline namespaces. 196 // 197 // A value of 1 means to use an inline namespace with the given name inside 198 // namespace absl. If this is set, ABSL_OPTION_INLINE_NAMESPACE_NAME must also 199 // be changed to a new, unique identifier name. In particular "head" is not 200 // allowed. 201 202 #define ABSL_OPTION_USE_INLINE_NAMESPACE 0 203 #define ABSL_OPTION_INLINE_NAMESPACE_NAME head 204 205 // ABSL_OPTION_HARDENED 206 // 207 // This option enables a "hardened" build in release mode (in this context, 208 // release mode is defined as a build where the `NDEBUG` macro is defined). 209 // 210 // A value of 0 means that "hardened" mode is not enabled. 211 // 212 // A value of 1 means that "hardened" mode is enabled. 213 // 214 // Hardened builds have additional security checks enabled when `NDEBUG` is 215 // defined. Defining `NDEBUG` is normally used to turn `assert()` macro into a 216 // no-op, as well as disabling other bespoke program consistency checks. By 217 // defining ABSL_OPTION_HARDENED to 1, a select set of checks remain enabled in 218 // release mode. These checks guard against programming errors that may lead to 219 // security vulnerabilities. In release mode, when one of these programming 220 // errors is encountered, the program will immediately abort, possibly without 221 // any attempt at logging. 222 // 223 // The checks enabled by this option are not free; they do incur runtime cost. 224 // 225 // The checks enabled by this option are always active when `NDEBUG` is not 226 // defined, even in the case when ABSL_OPTION_HARDENED is defined to 0. The 227 // checks enabled by this option may abort the program in a different way and 228 // log additional information when `NDEBUG` is not defined. 229 230 #define ABSL_OPTION_HARDENED 1 231 232 #endif // ABSL_BASE_OPTIONS_H_ 233