16e88870fSMark Nunberg# Couchbase C Client
22fee5865STrond Norbye
3969103bdSMatt IngenthronThis is the C client library for [Couchbase](http://www.couchbase.com)
4969103bdSMatt IngenthronIt communicates with the cluster and speaks the relevant protocols
5969103bdSMatt Ingenthronnecessary to connect to the cluster and execute data operations.
62fee5865STrond Norbye
76e88870fSMark Nunberg## Features
82fee5865STrond Norbye
96e88870fSMark Nunberg* Can function as either a synchronous or asynchronous library
106e88870fSMark Nunberg* Callback Oriented
116e88870fSMark Nunberg* Can integrate with most other asynchronous environments. You can write your
126e88870fSMark Nunberg  code to integrate it into your environment. Currently support exists for
136e88870fSMark Nunberg    * [libuv](http://github.com/joyent/libuv) (Windows and POSIX)
146e88870fSMark Nunberg    * [libev](http://software.schmorp.de/pkg/libev.html) (POSIX)
156e88870fSMark Nunberg    * [libevent](http://libevent.org/) (POSIX)
166e88870fSMark Nunberg    * `select` (Windows and POSIX)
176e88870fSMark Nunberg    * IOCP (Windows Only)
186e88870fSMark Nunberg* Support for operation batching
196e88870fSMark Nunberg* Cross Platform - Tested on Linux, OS X, and Windows.
202fee5865STrond Norbye
216e88870fSMark Nunberg## Building
222fee5865STrond Norbye
2317c74a78SMark NunbergBefore you build from this repository, please check the
24da4363f4SSergey Avseyev[installation page](https://developer.couchbase.com/server/other-products/release-notes-archives/c-sdk)
2517c74a78SMark Nunbergto see if there is a binary or release tarball available for your needs. Since the code here is
26969103bdSMatt Ingenthronnot part of an official release it has therefore not gone through our
27969103bdSMatt Ingenthronrelease testing process.
282fee5865STrond Norbye
296e88870fSMark Nunberg### Dependencies
30e7387be8SMark Nunberg
31e7387be8SMark NunbergBy default the library depends on:
32e7387be8SMark Nunberg
33e7387be8SMark Nunberg* _libevent_ (or _libev_) for the primary I/O backend.
34e7387be8SMark Nunberg* _openssl_ for SSL transport.
3582cae610SMark Nunberg* _CMake_ version 2.8.9 or greater (for building)
36e7387be8SMark Nunberg
37e7387be8SMark NunbergOn Unix-like systems these dependencies are checked for by default
38e7387be8SMark Nunbergwhile on Windows they are not checked by default.
39e7387be8SMark Nunberg
4082cae610SMark NunbergOn Unix, the build system will expect to have _libevent_ or _libev_ installed,
4182cae610SMark Nunbergunless building plugins is explicitly disabled (see further).
422fee5865STrond Norbye
4382cae610SMark Nunberg### Building on Unix-like systems
44aadf8e02SM. Nunberg
45969103bdSMatt IngenthronProvided is a convenience script called `cmake/configure`. It is a Perl
46969103bdSMatt Ingenthronscript and functions like a normal `autotools` script.
47aadf8e02SM. Nunberg
486e88870fSMark Nunberg```shell
4917c74a78SMark Nunberg$ git clone git://github.com/couchbase/libcouchbase.git
5082cae610SMark Nunberg$ cd libcouchbase && mkdir build && cd build
5117c74a78SMark Nunberg$ ../cmake/configure
526e88870fSMark Nunberg$ make
536e88870fSMark Nunberg$ ctest
546e88870fSMark Nunberg```
55aadf8e02SM. Nunberg
5682cae610SMark Nunberg### Building on Windows
571846345cSSergey Avseyev
5882cae610SMark NunbergAssuming `git` and Visual Studio 2010 are installed, from a `CMD` shell, do:
591846345cSSergey Avseyev
606e88870fSMark Nunberg```
616e88870fSMark NunbergC:\> git clone git://github.com/couchbase/libcouchbase.git
626e88870fSMark NunbergC:\> mkdir lcb-build
636e88870fSMark NunbergC:\> cd lcb-build
646e88870fSMark NunbergC:\> cmake -G "Visual Studio 10" ..\libcouchbase
6582cae610SMark NunbergC:\> cmake --build .
666e88870fSMark Nunberg```
671846345cSSergey Avseyev
686e88870fSMark NunbergThis will generate and build a Visual Studio `.sln` file.
691846345cSSergey Avseyev
706e88870fSMark NunbergWindows builds are known to work on Visual Studio versions 2008, 2010 and
716e88870fSMark Nunberg2012.
721846345cSSergey Avseyev
73e7387be8SMark NunbergIf you wish to link against OpenSSL, you should set the value of
74e7387be8SMark Nunberg`OPENSSL_ROOT_DIR` to the location of the installation path, as described
75e7387be8SMark Nunberg[here](https://github.com/Kitware/CMake/blob/master/Modules/FindOpenSSL.cmake)
76e7387be8SMark Nunberg
7748d3bc46SSergey Avseyev## Running tests
7848d3bc46SSergey Avseyev
7948d3bc46SSergey AvseyevTo run tests, you can use either ctest directly or generated build targets.
8048d3bc46SSergey AvseyevFor Unix-like:
8148d3bc46SSergey Avseyev
8248d3bc46SSergey Avseyev```shell
8348d3bc46SSergey Avseyevmake test
8448d3bc46SSergey Avseyev```
8548d3bc46SSergey Avseyev
8648d3bc46SSergey AvseyevFor windows:
8748d3bc46SSergey Avseyev
8848d3bc46SSergey Avseyev```batchfile
8948d3bc46SSergey Avseyevcmake --build . --target alltests
9048d3bc46SSergey Avseyevctest -C debug
9148d3bc46SSergey Avseyev```
9248d3bc46SSergey Avseyev
9348d3bc46SSergey AvseyevBy default tests will use [CouchbaseMock](https://github.com/couchbase/CouchbaseMock) project to simulate the Couchbase
9448d3bc46SSergey AvseyevCluster. It allows to cover more different failure scenarios, although does not implement all kinds of APIs provided
9548d3bc46SSergey Avseyevby real server.
9648d3bc46SSergey Avseyev
9748d3bc46SSergey AvseyevIf you need to test against real server, you have to provide comma-separated configuration in `LCB_TEST_CLUSTER_CONF`
9848d3bc46SSergey Avseyevenvironment variable. For example, the following command will run tests against local cluster and bucket `default` using
9948d3bc46SSergey Avseyevadministrator credentials:
10048d3bc46SSergey Avseyev
10148d3bc46SSergey Avseyev```shell
10248d3bc46SSergey Avseyevexport LCB_TEST_CLUSTER_CONF=couchbase://localhost,default,Administrator,password
10348d3bc46SSergey Avseyevmake test
10448d3bc46SSergey Avseyev```
10548d3bc46SSergey AvseyevNote that specifying username will automatically switch to RBAC mode, which supported by Couchbase Server 5.0+. For old
10648d3bc46SSergey Avseyevservers the spec will look like `couchbase://localhost,default` or `couchbase://localhost,protected,,secret`.
10748d3bc46SSergey Avseyev
10848d3bc46SSergey AvseyevAlso tests expecting `beer-sample` bucket loaded. It comes with the server. Look at "Sample buckets" section of Admin
10948d3bc46SSergey AvseyevConsole.
11048d3bc46SSergey Avseyev
1116e88870fSMark Nunberg## Bugs, Support, Issues
1126e88870fSMark NunbergYou may report issues in the library in our issue tracked at
113485e391bSMark Nunberg<https://issues.couchbase.com>. Sign up for an account and file an issue
114969103bdSMatt Ingenthronagainst the _Couchbase C Client Library_ project.
1151846345cSSergey Avseyev
1166e88870fSMark NunbergThe developers of the library hang out in IRC on `#libcouchbase` on
1176e88870fSMark Nunbergirc.freenode.net.
1181846345cSSergey Avseyev
1191846345cSSergey Avseyev
1206e88870fSMark Nunberg## Examples
1211846345cSSergey Avseyev
1226e88870fSMark Nunberg* The `examples` directory
123ad71483fSMark Nunberg* Official client libraries using libcouchbase
1246e88870fSMark Nunberg    * [node.js](http://github.com/couchbase/couchnode)
1256e88870fSMark Nunberg    * [Python](http://github.com/couchbase/couchbase-python-client)
126da4363f4SSergey Avseyev    * [PHP](http://github.com/couchbase/php-couchbase)
127ad71483fSMark Nunberg* Community projects using libcouchbase
128ad71483fSMark Nunberg    * [C++11 wrapper](https://github.com/couchbaselabs/libcouchbase-cxx)
12968f372f8SWilliam Cummings    * [cberl - Couchbase NIF](https://github.com/wcummings/cberl)
130ad71483fSMark Nunberg    * [Perl client](https://github.com/mnunberg/perl-Couchbase-Client)
131da4363f4SSergey Avseyev    * [Ruby](http://github.com/couchbase/couchbase-ruby-client) (uses the old < 2.6 API)
132aadf8e02SM. Nunberg
1336e88870fSMark Nunberg## Documentation
134378e2fa9SMark Nunberg
135c20391c6SMark NunbergDocumentation is available in guide format (introducing the basic concepts of
136c20391c6SMark NunbergCouchbase and the library). It is recommended for first-time users, and can
137da4363f4SSergey Avseyevbe accessed at our [Documentation Site](https://developer.couchbase.com/documentation/server/current/sdk/c/start-using-sdk.html).
138c20391c6SMark Nunberg
139c20391c6SMark NunbergAPI documentation is also available and is generated from the library's headers.
140c20391c6SMark NunbergIt may contain references to more advanced features not found in the guide.
141c20391c6SMark Nunberg
142378e2fa9SMark NunbergAPI documentation may be generated by running `doxygen` within the source root
143378e2fa9SMark Nunbergdirectory. When this is done, you should have a `doc/html/index.html` page which
144378e2fa9SMark Nunbergmay be viewed.
145378e2fa9SMark Nunberg
146378e2fa9SMark NunbergDoxygen may be downloaded from the
147378e2fa9SMark Nunberg[doxygen downloads page](http://www.stack.nl/~dimitri/doxygen/download.html). Note
148378e2fa9SMark Nunberghowever that most Linux distributions as well as Homebrew contain Doxygen in their
149378e2fa9SMark Nunbergrepositories.
150378e2fa9SMark Nunberg
151378e2fa9SMark Nunberg```
152378e2fa9SMark Nunberg$ doxygen
153378e2fa9SMark Nunberg$ xdg-open doc/html/index.html # Linux
154378e2fa9SMark Nunberg$ open doc/html/index.html # OS X
155378e2fa9SMark Nunberg```
156378e2fa9SMark Nunberg
1578fcb0db6SMark NunbergYou may also generate documentation using the `doc/Makefile` which dynamically
1588fcb0db6SMark Nunberginserts version information
159378e2fa9SMark Nunberg
160378e2fa9SMark Nunberg```
1618fcb0db6SMark Nunberg$ make -f doc/Makefile public # for public documentation
1628fcb0db6SMark Nunberg$ make -f doc/Makefile internal # for internal documentation
163378e2fa9SMark Nunberg```
164378e2fa9SMark Nunberg
1658fcb0db6SMark NunbergThe generated documentation will be in the `doc/public/html` directory for
1668fcb0db6SMark Nunbergpublic documentation, and in the `doc/internal/html` directory for internal
1678fcb0db6SMark Nunbergdocumentation.
1682fee5865STrond Norbye
1696e88870fSMark Nunberg## Contributors
1706e88870fSMark Nunberg
1719fb8403aSMark NunbergThe following people contributed to libcouchbase (in alphabetic order)
1729fb8403aSMark Nunberg(last updated Nov. 27 2014)
1739fb8403aSMark Nunberg
1749fb8403aSMark Nunberg* Brett Lawson <brett19@gmail.com>
1759fb8403aSMark Nunberg* Dave Rigby <daver@couchbase.com>
1769fb8403aSMark Nunberg* Jan Lehnardt <jan@apache.org>
1779fb8403aSMark Nunberg* Mark Nunberg <mnunberg@haskalah.org>
1789fb8403aSMark Nunberg* Matt Ingenthron <ingenthr@cep.net>
1799fb8403aSMark Nunberg* Patrick Varley <patrick@couchbase.com>
1809fb8403aSMark Nunberg* Paul Farag <pfarag@neuraliq.com>
1819fb8403aSMark Nunberg* Pierre Joye <pierre.php@gmail.com>
1829fb8403aSMark Nunberg* Sebastian <sebastian@chango.com>
1839fb8403aSMark Nunberg* Sergey Avseyev <sergey.avseyev@gmail.com>
1849fb8403aSMark Nunberg* Subhashni Balakrishnan <b.subhashni@gmail.com>
1859fb8403aSMark Nunberg* Sundar Sridharan <sundar.sridharan@gmail.com>
1869fb8403aSMark Nunberg* Trond Norbye <trond.norbye@gmail.com>
1879fb8403aSMark Nunberg* Volker Mische <vmx@couchbase.com>
1889fb8403aSMark Nunberg* William Bowers <wbowers@neuraliq.com>
1899fb8403aSMark Nunberg* Yura Sokolov <funny.falcon@gmail.com>
1909fb8403aSMark Nunberg* Yury Alioshinov <haster2010@gmail.com>
1916e88870fSMark Nunberg
1926e88870fSMark Nunberg## License
1936e88870fSMark Nunberg
1946e88870fSMark Nunberglibcouchbase is licensed under the Apache 2.0 License. See `LICENSE` file for
195969103bdSMatt Ingenthrondetails.
196