Name Date Size

..11-Feb-20204 KiB

.gitignoreH A D11-Feb-202012

clang-format-pre-commit-hookH A D11-Feb-20201.6 KiB

cmake/Modules/H11-Feb-20204 KiB

CMakeLists-cbq.txtH A D11-Feb-2020537

CMakeLists-moxi.txtH A D11-Feb-20201.2 KiB

CMakeLists.txtH A D11-Feb-202010.1 KiB

deps/H11-Feb-20204 KiB

dot-clang-formatH A D11-Feb-20202.6 KiB

GNUmakefileH A D11-Feb-20201.5 KiB

install_hook.shH A D11-Feb-20202.1 KiB

MakefileH A D11-Feb-20202.6 KiB

memcached-wrapper.inH A D11-Feb-2020822

moxi-wrapper.inH A D11-Feb-2020125

README.markdownH A D11-Feb-202013 KiB

scripts/H11-Feb-20204 KiB

tag_release.pyH A D11-Feb-20201.3 KiB

third-party-CMakeLists.txtH A D11-Feb-2020809

tsan.suppressionsH A D11-Feb-20202.4 KiB

valgrind.suppH A D11-Feb-20206.7 KiB

win32/H11-Feb-20204 KiB

README.markdown

1# tlm - Top-level Makefile
2
3What's this, then? The tlm project contains the make information for
4building Couchbase on multiple platforms.
5
6**Table of Contents**
7
8- [Content](#user-content-content)
9- [How to build](#user-content-how-to-build)
10	- [Simple](#user-content-simple-build)
11	- [Customize your builds](#user-content-customize-your-builds)
12- [Microsoft Windows 2008R2](#user-content-microsoft-windows-2008r2)
13	- [Configuration](#user-content-configuration)
14		- [git](#user-content-git)
15	- [How to build](#user-content-how-to-build-1)
16- [MacOSX](#user-content-macosx)
17- [Ubuntu 14.04](#user-content-ubuntu-1404)
18- [Fedora 21](#user-content-fedora-21)
19- [OpenSUSE](#opensuse)
20- [Static Analysis](#user-content-static-analysis)
21
22## Content
23
24The file named `CMakeLists.txt` contains the full build description
25for Couchbase. It should be copied to the top of your source directory
26(this happens automatically when you are using repo).
27
28The `cmake` directory contains macros used by cmake to configure a
29build of Couchbase.
30
31`Makefile` is a convenience file that repo will put in the root of
32your source directory. It invokes `cmake` with a specific set of
33options. "All" flavors of make should be able to parse this makefile,
34and its defaults are set to match building on Microsoft Windows.
35
36`GNUmakefile` is another convenience file that repo will put in the
37root of your source directory. GNU make will favor this file over
38`Makefile` and this file just overrides the defaults specified in
39`Makefile`.
40
41## How to build
42
43Couchbase utilizes [CMake][cmake_link] in order to provide build
44support for a wide range of platforms. CMake isn't a build system
45like GNU Autotools, but a tool that generates build information for
46external systems like: Visual Studio projects, XCode projects and
47Makefiles to name a few. Their good support for Microsoft Windows and
48Makefiles is the primary reason why we decided to move away from GNU
49Autotools. CMake isn't a magic pill that solves all our problems; it
50comes with its own list of challenges.
51
52It is recommended to perform "out of source builds", which means that
53the build artifacts is stored _outside_ the source directory.
54
55### Simple build
56
57If you just want to build Couchbase and without any special
58configuration, you may use the Makefile we've supplied for your
59convenience:
60
61    trond@ok > mkdir source
62    trond@ok > cd source
63    trond@ok source> repo init -u git://github.com/couchbase/manifest -m branch-master.xml
64    trond@ok source> repo sync
65    trond@ok source> make
66
67This would install the build software in a subdirectory named
68`install`. To change this you may run:
69
70    trond@ok source> make PREFIX=/opt/couchbase
71
72### Customize your builds
73
74CMake offers a wide range of customizations, and this chapter won't
75try to cover all of them. There is plenty of documentation available
76on the [webpage](http://www.cmake.org/cmake/help/documentation.html).
77
78There is no point of trying to keep a list of all tunables in this
79document. To find the tunables you have two options: look in
80`cmake/Modules/*.cmake` or you may look in the cache file generated
81during a normal build (see `build/CMakeCache.txt`)
82
83There are two ways to customize your own builds. You can do it all by
84yourself by invoking cmake yourself:
85
86    trond@ok > mkdir source
87    trond@ok > mkdir build
88    trond@ok > cd source
89    trond@ok source> repo init -u git://github.com/couchbase/manifest -m branch-master.xml
90    trond@ok source> repo sync
91    trond@ok source> cd ../build
92    trond@ok build> cmake -D CMAKE_INSTALL_PREFIX=/opt/couchbase -D CMAKE_BUILD_TYPE=Debug -D DTRACE_FOUND:BOOL=True -D DTRACE:FILEPATH=/usr/sbin/dtrace CMAKE_PREFIX_PATH="/opt/r14b04;/opt/couchbase"
93    trond@ok build> gmake all install
94
95Or pass extra options to the convenience Makefile provided:
96
97    trond@ok > mkdir source
98    trond@ok > mkdir build
99    trond@ok > cd source
100    trond@ok source> repo init -u git://github.com/couchbase/manifest -m branch-master.xml
101    trond@ok source> repo sync
102    trond@ok source> make PREFIX=/opt/couchbase CMAKE_PREFIX_PATH="/opt/r14b04;/opt/couchbase" EXTRA_CMAKE_OPTIONS='-D DTRACE_FOUND:BOOL=True -D DTRACE:FILEPATH=/usr/sbin/dtrace'
103
104Use `CMAKE_PREFIX_PATH` to specify a "list" of directories to search
105for tools/libraries if they are stored in "non-standard"
106locations. Ex:
107
108    CMAKE_PREFIX_PATH="/opt/r14b04;/opt/couchbase;/opt/local"
109
110## Microsoft Windows 2008R2
111
112The following steps are needed to build Couchbase on Microsoft Windows 2008R2:
113
114* Install OS, activate and run Windows Update and install all updates
115* Install Google Chrome (optional, but makes your life easier)
116* Install [Visual Studio 2013 Professional][win_visual_studio_link]
117* Install all updates from microsoft update
118* Install [GIT][win_git_link] and select the option to add GIT to path
119* Install [Python 2.7][win_python_link] and add c:\python27 to path (manually)
120* Install [7-ZIP][win_7zip_link] and add the installation to path (manually)
121* Install [CMake][win_cmake_link] and add to path
122* Install [MinGW][mingw_link] and add to path
123* Download and install [2008 runtime extensions][win_2008_runtime_ext_link]
124
125Note: Significant portions of Couchbase Server are written in Go. Go itself
126is automatically downloaded as part of the build, but Go requires gcc (and
127not Visual Studio) in order to interface with C libraries. Our builds are
128tested with MinGW 4.8.3.
129
130### Configuration
131
132#### git
133
134Repo will complain if git isn't properly configured. Setting name and
135email should be sufficient, but you also may at least want to set the
136two additional settings suggested:
137
138    C:\> git config --global user.email trond.norbye@gmail.com
139    C:\> git config --global user.name "Trond Norbye"
140    C:\> git config --global color.ui false
141    C:\> git config --global core.autocrlf true
142
143### How to build
144
145Before you may start to build on Microsoft Windows you have to set up
146the environment. The script `environment.bat` is located in the `win32`
147directory.
148
149Open cmd.com and type in the following (assuming c:\compile\couchbase
150is the directory holding your source):
151
152    C:\> set source_root=c:\compile\couchbase
153    C:\> set target_arch=amd64
154    C:\> environment
155
156You may now follow the build description outlined in [How to
157build](#user-content-how-to-build). Please note that the make utility
158on windows is named `nmake`.
159
160## MacOSX
161
162Multiple versions of Mac OSX may work, but this list is verified with
163El Capitan
164
165* Install XCode 7.2
166* Install [Homebrew][homebrew_link]
167
168Install the following packages from homebrew:
169
170    trond@ok> brew install cmake git ccache
171
172You should be all set to start compile the server as described above.
173
174## Ubuntu 14.04
175
176The steps below may work on other versions of Ubuntu as well, but this
177procedure is verified with a clean installation of Ubuntu 14.04.1
178
179    sudo su -
180    wget https://storage.googleapis.com/git-repo-downloads/repo
181    chmod a+x repo
182    mv repo /usr/local/bin
183    apt-get install -y git gcc g++ ccache cmake libssl-dev
184
185## Fedora 21
186
187The steps below may work on other versions of Fedora as well, but this
188procedure is verified with a clean installation of Fedora 21
189
190    sudo su -
191    wget https://storage.googleapis.com/git-repo-downloads/repo
192    chmod a+x repo
193    mv repo /usr/local/bin
194    yum install -y gcc gcc-c++ git cmake ccache redhat-lsb-core \
195                   openssl-devel
196
197## OpenSUSE
198
199I tested this on a clean install of OpenSUSE 13.2 by choosing the
200defaults during the installer except choosing gnome desktop and enable
201ssh access.
202
203    sudo zypper install gcc gcc-c++ autoconf automake ncurses-devel \
204                        git ccache libopenssl-devel cmake
205
206Open a new terminal to ensure you get an updated environment (the
207package install modifies some of the environement variables)
208
209    curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
210    chmod a+x ~/bin/repo
211    sudo mkdir /opt/couchbase
212    sudo chown `whoami` /opt/couchbase
213    mkdir -p compile/couchbase
214    cd compile/couchbase
215    repo init -u git://github.com/couchbase/manifest -m branch-master.xml -g default,build
216    repo sync
217    repo start opensuse --all
218    mkdir cbdeps && cd cbdeps
219    ../cbbuild/cbdeps/build-all-sherlock.sh
220    export CB_DOWNLOAD_DEPS_CACHE=`pwd`/output
221    export CB_DOWNLOAD_DEPS_MANIFEST=`pwd`/output/manifest.cmake
222    unset GOBIN
223    cd ..
224    gmake PREFIX=/opt/couchbase
225
226Note: Unfortunately the build-all-sherlock.sh script mentioned above is
227likely out of date for Couchbase Server builds later than 4.1.
228
229You should be able to start the server by running
230
231    /opt/couchbase/bin/couchbase-server start
232
233## Static Analysis
234
235There are pre-canned build rules to allow you to run the
236[Clang Static Analyzer][clang_static_analyzer_link] against the Couchbase
237codebase.
238
239So far this has only been tested on OS X, using Clang shipping as part
240of OS X Developer Tools. It *should* be possible to also run on other
241platforms which Clang/LLVM is available, however this isn't tested.
242
243### Prerequisites
244
245* Install `clang` (from OS X Developer Tools). If you can build from source you should already have this :)
246* Download and extract clang Static Analyzer tools
247  (from [clang-analyzer.llvm.org][clang_static_analyzer_link]).
248  Note that while the actual analyzer functionality is built into
249  clang, this is needed for `scan-build` and `scan-view` tools to
250  invoke and display the analyser results.
251
252### Running
253
254*  Add `scan-build` and `scan-view` to your path:
255
256        export PATH=$PATH:/path/to/scan-build
257
258*  Run `make analyze` at the top-level to configure clang-analyser as the 'compiler':
259
260        make analyze
261
262*  At the end you will see a message similar to the following - Invoke the specified command to browse the found bugs:
263
264
265        scan-build: 31 bugs found.
266        scan-build: Run 'scan-view /source/build-analyzer/analyser-results/2014-06-05-173247-52416-1' to examine bug reports.
267
268## Address / Thread / UndefinedBehavior Sanitizers
269
270There are pre-canned build rules to allow you to build with
271[ThreadSanitizer][thread_sanitizer_link] to detect threading issues,
272[AddressSanitizer][address_sanitizer_link] to detect memory errors, or
273[UndefinedBehaviorSanitizer][undefined_sanitizer_link] to detect
274undefined behavior.
275
276### Prerequities
277
278* A compiler which supports Address / Thread / UndefinedBehavior
279  Sanitizer. Recent version of Clang (3.2+) or GCC (4.8+) are claimed
280  to work. Currently automatied tests use GCC 7 / Clang 3.9.
281
282### Running
283
284* Ensure that the compiler supporting *Sanitizer is chosen by
285  CMake. If it's the system default compiler there is nothing to do;
286  otherwise you will need to set both `CC` and `CXX` environment
287  variables to point to the C / C++ compiler before calling the build
288  system.
289
290* Pass the variable `CB_THREADSANITIZER=1` / `CB_ADDRESSSANITIZER=1` /
291  `CB_UNDEFINEDSANITIZER=1` to CMake.
292
293ThreadSanitizer one liner for a Ubuntu-based system where Clang isn't
294the default system compiler:
295
296        CC=clang CXX=clang++ make EXTRA_CMAKE_OPTIONS="-D CB_THREADSANITIZER=1"
297
298and for AddressSanitizer:
299
300        CC=clang CXX=clang++ make EXTRA_CMAKE_OPTIONS="-D CB_ADDRESSSANITIZER=1"
301
302similary for UndefinedBehaviorSanitizer:
303
304        CC=clang CXX=clang++ make EXTRA_CMAKE_OPTIONS="-D CB_UNDEFINEDSANITIZER=1"
305
306* Run one or more tests. Any issues will be reported (to stderr by default).
307
308### Customizing Address / Thread / UndefinedBehavior Sanitizer
309
310See `cmake/Modules/CouchbaseThreadSanitizer.cmake` CMake fragment for
311how ThreadSanizer is configured.
312
313See the `TSAN_OPTIONS` environment variable (documented on the
314ThreadSanitizer [Flags][thread_sanitizer_flags] wiki page) for more
315information on configuring.
316
317Similarly for AddressSanitizer / UndefinedBehaviorSanitizer see
318`cmake/Modules/CouchbaseAddressSanitizer.cmake` or
319`cmake/Modules/CouchbassUndefinedBehaviorSanitizer.cmake`, and the
320`ASAN_OPTIONS` / `UBSAN_OPTIONS` environment variable (documented on
321the AddressSanitizer [Flags][address_sanitizer_flags] wiki page) for
322details..
323
324[win_visual_studio_link]: http://hub.internal.couchbase.com/confluence/download/attachments/7242678/en_visual_studio_professional_2013_x86_web_installer_3175305.exe?version=1&modificationDate=1389383332000
325[win_git_link]: http://git-scm.com/download/win
326[win_python_link]: http://www.python.org/download/releases/2.7/
327[win_7zip_link]: http://downloads.sourceforge.net/sevenzip/7z920-x64.msi
328[win_cmake_link]: http://www.cmake.org/cmake/resources/software.html
329[win_mingw_link]: http://www.mingw.org/
330[win_2008_runtime_ext_link]: http://www.microsoft.com/en-us/download/confirmation.aspx?id=15336
331[google_repo_link]: http://source.android.com/source/downloading.html#installing-repo
332[homebrew_link]: http://brew.sh/
333[cmake_link]: http://www.cmake.org/cmake/
334[clang_static_analyzer_link]: http://clang-analyzer.llvm.org
335[thread_sanitizer_link]: https://code.google.com/p/thread-sanitizer/wiki/CppManual
336[thread_sanitizer_flags]: https://code.google.com/p/thread-sanitizer/wiki/Flags
337[address_sanitizer_link]: https://github.com/google/sanitizers/wiki/AddressSanitizer
338[address_sanitizer_flags]: https://github.com/google/sanitizers/wiki/AddressSanitizerFlags
339[undefined_sanitizer_link]: https://github.com/google/sanitizers/wiki/AddressSanitizer
340