1MONGOC_INSTALLING(3) libmongoc 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 9.2
20 · macOS 10.12
22 · Microsoft Windows Server 2008
24 · RHEL 7.0, 7.1, 7.2
26 · Ubuntu 16.04, 18.04
28 · Clang 3.4, 3.5, 3.7, 3.8
30 · GCC 4.6, 4.8, 4.9, 5.4, 6.3
32 · MinGW-W64
34 · Visual Studio 2010, 2013, 2015
36 · x86, x86_64, ARM (aarch64), Power8 (ppc64le), zSeries (s390x)
38
40 Several Linux distributions provide packages for libmongoc and its
41 dependencies. One advantage of installing libmongoc with a package man‐
42 ager is that its dependencies (including libbson) will be installed
43 automatically.
44 The libmongoc package is available on recent versions of Debian and
46 Ubuntu.
47 $ apt-get install libmongoc-1.0-0
49 On Fedora, a mongo-c-driver package is available in the default reposi‐
51 tories and can be installed with:
52 $ dnf install mongo-c-driver
54 On recent Red Hat systems, such as CentOS and RHEL 7, a mongo-c-driver
56 package is available in the EPEL repository. To check which version is
57 available, see https://apps.fedoraproject.org/packages/mongo-c-driver.
58 The package can be installed with:
59 $ yum install mongo-c-driver
61
63 The libbson package is available on recent versions of Debian and
64 Ubuntu. If you have installed libmongoc, then libbson will have already
65 been installed as a dependency. It is also possible to install libbson
66 without libmongoc.
67 $ apt-get install libbson-1.0
69 On Fedora, a libbson package is available in the default repositories
71 and can be installed with:
72 $ dnf install libbson
74 On recent Red Hat systems, such as CentOS and RHEL 7, a libbson package
76 is available in the EPEL repository. To check which version is avail‐
77 able, see https://apps.fedoraproject.org/packages/libbson. The package
78 can be installed with:
79 $ yum install libbson
81
83 Prerequisites for libmongoc
84 OpenSSL is required for authentication or for SSL connections to Mon‐
85 goDB. Kerberos or LDAP support requires Cyrus SASL.
86 To install all optional dependencies on RedHat / Fedora:
88 $ sudo yum install cmake openssl-devel cyrus-sasl-devel
90 On Debian / Ubuntu:
92 $ sudo apt-get install cmake libssl-dev libsasl2-dev
94 On FreeBSD:
96 $ su -c 'pkg install cmake openssl cyrus-sasl'
98 Prerequisites for libbson
100 The only prerequisite for building libbson is cmake. The command lines
101 above can be adjusted to install only cmake.
102 Building from a release tarball
104 Unless you intend to contribute to mongo-c-driver and/or libbson, you
105 will want to build from a release tarball.
106 The most recent release of libmongoc and libbson, both of which are
108 included in mongo-c-driver, can be downloaded here. The instructions in
109 this document utilize cmake's out-of-source build feature to keep build
110 artifacts separate from source files.
111 The following snippet will download and extract the driver, and config‐
113 ure it:
114 $ wget https://github.com/mongodb/mongo-c-driver/releases/download/x.y.z/mongo-c-driver-x.y.z.tar.gz
116 $ tar xzf mongo-c-driver-x.y.z.tar.gz
117 $ cd mongo-c-driver-x.y.z
118 $ mkdir cmake-build
119 $ cd cmake-build
120 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..
121 The -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF option is recommended, see
123 init-cleanup. Another useful cmake option is -DCMAKE_BUILD_TYPE=Release
124 for a release optimized build and -DCMAKE_BUILD_TYPE=Debug for a debug
125 build. For a list of all configure options, run cmake -L ...
126 If cmake completed successfully, you will see a considerable amount of
128 output describing your build configuration. The final line of output
129 should look something like this:
130 -- Build files have been written to: /home/user/mongo-c-driver-x.y.z/cmake-build
132 If cmake concludes with anything different, then there is likely an
134 error or some other problem with the build. Review the output to iden‐
135 tify and correct the problem.
136 mongo-c-driver contains a copy of libbson, in case your system does not
138 already have libbson installed. The build will detect if libbson is not
139 installed and use the bundled libbson.
140 Additionally, it is possible to build only libbson by setting the -DEN‐
142 ABLE_MONGOC=OFF option:
143 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF -DENABLE_MONGOC=OFF ..
145 A build configuration description similar to the one above will be dis‐
147 played, though with fewer entries. Once the configuration is complete,
148 the selected items can be built and installed with these commands:
149 $ sudo make install
151 There are two ways to uninstall the components that have been
153 installed. The first is to invoke the uninstall program directly. On
154 Linux/Unix:
155 $ sudo /usr/local/share/mongo-c-driver/uninstall.sh
157 On Windows:
159 $ C:\mongo-c-driver\share\mongo-c-driver\uninstall.bat
161 The second way to uninstall is from within the build directory, assum‐
163 ing that it is in the exact same state as when the install command was
164 invoked:
165 $ sudo make uninstall
167 The second approach simply invokes the uninstall program referenced in
169 the first approach.
170 Building from git
172 Clone the repository and build the current master or a particular
173 release tag:
174 $ git clone https://github.com/mongodb/mongo-c-driver.git
176 $ cd mongo-c-driver
177 $ git checkout x.y.z # To build a particular release
178 $ python build/calc_release_version.py > VERSION_CURRENT
179 $ mkdir cmake-build
180 $ cd cmake-build
181 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..
182 $ sudo make install
183 Generating the documentation
185 Install Sphinx, then:
186 $ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
188 $ make mongoc-doc
189 To build only the libbson documentation:
191 $ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
193 $ make bson-doc
194 The -DENABLE_MAN_PAGES=ON and -DENABLE_HTML_DOCS=ON can also be added
196 as options to a normal build from a release tarball or from git so that
197 the documentation is built at the same time as other components.
198
200 Install the XCode Command Line Tools:
201 $ xcode-select --install
203 The cmake utility is also required. First install Homebrew according to
205 its instructions, then:
206 $ brew install cmake
208 Download the latest release tarball:
210 $ curl -LO https://github.com/mongodb/mongo-c-driver/releases/download/x.y.z/mongo-c-driver-x.y.z.tar.gz
212 $ tar xzf mongo-c-driver-x.y.z.tar.gz
213 $ cd mongo-c-driver-x.y.z
214 Build and install the driver:
216 $ mkdir cmake-build
218 $ cd cmake-build
219 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..
220 $ make install
221 All of the same variations described above (e.g., building only libb‐
223 son, building documentation, etc.) are available when building on mac‐
224 OS.
225
227 Building on Windows requires Windows Vista or newer and Visual Studio
228 2010 or newer. Additionally, cmake is required to generate Visual Stu‐
229 dio project files.
230 Let's start by generating Visual Studio project files. The following
232 assumes we are compiling for 64-bit Windows using Visual Studio 2015
233 Express, which can be freely downloaded from Microsoft. We will be uti‐
234 lizing cmake's out-of-source build feature to keep build artifacts sep‐
235 arate from source files.
236 $ cd mongo-c-driver-x.y.z
238 $ mkdir cmake-build
239 $ cd cmake-build
240 $ cmake -G "Visual Studio 14 2015 Win64" \
241 "-DCMAKE_INSTALL_PREFIX=C:\mongo-c-driver" \
242 "-DCMAKE_PREFIX_PATH=C:\mongo-c-driver" \
243 ..
244 (Run cmake -LH .. for a list of other options.)
246 Now that we have project files generated, we can either open the
248 project in Visual Studio or compile from the command line. Let's build
249 using the command line program msbuild.exe:
250 $ msbuild.exe /p:Configuration=RelWithDebInfo ALL_BUILD.vcxproj
252 Visual Studio's default build type is Debug, but we recommend a release
254 build with debug info for production use. Now that libmongoc and libb‐
255 son are compiled, let's install them using msbuild. It will be
256 installed to the path specified by CMAKE_INSTALL_PREFIX.
257 $ msbuild.exe INSTALL.vcxproj
259 You should now see libmongoc and libbson installed in C:\mongo-c-driver
261 To use the driver libraries in your program, see visual-studio-guide.
263
265 Install MSYS2 from msys2.github.io. Choose the x86_64 version, not
266 i686.
267 Open the MingGW shell with c:\msys64\ming64.exe (not the msys2_shell).
269 Install dependencies:
270 $ pacman --noconfirm -Syu
272 $ pacman --noconfirm -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake
273 $ pacman --noconfirm -S mingw-w64-x86_64-extra-cmake-modules make tar
274 $ pacman --noconfirm -S mingw64/mingw-w64-x86_64-cyrus-sasl
275 Download and untar the latest tarball.
277 $ curl -LO https://github.com/mongodb/mongo-c-driver/releases/download/x.y.z/mongo-c-driver-x.y.z.tar.gz
279 $ tar xzf mongo-c-driver-x.y.z.tar.gz
280 $ cd mongo-c-driver-x.y.z
281 Create a build directory and build and install with cmake:
283 $ mkdir cmake-build
285 $ cd cmake-build
286 $ CC=/mingw64/bin/gcc.exe /mingw64/bin/cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX="C:/mongo-c-driver" -DCMAKE_C_FLAGS="-D__USE_MINGW_ANSI_STDIO=1" ..
287 $ make install
288
290 In the event that you are building the BSON library and/or the C driver
291 to embed with other components and you wish to avoid the potential for
292 collision with components installed from a standard build or from a
293 distribution package manager, you can make use of the BSON_OUTPUT_BASE‐
294 NAME and MONGOC_OUTPUT_BASENAME options to cmake.
295 $ mkdir cmake-build
297 $ cd cmake-build
298 $ cmake -DBSON_OUTPUT_BASENAME=custom_bson -DMONGOC_OUTPUT_BASENAME=custom_mongoc ..
299 The above command would produce libraries named libcustom_bson.so and
301 libcustom_mongoc.so (or with the extension appropriate for the build
302 platform). Those libraries could be placed in a standard system direc‐
303 tory or in an alternate location and could be linked to by specifying
304 something like -lcustom_mongoc -lcustom_bson on the linker command line
305 (possibly adjusting the specific flags to those required by your
306 linker).
307
309 MongoDB, Inc
310
312 2017-present, MongoDB, Inc
3131.16.2 Feb 25, 2020 MONGOC_INSTALLING(3)