Folly: Facebook Open-source Library

什么是 folly？

Folly（Facebook 开源库的缩写）是一个 C++17 组件库，设计时注重实用性和效率。

Folly 包含 Facebook 广泛使用的各种核心库组件。特别是，它通常是 Facebook 其他开源 C++ 项目的依赖项，也是这些项目共享代码的地方。

它与 Boost 和 std 等产品相辅相成（而不是相互竞争）。事实上，只有当我们需要的组件不可用或无法满足所需的性能要求时，我们才会着手定义自己的组件。如果 std 或 Boost 淘汰了某些组件，我们会努力将其从 Folly 中删除。

性能问题贯穿了 Folly 的大部分内容，有时会导致设计比原本更独特（例如，参见 PackedSyncPtr.h 和 SmallLocks.h）。大规模下的良好性能是 Folly 的统一主题。

逻辑设计

Folly 是由一些相对独立的组件组成的集合，其中一些组件甚至可能只有几个符号。Folly 对内部依赖关系没有任何限制，这意味着一个特定的 Folly 模块可以使用任何其他Folly 组件。

所有符号均在顶级命名空间folly中定义，当然宏除外。宏名称全部大写，并应以“FOLLY_”作为前缀。命名空间“folly”定义了其他内部命名空间，例如“internal”或“detail”。用户代码不应依赖于这些命名空间中的符号。

物理设计

Folly 的顶层目录采用了 Boost 和其他库使用的经典“stuttering”方案folly/folly。第一个目录用作库的安装根目录（可能带有类似folly-1.0/ 的版本控制），第二个目录用于在包含文件时区分库，例如 #include <folly/FBString.h>。

目录结构是扁平的（模仿命名空间结构），也就是说，我们没有复杂的目录层次结构（未来版本可能会改变）。子目录 experimental包含在 folly 内部使用的文件，也可能在 Facebook 中使用，但被认为不够稳定，无法供客户端使用。您的代码不应使用folly/experimental 中的文件，以免在更新 Folly 时崩溃。

folly/folly/test 子目录包含所有组件的单元测试，通常每个 ComponentXyz.* 的单元测试名为 ComponentXyzTest.cpp。folly/folly/docs 目录包含相关文档。

内容是什么？

由于 folly 的结构相当扁平，查看其内容的最佳方式是查看 顶层 folly/ 目录 中的头文件。您也可以查看 docs 文件夹 中的文档，首先查看overview。

Folly 发布在 GitHub 上，地址为 https://github.com/facebook/folly。

构建说明

由于 folly 不提供任何从提交到提交的 ABI 兼容性保证，因此我们通常建议将 folly 构建为静态库。

folly 支持 gcc (5.1+)、clang 或 MSVC。它可以在 Linux（x86-32、x86-64 和 ARM）、iOS、macOS 和 Windows (x86-64) 上运行。 CMake 构建仅在部分平台上进行过测试；我们的目标是至少支持 macOS 和Linux（在最新的 Ubuntu LTS 版本或更新版本上）。

getdeps.py

此脚本被 Meta 的许多 OSS 工具使用。它会首先下载并构建所有必要的依赖项，然后调用 cmake 等命令来构建 folly。这将有助于确保您使用所有依赖库的相关版本进行构建，并考虑到您系统上本地安装的版本。

它是用 Python 编写的，因此您需要在 PATH 中安装 python3.6 或更高版本。它适用于 Linux、macOS 和 Windows。

folly 的 cmake 构建设置保存在其 getdeps 清单 build/fbcode_builder/manifests/folly 中，您可以根据需要在本地进行编辑。

依赖项

如果您使用的是 Linux 或 MacOS（已安装 Homebrew），您可以安装系统依赖项以节省构建时间：

# Clone the repo
git clone https://github.com/facebook/folly
# Install dependencies
cd folly
sudo ./build/fbcode_builder/getdeps.py install-system-deps --recursive

如果您想在安装之前查看软件包：

./build/fbcode_builder/getdeps.py install-system-deps --dry-run --recursive

在其他平台上，或者在 Linux 上，如果没有系统依赖项，getdeps.py 会在构建步骤中为您下载并构建它们。

getdeps.py 使用和安装的一些依赖项包括：

• 支持 C++14 编译的 boost 版本。
• 构建和运行 folly 的测试需要 googletest。

构建

此脚本将首先下载并构建所有必要的依赖项，然后调用 cmake 等命令来构建 folly。这将帮助您确保使用所有依赖库的相关版本进行构建，并考虑到您系统上本地安装的版本。

getdeps.py 当前要求 Python 3.6 及以上版本位于您的路径中。

getdeps.py 将调用 cmake 等命令。

# Clone the repo
git clone https://github.com/facebook/folly
cd folly
# Build, using system dependencies if available
python3 ./build/fbcode_builder/getdeps.py --allow-system-packages build

它将输出放在其草稿区域中：

• installed/folly/lib/libfolly.a: Library

您还可以指定 --scratch-path 参数来控制用于构建的临时目录的位置。您可以从日志中或使用 python3 ./build/fbcode_builder/getdeps.py show-inst-dir 找到默认的临时安装位置。

