FAQ.md - external/github.com/abseil/abseil-cpp - Git at Google


            
            # 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//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.
	# 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//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.