facebook/folly: what the C++ library is, and how to build it

The gap folly fills for Meta's C++ code

Folly is not a general-purpose replacement for the standard library. The README describes it as a set of C++20 components written "with practicality and efficiency in mind," and says it complements Boost and std rather than competing with them. A new component is added only when something the authors need is missing or does not meet the required performance profile, and components are meant to be removed if std or Boost makes them redundant. That is an unusual stance for a library of this size, and it explains why the API surface looks uneven: some parts are thin wrappers, others are deliberately idiosyncratic because of performance work.

The intended audience is narrow. Folly is the shared dependency layer for Meta's other open source C++ work, so the primary consumer is a project that already lives in that ecosystem. If you are writing an application that has nothing to do with that stack, you are reading someone else's internal toolkit. The README is direct about the consequence: performance concerns shape the design, citing PackedSyncPtr.h and SmallLocks.h as examples where the result is more idiosyncratic than it would otherwise be. That trade is deliberate. A component like a packed pointer with synchronization metadata baked into the same word exists because the ordinary layout costs a cache line, and the library accepts a stranger API to avoid paying it.

How the library is organized, and why that matters for linking

The layout follows the Boost-style stuttering scheme: a top-level folly directory acts as the install root, and a nested folly directory is what appears in includes, so you write #include <folly/FBString.h>. The directory structure is flat and mirrors the namespace, which means there is no deep hierarchy to learn, but it also means the top-level header listing is the real table of contents. The README says the best way to see what is in the library is to look at the headers in the top-level folly directory, with additional documentation under folly/docs.

Two structural rules matter more than the rest. First, all symbols live in the top-level namespace folly, except macros, which are ALL_UPPERCASE and prefixed with FOLLY_. Namespaces such as internal and detail exist but user code is told not to depend on them. Second, there is no restriction on internal dependencies: any folly module may use any other folly component. That is convenient inside the project and painful outside it, because pulling in one header can drag in a chain of others, and the README offers no dependency map. The other boundary to respect is folly/experimental, which the README says is used inside folly and possibly at Meta but is not stable enough for client use, and warns that code depending on it may break on update.

Installing folly with getdeps.py

There is no package manager step here. The README points to build/fbcode_builder/getdeps.py, a Python script used by many of Meta's open source tools, which downloads and builds dependencies first and then invokes cmake. It needs python3.6 or later on PATH and works on Linux, macOS and Windows. On Linux or macOS with Homebrew, you can install system dependencies instead of building them, after cloning the repository.

git clone https://github.com/facebook/folly
cd folly
sudo ./build/fbcode_builder/getdeps.py install-system-deps --recursive

The README also shows a dry run that lists the packages before anything is installed: ./build/fbcode_builder/getdeps.py install-system-deps --dry-run --recursive. On other platforms, or on Linux without system dependencies, getdeps.py downloads and builds them during the build step. Among the dependencies it handles are a version of boost compiled with C++14 support, and googletest, which is required to build and run the tests. The cmake settings for folly's own build live in the getdeps manifest at build/fbcode_builder/manifests/folly, which the README says you can edit locally if you need to change them.

Building, testing and pointing your project at the result

The build command is a single invocation of the same script. Passing --allow-system-packages lets it use what is already installed.

python3 ./build/fbcode_builder/getdeps.py --allow-system-packages build

The README states the output lands in the scratch area as installed/folly/lib/libfolly.a. You can relocate the scratch directory with --scratch-path, and getdeps.py show-inst-dir prints the default install location. There are also --install-dir and --install-prefix arguments. The README's recommendation is to build into a temporary location and point your project's build at it rather than installing into system directories, for example by setting CMAKE_PREFIX_PATH so CMake can find folly there. If you need to re-run cmake while iterating, a run_cmake.py script is written into the scratch build directory, which getdeps.py show-build-dir will print. Tests are built by default; running them is another subcommand of the same script.

cd folly
python3 ./build/fbcode_builder/getdeps.py --allow-system-packages test

The README also lists build.sh and build.bat at the repository root, without describing what they do beyond that. The unittests live in folly/folly/test, usually named ComponentXyzTest.cpp for each ComponentXyz.*, so the test target is also the fastest way to see a component used correctly.

The ABI commitment you are not getting

The README states plainly that folly provides no ABI compatibility guarantees from commit to commit, and recommends building it as a static library. That single sentence should decide most adoption questions. A shared library built from one release tag and linked against a binary compiled from another is not a supported configuration, and the release cadence (v2026.09.07.00, v2026.08.31.00, v2026.08.24.00, roughly weekly) means "another commit" arrives quickly. Treat folly as source you compile, pin to a tag, and rebuild with your own code.