此外，还有 --install-dir 和 --install-prefix 参数，可以对安装目录进行更精细的控制。但是，鉴于folly 不提供提交之间的兼容性保证，我们通常建议将库构建和安装到一个临时位置，然后将项目的构建指向这个临时位置，而不是将 folly 安装在传统的系统安装目录中。例如，如果您使用 CMake 构建，则可以使用 CMAKE_PREFIX_PATH 变量，让 CMake 在构建项目时在此临时安装目录中找到 folly。

如果您想再次调用“cmake”进行迭代，临时构建目录中有一个有用的“run_cmake.py”脚本输出。您可以从日志中或使用“python3 ./build/fbcode_builder/getdeps.py show-build-dir”找到临时构建目录。

运行测试

默认情况下，getdeps.py 将为 folly 构建测试。要运行它们，请执行以下操作：

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

build.sh/build.bat 包装器

build.sh 可在 Linux 和 MacOS 上使用，在 Windows 上，请使用
build.bat 脚本。它是 getdeps.py 的包装器。

直接使用 CMake 构建

如果您不想让 getdeps 为您调用 CMake，那么默认情况下，构建测试在 CMake 的 all 目标中是禁用的。要构建测试，请在配置时为 CMake 指定 -DBUILD_TESTS=ON。

注意：如果您想再次调用 cmake 来迭代 getdeps.py 构建，scratch-path 构建目录中有一个很有用的 run_cmake.py 脚本输出。您可以从日志中或使用 python3 ./build/fbcode_builder/getdeps.py show-build-dir 找到临时构建目录。

如果您使用 cd 命令切换到构建目录，也可以使用 ctests 运行测试，例如：
(cd $(python3 ./build/fbcode_builder/getdeps.py show-build-dir) && ctest)

在非默认位置查找依赖项

如果您在非默认位置安装了 boost、gtest 或其他依赖项，您可以使用 CMAKE_INCLUDE_PATH 和 CMAKE_LIBRARY_PATH变量，使 CMAKE 查找非标准位置的头文件和库。例如，如果还要在目录 /alt/include/path1 和 /alt/include/path2 中搜索头文件，并在目录 /alt/lib/path1 和 /alt/lib/path2 中搜索库，则可以按如下方式调用 cmake：

cmake \
  -DCMAKE_INCLUDE_PATH=/alt/include/path1:/alt/include/path2 \
  -DCMAKE_LIBRARY_PATH=/alt/lib/path1:/alt/lib/path2 ...

Ubuntu LTS、CentOS Stream、Fedora

使用上述 getdeps.py 方法。我们在 Ubuntu LTS 上进行持续集成测试，偶尔也会在其他发行版上进行测试。

如果您发现系统软件包集与您选择的发行版不太匹配，您可以在依赖项清单中指定特定于发行版的覆盖（例如 https://github.com/facebook/folly/blob/main/build/fbcode_builder/manifests/boost ）。您或许可以在最新的 Ubuntu/Debian 或 Fedora/Redhat 衍生发行版上运行它。

在撰写本文时（2021 年 12 月），lang_badge_test 中基于 GCC 11.x 的系统存在构建中断。如果您不需要徽章功能，可以通过在 CMakeLists.txt 中将其注释掉来解决这个问题（可惜 fbthrift 需要它）。

Windows (Vcpkg)

请注意，许多测试在 folly Windows 构建中被禁用，您可以在 cmake configure 步骤的日志中查看，或者在 CMakeLists.txt 中查找 WINDOWS_DISABLED。

不过，getdeps.py 构建可以在 Windows 上运行，并且在 CI 中进行了测试。

如果您愿意，可以尝试 Vcpkg。folly 在 Vcpkg 中可用，可以通过 vcpkg install folly:x64-windows 构建发布版本。

您也可以使用 vcpkg install folly:x64-windows --head 来针对 main 进行构建。

macOS

getdeps.py 可以在 macOS 上构建，并在 CI 中测试过。不过，如果您愿意，也可以尝试使用其他 macOS 包管理器。

Homebrew

folly 可以作为 Formula 使用，可以通过 brew install folly 构建发行版。

您也可以使用 folly/build/bootstrap-osx-homebrew.sh 来构建 main 版本：

  ./folly/build/bootstrap-osx-homebrew.sh

这将在顶层创建一个构建目录_build。

MacPorts

从 MacPorts 安装所需的软件包：

  sudo port install \
    boost \
    cmake \
    gflags \
    git \
    google-glog \
    libevent \
    libtool \
    lz4 \
    lzma \
    openssl \
    snappy \
    xz \
    zlib

下载并安装双转换：

  git clone https://github.com/google/double-conversion.git
  cd double-conversion
  cmake -DBUILD_SHARED_LIBS=ON .
  make
  sudo make install

使用下面列出的参数下载并安装 folly：

  git clone https://github.com/facebook/folly.git
  cd folly
  mkdir _build
  cd _build
  cmake ..
  make
  sudo make install