tlm - Top-level Makefile
What's this, then? The tlm project contains the make information for building Couchbase on multiple platforms.
Table of Contents
- How to build
- Microsoft Windows 2008R2
- Ubuntu 14.04
- Fedora 21
- Static Analysis
The file named
CMakeLists.txt contains the full build description
for Couchbase. It should be copied to the top of your source directory
(this happens automatically when you are using repo).
cmake directory contains macros used by cmake to configure a
build of Couchbase.
Makefile is a convenience file that repo will put in the root of
your source directory. It invokes
cmake with a specific set of
options. "All" flavors of make should be able to parse this makefile,
and its defaults are set to match building on Microsoft Windows.
GNUmakefile is another convenience file that repo will put in the
root of your source directory. GNU make will favor this file over
Makefile and this file just overrides the defaults specified in
How to build
Couchbase utilizes CMake in order to provide build support for a wide range of platforms. CMake isn't a build system like GNU Autotools, but a tool that generates build information for external systems like: Visual Studio projects, XCode projects and Makefiles to name a few. Their good support for Microsoft Windows and Makefiles is the primary reason why we decided to move away from GNU Autotools. CMake isn't a magic pill that solves all our problems; it comes with its own list of challenges.
It is recommended to perform "out of source builds", which means that the build artifacts is stored outside the source directory.
If you just want to build Couchbase and without any special configuration, you may use the Makefile we've supplied for your convenience:
trond@ok > mkdir source trond@ok > cd source trond@ok source> repo init -u git://github.com/couchbase/manifest -m branch-master.xml trond@ok source> repo sync trond@ok source> make
This would install the build software in a subdirectory named
install. To change this you may run:
trond@ok source> make PREFIX=/opt/couchbase
Customize your builds
CMake offers a wide range of customizations, and this chapter won't try to cover all of them. There is plenty of documentation available on the webpage.
There is no point of trying to keep a list of all tunables in this
document. To find the tunables you have two options: look in
cmake/Modules/*.cmake or you may look in the cache file generated
during a normal build (see
There are two ways to customize your own builds. You can do it all by yourself by invoking cmake yourself:
trond@ok > mkdir source trond@ok > mkdir build trond@ok > cd source trond@ok source> repo init -u git://github.com/couchbase/manifest -m branch-master.xml trond@ok source> repo sync trond@ok source> cd ../build 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" trond@ok build> gmake all install
Or pass extra options to the convenience Makefile provided:
trond@ok > mkdir source trond@ok > mkdir build trond@ok > cd source trond@ok source> repo init -u git://github.com/couchbase/manifest -m branch-master.xml trond@ok source> repo sync 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'
CMAKE_PREFIX_PATH to specify a "list" of directories to search
for tools/libraries if they are stored in "non-standard"
Microsoft Windows 2008R2
The following steps are needed to build Couchbase on Microsoft Windows 2008R2:
- Install OS, activate and run Windows Update and install all updates
- Install Google Chrome (optional, but makes your life easier)
- Install Visual Studio 2013 Professional
- Install all updates from microsoft update
- Install GIT and select the option to add GIT to path
- Install Python 2.7 and add c:\python27 to path (manually)
- Install 7-ZIP and add the installation to path (manually)
- Install CMake and add to path
- Install [MinGW][mingw_link] and add to path
- Download and install 2008 runtime extensions
Note: Significant portions of Couchbase Server are written in Go. Go itself is automatically downloaded as part of the build, but Go requires gcc (and not Visual Studio) in order to interface with C libraries. Our builds are tested with MinGW 4.8.3.
Repo will complain if git isn't properly configured. Setting name and email should be sufficient, but you also may at least want to set the two additional settings suggested:
C:\> git config --global user.email firstname.lastname@example.org C:\> git config --global user.name "Trond Norbye" C:\> git config --global color.ui false C:\> git config --global core.autocrlf true
How to build
Before you may start to build on Microsoft Windows you have to set up
the environment. The script
environment.bat is located in the
Open cmd.com and type in the following (assuming c:\compile\couchbase is the directory holding your source):
C:\> set source_root=c:\compile\couchbase C:\> set target_arch=amd64 C:\> environment
You may now follow the build description outlined in How to
build. Please note that the make utility
on windows is named
Multiple versions of Mac OSX may work, but this list is verified with El Capitan
- Install XCode 7.2
- Install Homebrew
Install the following packages from homebrew:
trond@ok> brew install cmake git ccache
You should be all set to start compile the server as described above.
The steps below may work on other versions of Ubuntu as well, but this procedure is verified with a clean installation of Ubuntu 14.04.1
sudo su - wget https://storage.googleapis.com/git-repo-downloads/repo chmod a+x repo mv repo /usr/local/bin apt-get install -y git gcc g++ ccache cmake libssl-dev
The steps below may work on other versions of Fedora as well, but this procedure is verified with a clean installation of Fedora 21
sudo su - wget https://storage.googleapis.com/git-repo-downloads/repo chmod a+x repo mv repo /usr/local/bin yum install -y gcc gcc-c++ git cmake ccache redhat-lsb-core \ openssl-devel
I tested this on a clean install of OpenSUSE 13.2 by choosing the defaults during the installer except choosing gnome desktop and enable ssh access.
sudo zypper install gcc gcc-c++ autoconf automake ncurses-devel \ git ccache libopenssl-devel cmake
Open a new terminal to ensure you get an updated environment (the package install modifies some of the environement variables)
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo chmod a+x ~/bin/repo sudo mkdir /opt/couchbase sudo chown `whoami` /opt/couchbase mkdir -p compile/couchbase cd compile/couchbase repo init -u git://github.com/couchbase/manifest -m branch-master.xml -g default,build repo sync repo start opensuse --all mkdir cbdeps && cd cbdeps ../cbbuild/cbdeps/build-all-sherlock.sh export CB_DOWNLOAD_DEPS_CACHE=`pwd`/output export CB_DOWNLOAD_DEPS_MANIFEST=`pwd`/output/manifest.cmake unset GOBIN cd .. gmake PREFIX=/opt/couchbase
Note: Unfortunately the build-all-sherlock.sh script mentioned above is likely out of date for Couchbase Server builds later than 4.1.
You should be able to start the server by running
There are pre-canned build rules to allow you to run the Clang Static Analyzer against the Couchbase codebase.
So far this has only been tested on OS X, using Clang shipping as part of OS X Developer Tools. It should be possible to also run on other platforms which Clang/LLVM is available, however this isn't tested.
clang(from OS X Developer Tools). If you can build from source you should already have this :)
- Download and extract clang Static Analyzer tools
Note that while the actual analyzer functionality is built into
clang, this is needed for
scan-viewtools to invoke and display the analyser results.
scan-viewto your path:
make analyzeat the top-level to configure clang-analyser as the 'compiler':
At the end you will see a message similar to the following - Invoke the specified command to browse the found bugs:
scan-build: 31 bugs found. scan-build: Run 'scan-view /source/build-analyzer/analyser-results/2014-06-05-173247-52416-1' to examine bug reports.
Thread Sanitizer and Address Sanitizer
- A compiler which supports ThreadSanitizer / AddressSanitizer. Recent version of Clang (3.2+) or GCC (4.8+) are claimed to work, however only Clang (3.5+) has been tested.
Ensure that the compiler supporting Thread/Address Sanitizer is chosen by CMake. If it's the system default compiler there is nothing to do; otherwise you will need to set both
CXXenvironment variables to point to the C / C++ compiler before calling the build system.
Pass the variable
ThreadSanitizer one liner for a Ubuntu-based system where Clang isn't the default system compiler:
CC=clang CXX=clang++ make EXTRA_CMAKE_OPTIONS="-D CB_THREADSANITIZER=1"
and for AddressSanitizer:
CC=clang CXX=clang++ make EXTRA_CMAKE_OPTIONS="-D CB_ADDRESSSANITIZER=1"
- Run one or more tests. Any issues will be reported (to stderr by default).
Customizing ThreadSanitizer / AddressSanitizer
cmake/Modules/CouchbaseThreadSanitizer.cmake CMake fragment for
how ThreadSanizer is configured.
TSAN_OPTIONS environment variable (documented on the
ThreadSanitizer Flags wiki page) for more
information on configuring.
Similarly for AddressSanitizer see
cmake/Modules/CouchbaseAddressSanitizer.cmake, and the
ASAN_OPTIONS environment variable (documented on the
AddressSanitizer Flags wiki page) for