The second limitation is the experimental directory. It is inside the installed tree and included by the build, but the README says client code should not use it because it may break on update. Any evaluation that greps the repository for a convenient header should check whether that header sits under folly/experimental before assuming it is usable. The third is the platform matrix: gcc 5.1+, clang or MSVC, running on Linux (x86-32, x86-64, ARM), iOS, macOS and Windows x86-64, with the CMake build tested on only some of those, aiming at a minimum for macOS and Linux on the latest Ubuntu LTS or newer. If you are on an older distribution or an unusual target, you are outside the stated support envelope.

There is a fourth cost that the README implies rather than states. Because there is no restriction on internal dependencies between folly modules, the static archive you link is larger than the set of components you named, and the linker may need to resolve symbols from modules you never included. That is the price of the flat, interdependent layout, and it is worth measuring against your binary size budget before you commit.

Where folly is the wrong tool, and what to use instead

If your need is a portable, ABI-stable set of general C++ utilities with a long support horizon, Boost is the natural comparison and the README frames folly as complementing it rather than replacing it. The difference in approach is governance and scope: Boost maintains a reviewed, versioned collection with documented compatibility expectations, while folly is an internal toolkit published as-is, adding a component only when Meta needs something std or Boost does not provide, and removing it when that changes. The practical consequence is that a folly component may disappear or shift, which is exactly the trade Boost is designed to avoid. If your project cannot absorb a recompile of its dependency graph on someone else's schedule, Boost's model fits better even when folly's component is faster.

A second case is the one the README itself creates: if you only need a handful of small utilities, pulling in folly means pulling in its dependency chain, including boost and googletest for the test build, plus a cmake-driven build script. For a project that wants a single header-only helper, that is a poor trade. Folly is also the wrong choice if your team cannot rebuild dependencies on its own schedule, since the no-ABI-guarantee rule turns every folly update into a recompile of everything that links it.

Maintenance, releases and what the licence permits

The repository is not archived, and the last push was on 2026-09-10, with tagged releases appearing about weekly through August and September 2026. That is a fast-moving release train, and it is worth reading the cadence together with the ABI statement: frequent tags plus no cross-commit compatibility means the safe pattern is to pin one tag, vendor the source, and upgrade deliberately rather than tracking main. The repository also carries Buck build files (BUCK, .buckconfig, CMakeListsForBuck2.txt) alongside the CMake setup, which tells you the build system Meta itself uses is not the one the README walks you through.

Folly is licensed under Apache-2.0. That is a permissive licence, and the repository carries LICENSE, CONTRIBUTING.md and CODE_OF_CONDUCT.md at the top level, so the usual obligations apply: keep the licence and notices with redistributed source or binaries, and check the terms yourself rather than relying on a summary. Note that the dependency set is not covered by folly's licence, so a build that pulls in boost and googletest brings their terms along with it. This is a description of what the repository states, not legal advice.

What to check before you commit to folly

Start from the headers. The README says the top-level folly directory is the best index of what the library contains, so read that listing against your actual needs before reading anything else, and confirm that the components you want are not under folly/experimental. Then confirm the build works on your platform with your compiler, since the CMake build is tested on only part of the stated platform list. Finally, decide your pinning strategy: pick a release tag such as v2026.09.07.00, build it to a scratch path, and wire CMAKE_PREFIX_PATH to that path rather than installing into system directories, which is what the README recommends and what the lack of ABI guarantees makes sensible. If you need to know how a component is meant to be used, the matching ComponentXyzTest.cpp under folly/folly/test is the closest thing to a usage example the repository ships.

Editorial conclusion

Adopt folly if you are already building Meta's C++ stack or need components like FBString and the synchronization primitives the README singles out, and you can pin a release tag such as v2026.09.07.00 and rebuild it yourself. Do not adopt it if you need a stable ABI across upgrades, a distribution package, or a documented support window; the README states there are no compatibility guarantees from commit to commit and recommends a temporary install prefix instead of system directories. Before committing, verify that your compiler and platform are covered (gcc 5.1+, clang, or MSVC, with CMake tested at a minimum on macOS and Linux), check that the headers you need are outside folly/experimental, and confirm your build can consume a static libfolly.a from a scratch path via CMAKE_PREFIX_PATH.

Frequently asked questions

Official sources

1. facebook/folly on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases