X-Git-Url: http://plrg.eecs.uci.edu/git/?p=folly.git;a=blobdiff_plain;f=README.md;h=4fc27ae242bfa8e1d37c94a841646a6c2b641d54;hp=ad8f49b7cd9ffd65ac7a53d8dab40c39a5611ca0;hb=9eadcfcdb4d766a4a10b3828d4a574c71a4ce70f;hpb=754568a3ca0583bc4aa9f64a5b09fa9c3743876f diff --git a/README.md b/README.md index ad8f49b7..4fc27ae2 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,108 @@ 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`: -Ubuntu 12.04 ------------- + (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) + +#### 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 ------------- +#### Ubuntu 13.10 The following packages are required (feel free to cut and paste the apt-get command below): @@ -51,13 +127,19 @@ sudo apt-get install \ binutils-dev \ libjemalloc-dev \ libssl-dev \ + pkg-config +``` + +If advanced debugging functionality is required + +``` +sudo apt-get install \ libunwind8-dev \ libelf-dev \ libdwarf-dev ``` -Ubuntu 14.04 LTS ----------------- +#### Ubuntu 14.04 LTS The packages listed above for Ubuntu 13.10 are required, as well as: @@ -68,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 @@ -77,8 +159,12 @@ In the folly directory, run sudo make install ``` -OS X (Homebrew) ----- +#### 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`: @@ -86,12 +172,10 @@ You may also use `folly/build/bootstrap-osx-homebrew.sh` to build against `maste ``` cd folly ./build/bootstrap-osx-homebrew.sh - make - make check ``` -OS X (MacPorts) ----- +#### OS X (MacPorts) + Install the required packages from MacPorts: ``` @@ -132,8 +216,13 @@ Download and install folly with the parameters listed below: sudo make install ``` -Other Linux distributions -------------------------- +#### 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) @@ -166,6 +255,8 @@ Other Linux distributions - double-conversion-devel - openssl-devel - libevent-devel + + Optional - libdwarf-dev - libelf-dev - libunwind8-dev