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 a variety of platforms
15 including:
16 • Archlinux
18 • Debian 9.2, 10.0
20 • macOS 10.14
22 • Microsoft Windows Server 2008, 2016
24 • RHEL 6.2, 7.0, 7.1, 8.2
26 • Ubuntu 16.04, 18.04
28 • Clang 3.4, 3.5, 3.7, 3.8, 6.0
30 • GCC 4.8, 4.9, 5.4, 6.3, 8.2, 8.3
32 • MinGW-W64
34 • Visual Studio 2013, 2015, 2017
36 • x86, x86_64, ARM (aarch64), Power8 (ppc64le), zSeries (s390x)
38
40 Several Linux distributions provide packages for libmongoc and its de‐
41 pendencies. One advantage of installing libmongoc with a package man‐
42 ager is that its dependencies (including libbson) will be installed au‐
43 tomatically. If you choose to install libmongoc from distribution pack‐
44 ages, use the package manager to confirm the version being installed is
45 sufficient for your needs.
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 On macOS systems with Homebrew, the mongo-c-driver package can be in‐
65 stalled with:
66 $ brew install mongo-c-driver
68
70 The libbson package is available on recent versions of Debian and
71 Ubuntu. If you have installed libmongoc, then libbson will have already
72 been installed as a dependency. It is also possible to install libbson
73 without libmongoc.
74 $ apt-get install libbson-1.0-0
76 On Fedora, a libbson package is available in the default repositories
78 and can be installed with:
79 $ dnf install libbson
81 On recent Red Hat systems, such as CentOS and RHEL 7, a libbson package
83 is available in the EPEL repository. To check which version is avail‐
84 able, see https://apps.fedoraproject.org/packages/libbson. The package
85 can be installed with:
86 $ yum install libbson
88
90 Build environment on Unix
91 Prerequisites for libmongoc
92 OpenSSL is required for authentication or for TLS connections to Mon‐
93 goDB. Kerberos or LDAP support requires Cyrus SASL.
94 To install all optional dependencies on RedHat / Fedora:
96 $ sudo yum install cmake openssl-devel cyrus-sasl-devel
98 On Debian / Ubuntu:
100 $ sudo apt-get install cmake libssl-dev libsasl2-dev
102 On FreeBSD:
104 $ su -c 'pkg install cmake openssl cyrus-sasl'
106 Prerequisites for libbson
108 The only prerequisite for building libbson is cmake. The command lines
109 above can be adjusted to install only cmake.
110 Build environment on macOS
112 Install the XCode Command Line Tools:
113 $ xcode-select --install
115 The cmake utility is also required. First install Homebrew according to
117 its instructions, then:
118 $ brew install cmake
120 Build environment on Windows with Visual Studio
122 Building on Windows requires Windows Vista or newer and Visual Studio
123 2010 or newer. Additionally, cmake is required to generate Visual Stu‐
124 dio project files. Installation of these components on Windows is be‐
125 yond the scope of this document.
126 Build environment on Windows with MinGW-W64 and MSYS2
128 Install MSYS2 from msys2.github.io. Choose the x86_64 version, not
129 i686.
130 Open the MingGW shell with c:\msys64\ming64.exe (not the msys2_shell).
132 Install dependencies:
133 $ pacman --noconfirm -Syu
135 $ pacman --noconfirm -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake
136 $ pacman --noconfirm -S mingw-w64-x86_64-extra-cmake-modules make tar
137 $ pacman --noconfirm -S mingw64/mingw-w64-x86_64-cyrus-sasl
138
140 Before building libmongoc and/or libbson, it is necessary to configure,
141 or prepare, the build. The steps to prepare the build depend on how
142 you obtained the source code and the build platform.
143 Preparing a build from a release tarball
145 The most recent release of libmongoc and libbson, both of which are in‐
146 cluded in mongo-c-driver, can be downloaded here. The instructions in
147 this document utilize cmake's out-of-source build feature to keep build
148 artifacts separate from source files. While the $ prompt is used
149 throughout, the instructions below will work on Linux, macOS, and Win‐
150 dows (assuming that CMake is in the user's shell path in all cases).
151 See the subsequent sections for additional platform-specific instruc‐
152 tions.
153 The following snippet will download and extract the driver, and config‐
155 ure it:
156 $ wget https://github.com/mongodb/mongo-c-driver/releases/download/1.20.0/mongo-c-driver-1.20.0.tar.gz
158 $ tar xzf mongo-c-driver-1.20.0.tar.gz
159 $ cd mongo-c-driver-1.20.0
160 $ mkdir cmake-build
161 $ cd cmake-build
162 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..
163 The -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF option is recommended, see
165 init-cleanup. Another useful cmake option is -DCMAKE_BUILD_TYPE=Release
166 for a release optimized build and -DCMAKE_BUILD_TYPE=Debug for a debug
167 build. For a list of all configure options, run cmake -L ...
168 If cmake completed successfully, you will see a considerable amount of
170 output describing your build configuration. The final line of output
171 should look something like this:
172 -- Build files have been written to: /home/user/mongo-c-driver-1.20.0/cmake-build
174 If cmake concludes with anything different, then it is likely an error
176 occurred.
177 mongo-c-driver contains a copy of libbson, in case your system does not
179 already have libbson installed. The configuration will detect if libb‐
180 son is not installed and use the bundled libbson.
181 Additionally, it is possible to build only libbson by setting the -DEN‐
183 ABLE_MONGOC=OFF option:
184 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF -DENABLE_MONGOC=OFF ..
186 A build configuration description similar to the one above will be dis‐
188 played, though with fewer entries. Once the configuration is complete,
189 the selected items can be built and installed with these commands:
190 Preparing a build from a git repository clone
192 Clone the repository and prepare the build on the current branch or a
193 particular release tag:
194 $ git clone https://github.com/mongodb/mongo-c-driver.git
196 $ cd mongo-c-driver
197 $ git checkout 1.20.0 # To build a particular release
198 $ python build/calc_release_version.py > VERSION_CURRENT
199 $ mkdir cmake-build
200 $ cd cmake-build
201 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..
202 Preparing a build on Windows with Visual Studio
204 On the Windows platform with Visual Studio, it may be necessary to
205 specify the CMake generator to use. This is especially important if
206 multiple versions of Visual Studio are installed on the system or if
207 alternate build tools (e.g., MinGW, MSYS2, Cygwin, etc.) are present on
208 the system. Specifying the generator will ensure that the build con‐
209 figuration is known with certainty, rather than relying on the
210 toolchain that CMake happens to find.
211 Start by generating Visual Studio project files. The following assumes
213 you are compiling for 64-bit Windows using Visual Studio 2015 Express,
214 which can be freely downloaded from Microsoft. The sample commands uti‐
215 lize cmake's out-of-source build feature to keep build artifacts sepa‐
216 rate from source files.
217 $ cd mongo-c-driver-1.20.0
219 $ mkdir cmake-build
220 $ cd cmake-build
221 $ cmake -G "Visual Studio 14 2015 Win64" \
222 "-DCMAKE_INSTALL_PREFIX=C:\mongo-c-driver" \
223 "-DCMAKE_PREFIX_PATH=C:\mongo-c-driver" \
224 ..
225 (Run cmake -LH .. for a list of other options.)
227 To see a complete list of the CMake generators available on your spe‐
229 cific system, use a command like this:
230 $ cmake --help
232
234 Building on Unix, macOS, and Windows (MinGW-W64 and MSYS2)
235 $ cmake --build .
236 $ sudo cmake --build . --target install
237 (Note that the sudo command may not be applicable or available depend‐
239 ing on the configuration of your system.)
240 In the above commands, the first relies on the default target which
242 builds all configured components. For fine grained control over what
243 gets built, the following command can be used (for Ninja and Make‐
244 file-based build systems) to list all available targets:
245 $ cmake --build . help
247 Building on Windows with Visual Studio
249 Once the project files are generated, the project can be opened di‐
250 rectly in Visual Studio or compiled from the command line.
251 Build using the CMake build tool mode:
253 $ cmake --build . --config RelWithDebInfo
255 Visual Studio's default build type is Debug, but we recommend a release
257 build with debug info for production use. Now that libmongoc and libb‐
258 son are compiled, install them. Components will be installed to the
259 path specified by CMAKE_INSTALL_PREFIX.
260 $ cmake --build . --config RelWithDebInfo --target install
262 You should now see libmongoc and libbson installed in C:\mongo-c-driver
264 For Visual Studio 2019 (16.4 and newer), this command can be used to
266 list all available targets:
267 $ cmake --build . -- /targets
269 Alternately, you can examine the files matching the glob *.vcxproj in
271 the cmake-build directory.
272 To use the driver libraries in your program, see visual-studio-guide.
274 Generating the documentation
276 Install Sphinx, then:
277 $ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
279 $ cmake --build . --target mongoc-doc
280 To build only the libbson documentation:
282 $ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
284 $ cmake --build . --target bson-doc
285 The -DENABLE_MAN_PAGES=ON and -DENABLE_HTML_DOCS=ON can also be added
287 as options to a normal build from a release tarball or from git so that
288 the documentation is built at the same time as other components.
289 Uninstalling the installed components
291 There are two ways to uninstall the components that have been in‐
292 stalled. The first is to invoke the uninstall program directly. On
293 Linux/Unix:
294 $ sudo /usr/local/share/mongo-c-driver/uninstall.sh
296 On Windows:
298 $ C:\mongo-c-driver\share\mongo-c-driver\uninstall.bat
300 The second way to uninstall is from within the build directory, assum‐
302 ing that it is in the exact same state as when the install command was
303 invoked:
304 $ sudo cmake --build . --target uninstall
306 The second approach simply invokes the uninstall program referenced in
308 the first approach.
309 Dealing with Build Failures
311 If your attempt to build the C driver fails, please see the README
312 <https://github.com/mongodb/mongo-c-driver#how-to-ask-for-help> for in‐
313 structions on requesting assistance.
314
316 In the event that you are building the BSON library and/or the C driver
317 to embed with other components and you wish to avoid the potential for
318 collision with components installed from a standard build or from a
319 distribution package manager, you can make use of the BSON_OUTPUT_BASE‐
320 NAME and MONGOC_OUTPUT_BASENAME options to cmake.
321 $ cmake -DBSON_OUTPUT_BASENAME=custom_bson -DMONGOC_OUTPUT_BASENAME=custom_mongoc ..
323 The above command would produce libraries named libcustom_bson.so and
325 libcustom_mongoc.so (or with the extension appropriate for the build
326 platform). Those libraries could be placed in a standard system direc‐
327 tory or in an alternate location and could be linked to by specifying
328 something like -lcustom_mongoc -lcustom_bson on the linker command line
329 (possibly adjusting the specific flags to those required by your
330 linker).
331
333 MongoDB, Inc
334
336 2017-present, MongoDB, Inc
3371.20.0 Nov 18, 2021 MONGOC_INSTALLING(3)