folly

Folly: Foundational Open-source Library What is folly? Folly (originally an acronym for Facebook Open-source Library) is a library of C++20 components designed with practicality and efficiency in mind. Folly contains a variety of core library components used extensively at Meta. In particular, it's often a dependency of Meta's other open source C++ efforts and place where those projects can share code. It builds on std and fills its gaps. We add a component when std doesn't provide it, or doesn't meet the performance, scalability or interface Meta's code needs. When std provides an equivalent, we move folly and its users to the standard one and keep the folly name only as long as users need it. Performance concerns permeate much of Folly, sometimes leading to designs that are more idiosyncratic than they would otherwise be (see e.g. PackedSyncPtr.h, SmallLocks.h). Good performance at large scale is a unifying theme in all of Folly. Check it out in the intro video Logical Design Folly is a collection of relatively independent components, some as simple as a few symbols. There is no restriction on internal dependencies, meaning that a given folly module may use any other folly components. All symbols are defined in the top-level namespace folly, except of course macros. Macro names are ALL_UPPERCASE and should be prefixed with FOLLY_. Namespace folly defines other internal namespaces such as internal or detail. User code should not depend on symbols in those namespaces. Physical Design The sources live in the folly/ directory, so headers are included with the library name as a prefix, e.g. #include <folly/FBString.h>. The directory structure is flat (mimicking the namespace structure), i.e. we don't have an elaborate directory hierarchy (it is possible this will change in future versions). The subdirectory experimental contains files that are used inside folly and possibly at Meta but not considered stable enough for client use. Your code should not use files in folly/experimental lest it may break when you update Folly. The folly/test subdirectory includes the unittests for all components, usually named ComponentXyzTest.cpp for each ComponentXyz.*. The folly/docs directory contains documentation. What's in it? Because of folly's fairly flat structure, the best way to see what's in it is to look at the headers in top level folly/ directory. You can also check the docs folder for documentation, starting with the overview. Folly is published on GitHub at https://github.com/meta/folly. Build Notes Because folly does not provide any ABI compatibility guarantees from commit to commit, we generally recommend building folly as a static library. folly supports gcc, clang, or MSVC with C++20 support. It should run on Linux (x86-32, x86-64, and ARM), iOS, macOS, and Windows (x86-64). The CMake build is only tested on some of these platforms; at a minimum, we aim to support macOS and Linux (on the latest Ubuntu LTS release or newer.) Build with CMake The CMake build fetches any dependency it cannot find installed, so a clone and two commands are enough: git clone https://github.com/meta/folly cd folly cmake -B _build cmake --build _build Anything already on the system is used as-is. Alternatively, install the system packages first: sudo build/fbcode_builder/getdeps.py install-system-deps --recursive Tests are not part of the all target. Configure with -DBUILD_TESTS=ON to build them, which also fetches googletest and gflags if they are not installed (the library itself uses gflags only if it is installed): cmake -B _build -DBUILD_TESTS=ON cmake --build _build (cd _build && ctest) Whether folly uses gflags is decided when folly is built and recorded in the installed folly/folly-config.h; linking gflags into a program later does not turn it on. Without gflags, folly::Init does not parse command-line flags, folly::gflags::FlagSaver and folly::gflags::SetCommandLineOption do nothing, and the cli libraries are not built. Declare folly's flags with the FOLLY_GFLAGS_DECLARE_* macros from folly/portability/GFlags.h, not with gflags' DECLARE_*, which would not match how folly defined them: without gflags, for example, a string flag is a std::string rather than a reference. cmake --install needs CMake 3.28 or newer once anything has been fetched, because fetched dependencies are deliberately left out of what folly installs. An installed folly expects its dependencies on the consumer's system instead; folly-config.cmake looks them up with find_package. getdeps.py getdeps.py also builds folly's sibling projects. Prefer the CMake build above unless you need that. This script is used by many of Meta's OSS tools. It will download and build all of the necessary dependencies first, and will then invoke cmake etc to build folly. This will help ensure that you build with relevant versions of all of the dependent libraries, taking into account what versions are installed locally on your system. It's written in python so you'll need python3.6 or later on your PATH. It works on Linux, macOS and Windows. The settings for folly's cmake build are held in its getdeps manifest build/fbcode_builder/manifests/folly, which you can edit locally if desired. Dependencies If on Linux or MacOS (with homebrew installed) you can install system dependencies to save building them: # Clone the repo git clone https://github.com/meta/folly # Install dependencies cd folly sudo build/fbcode_builder/getdeps.py install-system-deps --recursive If you'd like to see the packages before installing them: build/fbcode_builder/getdeps.py install-system-deps --dry-run --recursive On other platforms or if on Linux and without system dependencies getdeps.py will mostly download and build them for you during the build step. Some of the dependencies getdeps.py uses and installs are: boost. googletest is required to build and run folly's tests. Build # Clone the repo git clone https://github.com/meta/folly cd folly # Build, using system depende