about summary refs log tree commit diff
path: root/FAQ.md
diff options
context:
space:
mode:
authorAbseil Team <absl-team@google.com>2020-02-13T14·52-0800
committerMark Barolak <mbar@google.com>2020-02-13T18·56-0500
commitc44657f55692eddf5504156645d1f4ec7b3acabd (patch)
tree3a0da3d468193fd9c3b5485777da30f64f06f93e /FAQ.md
parent98eb410c93ad059f9bba1bf43f5bb916fc92a5ea (diff)
Export of internal Abseil changes
--
dc6d2715f0415082fcc8da8bf74e74bce69b236c by Derek Mauro <dmauro@google.com>:

Correctly detect C++ exceptions support on Clang for Windows

PiperOrigin-RevId: 294905116

--
b43c44501b4820f4a2f396e426619bd02565707e by Derek Mauro <dmauro@google.com>:

Set CMAKE_CXX_STANDARD on the MacOS CMake build

PiperOrigin-RevId: 294730418

--
184a078649167f9738da60b0f12108256bcfd67b by Abseil Team <absl-team@google.com>:

No need for custom spec to deal with limited platforms.

PiperOrigin-RevId: 294700133

--
b437c7f659b809fc84a45eab284265fec497a3e3 by Abseil Team <absl-team@google.com>:

Not calling sigaltstack on WatchOS and TVOS since they don't allow it.

PiperOrigin-RevId: 294699951

--
23ab8dd381ee4104125dece8455bc96b81239789 by Gennadiy Rozental <rogeeff@google.com>:

Replace use of atomic+global Mutex+bool with absl::call_once for Flag initialization.

This simplifies the initialization logic and helps with upcoming work with value storage rework.

PiperOrigin-RevId: 294654938

--
cee576163a2753c6138bc254e81de4800ea3307a by Gennadiy Rozental <rogeeff@google.com>:

Separate const bits from mutable bits.

Since bit field is not atomic unit for reading/writing, we can't have constant bits which are not protected by data guard to share the space with mutable bits which are protected.

This CL just reorder fields in class and does not make any other changes.

PiperOrigin-RevId: 294501780

--
b4d0e2ab559d04f655c93f008594562234773c15 by Abseil Team <absl-team@google.com>:

Correct the comment.

PiperOrigin-RevId: 294499328

--
a788cf71af6247df033298c49939ba0414d71693 by Derek Mauro <dmauro@google.com>:

Move the FAQ to the top level directory

PiperOrigin-RevId: 294493863
GitOrigin-RevId: dc6d2715f0415082fcc8da8bf74e74bce69b236c
Change-Id: I71b0d8cd401b48d41433417858ae0d69398b6602
Diffstat (limited to 'FAQ.md')
-rw-r--r--FAQ.md144
1 files changed, 144 insertions, 0 deletions
diff --git a/FAQ.md b/FAQ.md
new file mode 100644
index 000000000000..af721307c2ec
--- /dev/null
+++ b/FAQ.md
@@ -0,0 +1,144 @@
+# 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. 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 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 release of Abseil 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 release is all you need to do. 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.