xref: /folly/
Name Date Size

..27-Apr.-20224 KiB

.github/workflows/H11-Oct.-20214 KiB

.gitignoreH A D11-Oct.-2021556

.projectidH A D11-Oct.-20216

.travis.ymlH A D11-Oct.-20211.8 KiB

build/fbcode_builder/H11-Oct.-20214 KiB

build.batH A D11-Oct.-2021987

build.shH A D11-Oct.-20211.1 KiB

CMake/H11-Oct.-20214 KiB

CMakeLists.txtH A D11-Oct.-202136.5 KiB

CODE_OF_CONDUCT.mdH A D11-Oct.-20213.3 KiB

CONTRIBUTING.mdH A D11-Oct.-20211.3 KiB

folly/H19-Oct.-20214 KiB

LICENSEH A D11-Oct.-202111.1 KiB

README.mdH A D11-Oct.-20219.3 KiB

static/H11-Oct.-20214 KiB

README.md

1Folly: Facebook Open-source Library
2-----------------------------------
3
4### What is `folly`?
5
6<img src="static/logo.svg" alt="Logo Folly" width="15%" align="right" />
7
8Folly (acronymed loosely after Facebook Open Source Library) is a
9library of C++14 components designed with practicality and efficiency
10in mind. **Folly contains a variety of core library components used extensively
11at Facebook**. In particular, it's often a dependency of Facebook's other
12open source C++ efforts and place where those projects can share code.
13
14It complements (as opposed to competing against) offerings
15such as Boost and of course `std`. In fact, we embark on defining our
16own component only when something we need is either not available, or
17does not meet the needed performance profile. We endeavor to remove
18things from folly if or when `std` or Boost obsoletes them.
19
20Performance concerns permeate much of Folly, sometimes leading to
21designs that are more idiosyncratic than they would otherwise be (see
22e.g. `PackedSyncPtr.h`, `SmallLocks.h`). Good performance at large
23scale is a unifying theme in all of Folly.
24
25### Logical Design
26
27Folly is a collection of relatively independent components, some as
28simple as a few symbols. There is no restriction on internal
29dependencies, meaning that a given folly module may use any other
30folly components.
31
32All symbols are defined in the top-level namespace `folly`, except of
33course macros. Macro names are ALL_UPPERCASE and should be prefixed
34with `FOLLY_`. Namespace `folly` defines other internal namespaces
35such as `internal` or `detail`. User code should not depend on symbols
36in those namespaces.
37
38Folly has an `experimental` directory as well. This designation connotes
39primarily that we feel the API may change heavily over time. This code,
40typically, is still in heavy use and is well tested.
41
42### Physical Design
43
44At the top level Folly uses the classic "stuttering" scheme
45`folly/folly` used by Boost and others. The first directory serves as
46an installation root of the library (with possible versioning a la
47`folly-1.0/`), and the second is to distinguish the library when
48including files, e.g. `#include <folly/FBString.h>`.
49
50The directory structure is flat (mimicking the namespace structure),
51i.e. we don't have an elaborate directory hierarchy (it is possible
52this will change in future versions). The subdirectory `experimental`
53contains files that are used inside folly and possibly at Facebook but
54not considered stable enough for client use. Your code should not use
55files in `folly/experimental` lest it may break when you update Folly.
56
57The `folly/folly/test` subdirectory includes the unittests for all
58components, usually named `ComponentXyzTest.cpp` for each
59`ComponentXyz.*`. The `folly/folly/docs` directory contains
60documentation.
61
62### What's in it?
63
64Because of folly's fairly flat structure, the best way to see what's in it
65is to look at the headers in [top level `folly/` directory](https://github.com/facebook/folly/tree/master/folly). You can also
66check the [`docs` folder](folly/docs) for documentation, starting with the
67[overview](folly/docs/Overview.md).
68
69Folly is published on GitHub at https://github.com/facebook/folly
70
71### Build Notes
72
73Because folly does not provide any ABI compatibility guarantees from commit to
74commit, we generally recommend building folly as a static library.
75
76#### build.sh
77
78The simplest way to build folly is using the `build.sh` script in the top-level
79of the repository.  `build.sh` can be used on Linux and MacOS, on Windows use
80the `build.bat` script instead.
81
82This script will download and build all of the necessary dependencies first,
83and will then build folly.  This will help ensure that you build with recent
84versions of all of the dependent libraries, regardless of what versions are
85installed locally on your system.
86
87By default this script will build and install folly and its dependencies in a
88scratch directory.  You can also specify a `--scratch-path` argument to control
89the location of the scratch directory used for the build.  There are also
90`--install-dir` and `--install-prefix` arguments to provide some more
91fine-grained control of the installation directories.  However, given that
92folly provides no compatibility guarantees between commits we generally
93recommend building and installing the libraries to a temporary location, and
94then pointing your project's build at this temporary location, rather than
95installing folly in the traditional system installation directories.  e.g., if
96you are building with CMake you can use the `CMAKE_PREFIX_PATH` variable to
97allow CMake to find folly in this temporary installation directory when
98building your project.
99
100#### Dependencies
101
102folly supports gcc (5.1+), clang, or MSVC. It should run on Linux (x86-32,
103x86-64, and ARM), iOS, macOS, and Windows (x86-64). The CMake build is only
104tested on some of these platforms; at a minimum, we aim to support macOS and
105Linux (on the latest Ubuntu LTS release or newer.)
106
107folly requires a version of boost compiled with C++14 support.
108
109googletest is required to build and run folly's tests.  You can download
110it from https://github.com/google/googletest/archive/release-1.8.0.tar.gz
111The following commands can be used to download and install it:
112
113```
114wget https://github.com/google/googletest/archive/release-1.8.0.tar.gz && \
115tar zxf release-1.8.0.tar.gz && \
116rm -f release-1.8.0.tar.gz && \
117cd googletest-release-1.8.0 && \
118cmake . && \
119make && \
120make install
121```
122
123#### Finding dependencies in non-default locations
124
125If you have boost, gtest, or other dependencies installed in a non-default
126location, you can use the `CMAKE_INCLUDE_PATH` and `CMAKE_LIBRARY_PATH`
127variables to make CMAKE look also look for header files and libraries in
128non-standard locations.  For example, to also search the directories
129`/alt/include/path1` and `/alt/include/path2` for header files and the
130directories `/alt/lib/path1` and `/alt/lib/path2` for libraries, you can invoke
131`cmake` as follows:
132
133```
134cmake \
135  -DCMAKE_INCLUDE_PATH=/alt/include/path1:/alt/include/path2 \
136  -DCMAKE_LIBRARY_PATH=/alt/lib/path1:/alt/lib/path2 ...
137```
138
139#### Building tests
140
141By default, building the tests is disabled as part of the CMake `all` target.
142To build the tests, specify `-DBUILD_TESTS=ON` to CMake at configure time.
143
144#### Ubuntu 16.04 LTS
145
146The following packages are required (feel free to cut and paste the apt-get
147command below):
148
149```
150sudo apt-get install \
151    g++ \
152    cmake \
153    libboost-all-dev \
154    libevent-dev \
155    libdouble-conversion-dev \
156    libgoogle-glog-dev \
157    libgflags-dev \
158    libiberty-dev \
159    liblz4-dev \
160    liblzma-dev \
161    libsnappy-dev \
162    make \
163    zlib1g-dev \
164    binutils-dev \
165    libjemalloc-dev \
166    libssl-dev \
167    pkg-config \
168    libunwind-dev
169```
170
171Folly relies on [fmt](https://github.com/fmtlib/fmt) which needs to be installed from source.
172The following commands will download, compile, and install fmt.
173
174```
175git clone https://github.com/fmtlib/fmt.git && cd fmt
176
177mkdir _build && cd _build
178cmake ..
179
180make -j$(nproc)
181sudo make install
182```
183
184If advanced debugging functionality is required, use:
185
186```
187sudo apt-get install \
188    libunwind8-dev \
189    libelf-dev \
190    libdwarf-dev
191```
192
193In the folly directory (e.g. the checkout root or the archive unpack root), run:
194```
195  mkdir _build && cd _build
196  cmake ..
197  make -j $(nproc)
198  make install # with either sudo or DESTDIR as necessary
199```
200
201#### OS X (Homebrew)
202
203folly is available as a Formula and releases may be built via `brew install folly`.
204
205You may also use `folly/build/bootstrap-osx-homebrew.sh` to build against `master`:
206
207```
208  ./folly/build/bootstrap-osx-homebrew.sh
209```
210
211This will create a build directory `_build` in the top-level.
212
213#### OS X (MacPorts)
214
215Install the required packages from MacPorts:
216
217```
218  sudo port install \
219    boost \
220    cmake \
221    gflags \
222    git \
223    google-glog \
224    libevent \
225    libtool \
226    lz4 \
227    lzma \
228    openssl \
229    snappy \
230    xz \
231    zlib
232```
233
234Download and install double-conversion:
235
236```
237  git clone https://github.com/google/double-conversion.git
238  cd double-conversion
239  cmake -DBUILD_SHARED_LIBS=ON .
240  make
241  sudo make install
242```
243
244Download and install folly with the parameters listed below:
245
246```
247  git clone https://github.com/facebook/folly.git
248  cd folly
249  mkdir _build
250  cd _build
251  cmake ..
252  make
253  sudo make install
254```
255
256#### Windows (Vcpkg)
257
258folly is available in [Vcpkg](https://github.com/Microsoft/vcpkg#vcpkg) and releases may be built via `vcpkg install folly:x64-windows`.
259
260You may also use `vcpkg install folly:x64-windows --head` to build against `master`.
261
262#### Other Linux distributions
263
264- double-conversion (https://github.com/google/double-conversion)
265
266  Download and build double-conversion.
267  You may need to tell cmake where to find it.
268
269  [double-conversion/] `ln -s src double-conversion`
270
271  [folly/] `mkdir build && cd build`
272  [folly/build/] `cmake "-DCMAKE_INCLUDE_PATH=$DOUBLE_CONVERSION_HOME/include" "-DCMAKE_LIBRARY_PATH=$DOUBLE_CONVERSION_HOME/lib" ..`
273
274  [folly/build/] `make`
275
276- additional platform specific dependencies:
277
278  Fedora >= 21 64-bit (last tested on Fedora 28 64-bit)
279    - gcc
280    - gcc-c++
281    - cmake
282    - automake
283    - boost-devel
284    - libtool
285    - lz4-devel
286    - lzma-devel
287    - snappy-devel
288    - zlib-devel
289    - glog-devel
290    - gflags-devel
291    - scons
292    - double-conversion-devel
293    - openssl-devel
294    - libevent-devel
295    - fmt-devel
296    - libsodium-devel
297
298  Optional
299    - libdwarf-devel
300    - elfutils-libelf-devel
301    - libunwind-devel
302