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