X-Git-Url: http://plrg.eecs.uci.edu/git/?p=folly.git;a=blobdiff_plain;f=README.md;h=4fc27ae242bfa8e1d37c94a841646a6c2b641d54;hp=a5f3e2f03f3d3361e3d2215893e97270e0a4dc5e;hb=a123a11e30026dd9883f16fa3ad1baa2d9ecfeec;hpb=0887b7ac672970bf401d58cb0bb828afb2df3854 diff --git a/README.md b/README.md index a5f3e2f0..4fc27ae2 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,108 @@ -Folly: Facebook Open-source LibrarY +Folly: Facebook Open-source Library ----------------------------------- -Folly is an open-source C++ library developed and used at Facebook. +### What is `folly`? -###[Get Started](folly/docs/Overview.md) +Folly (acronymed loosely after Facebook Open Source Library) is a +library of C++11 components designed with practicality and efficiency +in mind. **Folly contains a variety of core library components used extensively +at Facebook**. In particular, it's often a dependency of Facebook's other +open source C++ efforts and place where those projects can share code. -Folly is published on Github at https://github.com/facebook/folly; for -discussions, there is a Google group at -https://groups.google.com/d/forum/facebook-folly. +It complements (as opposed to competing against) offerings +such as Boost and of course `std`. In fact, we embark on defining our +own component only when something we need is either not available, or +does not meet the needed performance profile. We endeavor to remove +things from folly if or when `std` or Boost obsoletes them. -Dependencies ------------- +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. -folly requires gcc 4.8+ and a version of boost compiled with C++11 support. +### 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. + +Folly has an `experimental` directory as well. This designation connotes +primarily that we feel the API may change heavily over time. This code, +typically, is still in heavy use and is well tested. + +### Physical Design + +At the top level Folly uses the classic "stuttering" scheme +`folly/folly` used by Boost and others. The first directory serves as +an installation root of the library (with possible versioning a la +`folly-1.0/`), and the second is to distinguish the library when +including files, e.g. `#include `. + +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 Facebook 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/folly/test` subdirectory includes the unittests for all +components, usually named `ComponentXyzTest.cpp` for each +`ComponentXyz.*`. The `folly/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](https://github.com/facebook/folly/tree/master/folly). You can also +check the [`docs` folder](folly/docs) for documentation, starting with the +[overview](folly/docs/Overview.md). + +Folly is published on Github at https://github.com/facebook/folly + +### Build Notes + +#### Dependencies + +folly requires gcc 4.9+ and a version of boost compiled with C++14 support. Please download googletest from -https://googletest.googlecode.com/files/gtest-1.7.0.zip and unzip it in the -folly/test subdirectory. +https://github.com/google/googletest/archive/release-1.8.0.tar.gz and unpack it into the +folly/test subdirectory as `gtest`: + + (cd folly/test && \ + rm -rf gtest && \ + wget https://github.com/google/googletest/archive/release-1.8.0.tar.gz && \ + tar zxf release-1.8.0.tar.gz && \ + rm -f release-1.8.0.tar.gz && \ + mv googletest-release-1.8.0 gtest) -Ubuntu 13.10 ------------- +#### Linking non-default boost libraries + +If you have boost installed in a non-default location, you need to be sure that +the linker and configure scripts know where to find boost. This means making +sure that the `LIBRARY_PATH` environment variable contains `/lib`, +as well as including the path explicitly when running +`./configure`: + +``` +export LIBRARY_PATH=$BOOST_ROOT/lib:$LIBRARY_PATH +./configure --with-boost=$BOOST_ROOT/lib +``` + +#### Ubuntu 12.04 + +This release is old, requiring many upgrades. However, since Travis CI runs +on 12.04, `folly/build/deps_ubuntu_12.04.sh` is provided, and upgrades all +the required packages. + +#### Ubuntu 13.10 The following packages are required (feel free to cut and paste the apt-get command below): @@ -43,11 +126,20 @@ sudo apt-get install \ zlib1g-dev \ binutils-dev \ libjemalloc-dev \ - libssl-dev + libssl-dev \ + pkg-config ``` -Ubuntu 14.04 LTS ----------------- +If advanced debugging functionality is required + +``` +sudo apt-get install \ + libunwind8-dev \ + libelf-dev \ + libdwarf-dev +``` + +#### Ubuntu 14.04 LTS The packages listed above for Ubuntu 13.10 are required, as well as: @@ -58,7 +150,7 @@ sudo apt-get install \ The above packages are sufficient for Ubuntu 13.10 and Ubuntu 14.04. -In the folly directory, run +In the folly directory, run: ``` autoreconf -ivf ./configure @@ -67,37 +159,85 @@ In the folly directory, run sudo make install ``` -OS X ----- -There is a bootstrap script if you use Homebrew (http://brew.sh/). At the time -of writing (OS X Yosemite 10.10.1) the default compiler (clang) has some -issues building, but gcc 4.9.2 from Homebrew works fine. (This is taken care -of by the bootstrap script.) +#### Ubuntu 16.04 LTS +The packages listed above for 13.10 and 14.04 are sufficient for installation, +and the build commands remain the same. + +#### OS X (Homebrew) + +folly is available as a Formula and releases may be built via `brew install folly`. + +You may also use `folly/build/bootstrap-osx-homebrew.sh` to build against `master`: ``` cd folly - ./bootstrap-osx-homebrew.sh + ./build/bootstrap-osx-homebrew.sh +``` + +#### OS X (MacPorts) + +Install the required packages from MacPorts: + +``` + sudo port install \ + autoconf \ + automake \ + boost \ + gflags \ + git \ + google-glog \ + libevent \ + libtool \ + lz4 \ + lzma \ + scons \ + snappy \ + zlib +``` + +Download and install double-conversion: + +``` + git clone https://github.com/google/double-conversion.git + cd double-conversion + cmake -DBUILD_SHARED_LIBS=ON . make - make check + sudo make install ``` -Other Linux distributions -------------------------- +Download and install folly with the parameters listed below: -- double-conversion (https://github.com/floitsch/double-conversion/) +``` + git clone https://github.com/facebook/folly.git + cd folly/folly + autoreconf -ivf + ./configure CPPFLAGS="-I/opt/local/include" LDFLAGS="-L/opt/local/lib" + make + sudo make install +``` + +#### Windows (Vcpkg) + +folly is available in [Vcpkg](https://github.com/Microsoft/vcpkg#vcpkg) and releases may be built via `vcpkg install folly:x64-windows`. + +You may also use `vcpkg install folly:x64-windows --head` to build against `master`. + +#### Other Linux distributions + +- double-conversion (https://github.com/google/double-conversion) Download and build double-conversion. You may need to tell configure where to find it. [double-conversion/] `ln -s src double-conversion` - [folly/] `./configure LDFLAGS=-L$DOUBLE_CONVERISON_HOME/ CPPFLAGS=-I$DOUBLE_CONVERISON_HOME/` + [folly/] `./configure LDFLAGS=-L$DOUBLE_CONVERSION_HOME/ CPPFLAGS=-I$DOUBLE_CONVERSION_HOME/` - [folly/] `LD_LIBRARY_PATH=$DOUBLE_CONVERISON_HOME/ make` + [folly/] `LD_LIBRARY_PATH=$DOUBLE_CONVERSION_HOME/ make` - additional platform specific dependencies: - Fedora 17 64-bit + Fedora 21 64-bit - gcc - gcc-c++ - autoconf @@ -111,4 +251,12 @@ Other Linux distributions - zlib-devel - glog-devel - gflags-devel - - scons (for double-conversion) + - scons + - double-conversion-devel + - openssl-devel + - libevent-devel + + Optional + - libdwarf-dev + - libelf-dev + - libunwind8-dev