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 1
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 1
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 1
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 1
178
179// ABSL_OPTION_USE_STD_ORDERING
180//
181// This option controls whether absl::{partial,weak,strong}_ordering are
182// implemented as aliases to the std:: ordering types, or as an independent
183// implementation.
184//
185// A value of 0 means to use Abseil's implementation. This requires only C++11
186// support, and is expected to work on every toolchain we support.
187//
188// A value of 1 means to use aliases. This requires that all code using Abseil
189// is built in C++20 mode or later.
190//
191// A value of 2 means to detect the C++ version being used to compile Abseil,
192// and use an alias only if working std:: ordering types are available. This
193// option is useful when you are building your program from source. It should
194// not be used otherwise -- for example, if you are distributing Abseil in a
195// binary package manager -- since in mode 2, they will name different types,
196// with different mangled names and binary layout, depending on the compiler
197// flags passed by the end user. For more info, see
198// https://abseil.io/about/design/dropin-types.
199//
200// User code should not inspect this macro. To check in the preprocessor if
201// the ordering types are aliases of std:: ordering types, use the feature macro
202// ABSL_USES_STD_ORDERING.
203
204#define ABSL_OPTION_USE_STD_ORDERING 0
205
206// ABSL_OPTION_USE_INLINE_NAMESPACE
207// ABSL_OPTION_INLINE_NAMESPACE_NAME
208//
209// These options controls whether all entities in the absl namespace are
210// contained within an inner inline namespace. This does not affect the
211// user-visible API of Abseil, but it changes the mangled names of all symbols.
212//
213// This can be useful as a version tag if you are distributing Abseil in
214// precompiled form. This will prevent a binary library build of Abseil with
215// one inline namespace being used with headers configured with a different
216// inline namespace name. Binary packagers are reminded that Abseil does not
217// guarantee any ABI stability in Abseil, so any update of Abseil or
218// configuration change in such a binary package should be combined with a
219// new, unique value for the inline namespace name.
220//
221// A value of 0 means not to use inline namespaces.
222//
223// A value of 1 means to use an inline namespace with the given name inside
224// namespace absl. If this is set, ABSL_OPTION_INLINE_NAMESPACE_NAME must also
225// be changed to a new, unique identifier name. In particular "head" is not
226// allowed.
227
228#define ABSL_OPTION_USE_INLINE_NAMESPACE 1
229#define ABSL_OPTION_INLINE_NAMESPACE_NAME lts_20240116
230
231// ABSL_OPTION_HARDENED
232//
233// This option enables a "hardened" build in release mode (in this context,
234// release mode is defined as a build where the `NDEBUG` macro is defined).
235//
236// A value of 0 means that "hardened" mode is not enabled.
237//
238// A value of 1 means that "hardened" mode is enabled.
239//
240// Hardened builds have additional security checks enabled when `NDEBUG` is
241// defined. Defining `NDEBUG` is normally used to turn `assert()` macro into a
242// no-op, as well as disabling other bespoke program consistency checks. By
243// defining ABSL_OPTION_HARDENED to 1, a select set of checks remain enabled in
244// release mode. These checks guard against programming errors that may lead to
245// security vulnerabilities. In release mode, when one of these programming
246// errors is encountered, the program will immediately abort, possibly without
247// any attempt at logging.
248//
249// The checks enabled by this option are not free; they do incur runtime cost.
250//
251// The checks enabled by this option are always active when `NDEBUG` is not
252// defined, even in the case when ABSL_OPTION_HARDENED is defined to 0. The
253// checks enabled by this option may abort the program in a different way and
254// log additional information when `NDEBUG` is not defined.
255
256#define ABSL_OPTION_HARDENED 0
257
258#endif // ABSL_BASE_OPTIONS_H_
259