1## Dependencies
2
3On non-Windows platforms, there is a dependency on Snappy library because ForestDB supports an option to compress a document body using Snappy.
4Please visit [Snappy site](https://code.google.com/p/snappy/) for more details.
5
6* **Ubuntu**
7
8    `sudo apt-get install libsnappy-dev`
9
10* **CentOS**
11
12    `wget https://snappy.googlecode.com/files/snappy-1.1.1.tar.gz`
13
14    `tar -xvfz snappy-1.1.1.tar.gz`
15
16    `cd snappy-1.1.1`
17
18    `./configure && make && sudo make install`
19
20* **OS X**
21
22    `sudo brew install snappy`
23
24We also use the asynchronous I/O library `libaio` on Linux if it is available, to submit multiple I/O requests at once to speed up fetching non-resident blocks from disk. As of this time, we use `libaio` to read data blocks from the old file during the compaction.
25
26* **Ubuntu**
27
28    `sudo apt-get install libaio-devel`
29
30* **CentOS**
31
32    `sudo yum install libaio-devel`
33
34We plan to support asynchronous I/O in other operating systems such as Windows and OS X, soon.
35
36For better memory fragmentation and concurrency management, jemalloc can be linked to ForestDB if available on the host environment. Please visit [jemalloc site](http://www.canonware.com/jemalloc/) for more information and install guideline.
37
38Database encryption is also supported and can be enabled at compilation time. Currently, we support CommonCrypto library on iOS and OS X, [OpenSSL](https://www.openssl.org/), and [LibTomCrypt](https://github.com/libtom/libtomcrypt).
39
40## Compilation and Build
41
42We use [CMake](http://www.cmake.org/cmake/) to provide the build support for a wide range of platforms. Cmake version 3.1 is required at least to have C++11 support. Please follow the instructions below to install CMake in your target platform.
43
44* **Ubuntu**
45
46    `sudo apt-get install cmake`
47
48* **Centos**
49
50    `wget http://www.cmake.org/files/v2.8/cmake-3.4.3.tar.gz`
51
52    `tar xvfz cmake-3.4.3.tar.gz`
53
54    `cd cmake-3.4.3`
55
56    `./bootstrap && make && sudo make install`
57
58* **OS X**
59
60    `brew install cmake`
61
62* **Windows**
63
64    Please download and install CMake binary for Windows from [CMake download page](http://www.cmake.org/cmake/resources/software.html).
65
66Once CMake is installed, please follow the instructions below to compile and build ForestDB on Ubuntu, Centos, or OS X:
67
68`git clone git://github.com/couchbase/forestdb`
69
70`cd forestdb`
71
72`mkdir build`
73
74`cd build`
75
76`cmake ../`
77
78(The default value of `CMAKE_BUILD_TYPE` is `RelWithDebInfo`. If you want to build with optimizations disabled for debugging, type `cmake -DCMAKE_BUILD_TYPE=Debug ../` instead.)
79
80`_JEMALLOC` variable can be optionally set to 1 and passed to link jemalloc to ForestDB (`cmake -D_JEMALLOC=1 ../`)
81
82`_ENCRYPTION` macro can be also optionally passed to specify which crypto library (`commoncrypto`, `openssl`, or `libtomcrypt`) is used to support database encryption (e.g., `cmake -D_ENCRYPTION=commoncrypto ../`)
83
84`make all`
85
86On Windows (using Visual Studio's CL compiler), the instructions are as follows:
87
88`git clone git://github.com/couchbase/forestdb` (or clone repository using [TortoiseGit](http://code.google.com/p/tortoisegit/))
89
90`cd forestdb`
91
92`mkdir build`
93
94`cd build`
95
96Note that the path and environment variables for command-line builds need to be set before moving to the next step. Please refer to the [MSDN Page](http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx).
97
98`cmake -G "NMake Makefiles" ..\`
99
100(The default value of `CMAKE_BUILD_TYPE` is `Debug`. If you want to build with optimizations enabled for better performance, type `cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release ../` instead.)
101
102`nmake all`
103
104## Test
105
106To run all the unit tests:
107
108* **Ubuntu**, **Centos**, and **OS X**
109
110    `make test`
111
112* **Windows**
113
114    `nmake test`
115
116* To enable code-coverage reporting for tests, install ```gcov``` and ```lcov``` for your OS. (Windows not supported).  Also make sure build type is **Coverage**
117
118     `cmake -DCMAKE_BUILD_TYPE=Coverage ../`
119
120     `make all`
121
122     `make test_coverage`
123
124    This target will run the tests and output coverage report to ```<repo>/coverage/index.html```
125
126* To enable valgrind tests, install ```valgrind``` for your OS. (Windows not supported).  Also make sure build type is **Valgrind**
127
128     `cmake -DCMAKE_BUILD_TYPE=Valgrind ../`
129
130     `make all`
131
132     `make test_valgrind`
133
134    This target will run the tests and output the memory report to the console
135
136* By default, every run will produce an additional .lat file which indicates the latencies
137  of the forestdb api. This is disabled if CMAKE_BUILD_TYPE=Release
138
139* To enable the use of threadsanitizer for tests, install clang 3.5+ (currently only Ubuntu 14.04 is supported).  Also make sure to set flag **CB_THREADSANITIZER**
140
141     `cmake  -DCMAKE_C_COMPILER=clang-3.5 -DCMAKE_CXX_COMPILER=clang++-3.5  -DCB_THREADSANITIZER=1 ..`
142
143     `make all`
144
145     `make test`
146
147     Alternatively you can manually run tests under build/tests/<component>/ for real-time analysis.  When running as standalone it is recommended to include false error suppressions:
148
149     `TSAN_OPTIONS="second_deadlock_stack=1 suppressions=../../../cmake/Modules/tsan.suppressions" ./fdb_functional_test`
150
151* For hardware accelerated CRC32C which can improve ForestDB performance, please fetch the optional couchbase platform repository into the forestdb source directory before building.
152
153     `cd forestdb`
154
155     `git clone https://github.com/couchbase/platform.git`
156
157     `Follow the rest of the platform specific build instructions from above`
158