aboutsummaryrefslogtreecommitdiffstats
path: root/contrib/restricted/abseil-cpp-tstring/FAQ.md
blob: 2df87867a6488ba550fd98b4015b9e6059cc51ba (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
# Abseil FAQ 
 
## Is Abseil the right home for my utility library? 
 
Most often the answer to the question is "no." As both the [About 
Abseil](https://abseil.io/about/) page and our [contributing 
guidelines](https://github.com/abseil/abseil-cpp/blob/master/CONTRIBUTING.md#contribution-guidelines) 
explain, Abseil contains a variety of core C++ library code that is widely used 
at [Google](https://www.google.com/). As such, Abseil's primary purpose is to be 
used as a dependency by Google's open source C++ projects. While we do hope that 
Abseil is also useful to the C++ community at large, this added constraint also 
means that we are unlikely to accept a contribution of utility code that isn't 
already widely used by Google. 
 
## How to I set the C++ dialect used to build Abseil? 
 
The short answer is that whatever mechanism you choose, you need to make sure 
that you set this option consistently at the global level for your entire 
project. If, for example, you want to set the C++ dialect to C++17, with 
[Bazel](https://bazel/build/) as the build system and `gcc` or `clang` as the 
compiler, there several ways to do this: 
* Pass `--cxxopt=-std=c++17` on the command line (for example, `bazel build 
  --cxxopt=-std=c++17 ...`) 
* Set the environment variable `BAZEL_CXXOPTS` (for example, 
  `BAZEL_CXXOPTS=-std=c++17`) 
* Add `build --cxxopt=-std=c++17` to your [`.bazelrc` 
  file](https://docs.bazel.build/versions/master/guide.html#bazelrc) 
 
If you are using CMake as the build system, you'll need to add a line like 
`set(CMAKE_CXX_STANDARD 17)` to your top level `CMakeLists.txt` file. If you
are developing a library designed to be used by other clients, you should
instead leave `CMAKE_CXX_STANDARD` unset and configure the minimum C++ standard
required by each of your library targets via `target_compile_features`. See the
[CMake build 
instructions](https://github.com/abseil/abseil-cpp/blob/master/CMake/README.md) 
for more information. 
 
For a longer answer to this question and to understand why some other approaches 
don't work, see the answer to ["What is ABI and why don't you recommend using a 
pre-compiled version of 
Abseil?"](#what-is-abi-and-why-dont-you-recommend-using-a-pre-compiled-version-of-abseil) 
 
## What is ABI and why don't you recommend using a pre-compiled version of Abseil? 
 
For the purposes of this discussion, you can think of 
[ABI](https://en.wikipedia.org/wiki/Application_binary_interface) as the 
compiled representation of the interfaces in code. This is in contrast to 
[API](https://en.wikipedia.org/wiki/Application_programming_interface), which 
you can think of as the interfaces as defined by the code itself. [Abseil has a 
strong promise of API compatibility, but does not make any promise of ABI 
compatibility](https://abseil.io/about/compatibility). Let's take a look at what 
this means in practice. 
 
You might be tempted to do something like this in a 
[Bazel](https://bazel.build/) `BUILD` file: 
 
``` 
# DON'T DO THIS!!! 
cc_library( 
    name = "my_library", 
    srcs = ["my_library.cc"], 
    copts = ["-std=c++17"],  # May create a mixed-mode compile! 
    deps = ["@com_google_absl//y_absl/strings"], 
) 
``` 
 
Applying `-std=c++17` to an individual target in your `BUILD` file is going to 
compile that specific target in C++17 mode, but it isn't going to ensure the 
Abseil library is built in C++17 mode, since the Abseil library itself is a 
different build target. If your code includes an Abseil header, then your 
program may contain conflicting definitions of the same 
class/function/variable/enum, etc. As a rule, all compile options that affect 
the ABI of a program need to be applied to the entire build on a global basis. 
 
C++ has something called the [One Definition 
Rule](https://en.wikipedia.org/wiki/One_Definition_Rule) (ODR). C++ doesn't 
allow multiple definitions of the same class/function/variable/enum, etc. ODR 
violations sometimes result in linker errors, but linkers do not always catch 
violations. Uncaught ODR violations can result in strange runtime behaviors or 
crashes that can be hard to debug. 
 
If you build the Abseil library and your code using different compile options 
that affect ABI, there is a good chance you will run afoul of the One Definition 
Rule. Examples of GCC compile options that affect ABI include (but aren't 
limited to) language dialect (e.g. `-std=`), optimization level (e.g. `-O2`), 
code generation flags (e.g. `-fexceptions`), and preprocessor defines 
(e.g. `-DNDEBUG`). 
 
If you use a pre-compiled version of Abseil, (for example, from your Linux 
distribution package manager or from something like 
[vcpkg](https://github.com/microsoft/vcpkg)) you have to be very careful to 
ensure ABI compatibility across the components of your program. The only way you 
can be sure your program is going to be correct regarding ABI is to ensure 
you've used the exact same compile options as were used to build the 
pre-compiled library. This does not mean that Abseil cannot work as part of a 
Linux distribution since a knowledgeable binary packager will have ensured that 
all packages have been built with consistent compile options. This is one of the 
reasons we warn against - though do not outright reject - using Abseil as a 
pre-compiled library. 
 
Another possible way that you might afoul of ABI issues is if you accidentally 
include two versions of Abseil in your program. Multiple versions of Abseil can 
end up within the same binary if your program uses the Abseil library and 
another library also transitively depends on Abseil (resulting in what is 
sometimes called the diamond dependency problem). In cases such as this you must 
structure your build so that all libraries use the same version of Abseil. 
[Abseil's strong promise of API compatibility between 
releases](https://abseil.io/about/compatibility) means the latest "HEAD" release 
of Abseil is almost certainly the right choice if you are doing as we recommend 
and building all of your code from source. 
 
For these reasons we recommend you avoid pre-compiled code and build the Abseil 
library yourself in a consistent manner with the rest of your code. 
 
## What is "live at head" and how do I do it? 
 
From Abseil's point-of-view, "live at head" means that every Abseil source 
release (which happens on an almost daily basis) is either API compatible with 
the previous release, or comes with an automated tool that you can run over code 
to make it compatible. In practice, the need to use an automated tool is 
extremely rare. This means that upgrading from one source release to another 
should be a routine practice that can and should be performed often. 
 
We recommend you update to the [latest commit in the `master` branch of 
Abseil](https://github.com/abseil/abseil-cpp/commits/master) as often as 
possible. Not only will you pick up bug fixes more quickly, but if you have good 
automated testing, you will catch and be able to fix any [Hyrum's 
Law](https://www.hyrumslaw.com/) dependency problems on an incremental basis 
instead of being overwhelmed by them and having difficulty isolating them if you 
wait longer between updates. 
 
If you are using the [Bazel](https://bazel.build/) build system and its 
[external dependencies](https://docs.bazel.build/versions/master/external.html) 
feature, updating the 
[`http_archive`](https://docs.bazel.build/versions/master/repo/http.html#http_archive) 
rule in your 
[`WORKSPACE`](https://docs.bazel.build/versions/master/be/workspace.html) for 
`com_google_abseil` to point to the [latest commit in the `master` branch of 
Abseil](https://github.com/abseil/abseil-cpp/commits/master) is all you need to 
do. For example, on February 11, 2020, the latest commit to the master branch 
was `98eb410c93ad059f9bba1bf43f5bb916fc92a5ea`. To update to this commit, you 
would add the following snippet to your `WORKSPACE` file: 
 
``` 
http_archive( 
  name = "com_google_absl", 
  urls = ["https://github.com/abseil/abseil-cpp/archive/98eb410c93ad059f9bba1bf43f5bb916fc92a5ea.zip"],  # 2020-02-11T18:50:53Z 
  strip_prefix = "abseil-cpp-98eb410c93ad059f9bba1bf43f5bb916fc92a5ea", 
  sha256 = "aabf6c57e3834f8dc3873a927f37eaf69975d4b28117fc7427dfb1c661542a87", 
) 
``` 
 
To get the `sha256` of this URL, run `curl -sL --output - 
https://github.com/abseil/abseil-cpp/archive/98eb410c93ad059f9bba1bf43f5bb916fc92a5ea.zip 
| sha256sum -`. 
 
You can commit the updated `WORKSPACE` file to your source control every time 
you update, and if you have good automated testing, you might even consider 
automating this. 
 
One thing we don't recommend is using GitHub's `master.zip` files (for example 
[https://github.com/abseil/abseil-cpp/archive/master.zip](https://github.com/abseil/abseil-cpp/archive/master.zip)), 
which are always the latest commit in the `master` branch, to implement live at 
head. Since these `master.zip` URLs are not versioned, you will lose build 
reproducibility. In addition, some build systems, including Bazel, will simply 
cache this file, which means you won't actually be updating to the latest 
release until your cache is cleared or invalidated.