1MONGOC_INSTALLING(3) MongoDB C Driver MONGOC_INSTALLING(3)
2
6 mongoc_installing - Installing the MongoDB C Driver (libmongoc) and
7 BSON library (libbson)
8 The following guide will step you through the process of downloading,
10 building, and installing the current release of the MongoDB C Driver
11 (libmongoc) and BSON library (libbson).
12
14 The MongoDB C Driver is continuously tested on variety of platforms
15 including:
16 · Archlinux
18 · Debian 8.1
20 · macOS 10.10
22 · Microsoft Windows Server 2008
24 · RHEL 7.0, 7.1, 7.2
26 · SUSE 12
28 · Ubuntu 12.04, 14.04, 16.04
30 · Clang 3.4, 3.5, 3.7, 3.8
32 · GCC 4.6, 4.8, 4.9, 5.3
34 · MinGW-W64
36 · Visual Studio 2010, 2013, 2015
38 · x86, x86_64, ARM (aarch64), Power8 (ppc64le), zSeries (s390x)
40
42 Several Linux distributions provide packages for libmongoc and its
43 dependencies. One advantage of installing libmongoc with a package man‐
44 ager is that its dependencies (including libbson) will be installed
45 automatically.
46 The libmongoc package is available on recent versions of Debian and
48 Ubuntu.
49 $ apt-get install libmongoc-1.0-0
51 On Fedora, a mongo-c-driver package is available in the default reposi‐
53 tories and can be installed with:
54 $ dnf install mongo-c-driver
56 On recent Red Hat systems, such as CentOS and RHEL 7, a mongo-c-driver
58 package is available in the EPEL repository. To check which version is
59 available, see https://apps.fedoraproject.org/packages/mongo-c-driver.
60 The package can be installed with:
61 $ yum install mongo-c-driver
63
65 The libbson package is available on recent versions of Debian and
66 Ubuntu. If you have installed libmongoc, then libbson will have already
67 been installed as a dependency. It is also possible to install libbson
68 without libmongoc.
69 $ apt-get install libbson-1.0
71 On Fedora, a libbson package is available in the default repositories
73 and can be installed with:
74 $ dnf install libbson
76 On recent Red Hat systems, such as CentOS and RHEL 7, a libbson package
78 is available in the EPEL repository. To check which version is avail‐
79 able, see https://apps.fedoraproject.org/packages/libbson. The package
80 can be installed with:
81 $ yum install libbson
83
85 Prerequisites for libmongoc
86 OpenSSL is required for authentication or for SSL connections to Mon‐
87 goDB. Kerberos or LDAP support requires Cyrus SASL.
88 To install all optional dependencies on RedHat / Fedora:
90 $ sudo yum install cmake openssl-devel cyrus-sasl-devel
92 On Debian / Ubuntu:
94 $ sudo apt-get install cmake libssl-dev libsasl2-dev
96 On FreeBSD:
98 $ su -c 'pkg install cmake openssl cyrus-sasl'
100 Prerequisites for libbson
102 The only prerequisite for building libbson is cmake. The command lines
103 above can be adjusted to install only cmake.
104 Building from a release tarball
106 Unless you intend to contribute to mongo-c-driver and/or libbson, you
107 will want to build from a release tarball.
108 The most recent release of libmongoc and libbson, both of which are
110 included in mongo-c-driver, can be downloaded here <‐
111 https://github.com/mongodb/mongo-c-driver/releases/latest>. The
112 instructions in this document utilize cmake's out-of-source build fea‐
113 ture to keep build artifacts separate from source files.
114 The following snippet will download and extract the driver, and config‐
116 ure it:
117 $ wget https://github.com/mongodb/mongo-c-driver/releases/download/x.y.z/mongo-c-driver-x.y.z.tar.gz
119 $ tar xzf mongo-c-driver-x.y.z.tar.gz
120 $ cd mongo-c-driver-x.y.z
121 $ mkdir cmake-build
122 $ cd cmake-build
123 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..
124 The -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF option is recommended, see
126 init-cleanup. Another useful cmake option is -DCMAKE_BUILD_TYPE=Release
127 for a release optimized build and -DCMAKE_BUILD_TYPE=Debug for a debug
128 build. For a list of all configure options, run cmake -L ...
129 If cmake completed successfully, you will see a considerable amount of
131 output describing your build configuration. The final line of output
132 should look something like this:
133 -- Build files have been written to: /home/user/mongo-c-driver-x.y.z/cmake-build
135 If cmake concludes with anything different, then there is likely an
137 error or some other problem with the build. Review the output to iden‐
138 tify and correct the problem.
139 mongo-c-driver contains a copy of libbson, in case your system does not
141 already have libbson installed. The build will detect if libbson is not
142 installed and use the bundled libbson.
143 Additionally, it is possible to build only libbson by setting the -DEN‐
145 ABLE_MONGOC=OFF option:
146 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF -DENABLE_MONGOC=OFF ..
148 A build configuration description similar to the one above will be dis‐
150 played, though with fewer entries. Once the configuration is complete,
151 the selected items can be built and installed with these commands:
152 $ make
154 $ sudo make install
155 There are two ways to uninstall the components that have been
157 installed. The first is to invoke the uninstall program directly. On
158 Linux/Unix:
159 $ sudo /usr/local/share/mongo-c-driver/uninstall.sh
161 On Windows:
163 C:\Users\user> C:\mongo-c-driver\share\mongo-c-driver\uninstall.bat
165 The second way to uninstall is from within the build directory, assum‐
167 ing that it is in the exact same state as when the install command was
168 invoked:
169 $ sudo make uninstall
171 The second approach simply invokes the uninstall program referenced in
173 the first approach.
174 Building from git
176 Clone the repository and build the current master or a particular
177 release tag:
178 $ git clone https://github.com/mongodb/mongo-c-driver.git
180 $ cd mongo-c-driver
181 $ git checkout x.y.z # To build a particular release
182 $ python build/calc_release_version.py > VERSION_CURRENT
183 $ mkdir cmake-build
184 $ cd cmake-build
185 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..
186 $ make
187 $ sudo make install
188 Generating the documentation
190 Install Sphinx, then:
191 $ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
193 $ make mongoc-doc
194 To build only the libbson documentation:
196 $ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
198 $ make bson-doc
199 The -DENABLE_MAN_PAGES=ON and -DENABLE_HTML_DOCS=ON can also be added
201 as options to a normal build from a release tarball or from git so that
202 the documentation is built at the same time as other components.
203
205 Install the XCode Command Line Tools:
206 $ xcode-select --install
208 The cmake utility is also required. First install Homebrew according to
210 its instructions, then:
211 $ brew install cmake
213 Download the latest release tarball:
215 $ curl -LO https://github.com/mongodb/mongo-c-driver/releases/download/x.y.z/mongo-c-driver-x.y.z.tar.gz
217 $ tar xzf mongo-c-driver-x.y.z.tar.gz
218 $ cd mongo-c-driver-x.y.z
219 Build and install the driver:
221 $ mkdir cmake-build
223 $ cd cmake-build
224 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..
225 All of the same variations described above (e.g., building only libb‐
227 son, building documentation, etc.) are available when building on mac‐
228 OS.
229
231 Building on Windows requires Windows Vista or newer and Visual Studio
232 2010 or newer. Additionally, cmake is required to generate Visual Stu‐
233 dio project files.
234 Let's start by generating Visual Studio project files. The following
236 assumes we are compiling for 64-bit Windows using Visual Studio 2015
237 Express, which can be freely downloaded from Microsoft. We will be uti‐
238 lizing cmake's out-of-source build feature to keep build artifacts sep‐
239 arate from source files.
240 cd mongo-c-driver-x.y.z
242 mkdir cmake-build
243 cd cmake-build
244 cmake -G "Visual Studio 14 2015 Win64" \
245 "-DCMAKE_INSTALL_PREFIX=C:\mongo-c-driver" \
246 "-DCMAKE_PREFIX_PATH=C:\mongo-c-driver" \
247 ..
248 (Run cmake -LH .. for a list of other options.)
250 Now that we have project files generated, we can either open the
252 project in Visual Studio or compile from the command line. Let's build
253 using the command line program msbuild.exe:
254 msbuild.exe /p:Configuration=RelWithDebInfo ALL_BUILD.vcxproj
256 Visual Studio's default build type is Debug, but we recommend a release
258 build with debug info for production use. Now that libmongoc and libb‐
259 son are compiled, let's install them using msbuild. It will be
260 installed to the path specified by CMAKE_INSTALL_PREFIX.
261 msbuild.exe INSTALL.vcxproj
263 You should now see libmongoc and libbson installed in C:\mongo-c-driver
265 To use the driver libraries in your program, see visual-studio-guide.
267
269 Install MSYS2 from msys2.github.io. Choose the x86_64 version, not
270 i686.
271 Open c:\msys64\ming64_shell.bat (not the msys2_shell). Install depen‐
273 dencies:
274 pacman --noconfirm -Syu
276 pacman --noconfirm -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake
277 pacman --noconfirm -S mingw-w64-x86_64-extra-cmake-modules make tar
278 pacman --noconfirm -S mingw64/mingw-w64-x86_64-cyrus-sasl
279 Download and untar the latest tarball, enter its directory, and build
281 with CMake:
282 CC=/mingw64/bin/gcc.exe /mingw64/bin/cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX="C:/mongo-c-driver" ..
284 make
285
287 MongoDB, Inc
288
290 2017-present, MongoDB, Inc
2911.14.0 Feb 22, 2019 MONGOC_INSTALLING(3)