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, 11.0
20 • macOS 10.14 (Will be dropped in an upcoming release)
22 • macOS 11.0 (x86_64 and arm64)
24 • Microsoft Windows Server 2008, 2016
26 • RHEL 7.0, 7.1, 8.1, 8.2, 8.3
28 • Ubuntu 16.04, 18.04, 20.04
30 • Clang 3.4, 3.5, 3.7, 3.8, 6.0
32 • GCC 4.8, 4.9, 5.4, 6.3, 7.5, 8.2, 8.3, 9.4, 10.2
34 • MinGW-W64
36 • Visual Studio 2013, 2015, 2017
38 • x86, x86_64, ARM (aarch64), Power8 (ppc64le), zSeries (s390x)
40
42 Several Linux distributions provide packages for libmongoc and its de‐
43 pendencies. One advantage of installing libmongoc with a package man‐
44 ager is that its dependencies (including libbson) will be installed au‐
45 tomatically. If you choose to install libmongoc from distribution pack‐
46 ages, use the package manager to confirm the version being installed is
47 sufficient for your needs.
48 The libmongoc package is available on recent versions of Debian and
50 Ubuntu.
51 $ apt-get install libmongoc-dev
53 The libmongoc-dev package includes headers required to build applica‐
55 tions using libmongoc. To check which version is available, run
56 apt-cache policy libmongoc-dev. To only install the libraries without
57 headers, install the libmongoc-1.0-0 package.
58 On Fedora, a mongo-c-driver package is available in the default reposi‐
60 tories and can be installed with:
61 $ dnf install mongo-c-driver-devel
63 The mongo-c-driver-devel package includes headers required to build ap‐
65 plications using libmongoc. To check which version is available, see
66 https://packages.fedoraproject.org/pkgs/mongo-c-driver/mongo-c-driver-devel.
67 To only install the libraries without headers, install the
68 mongo-c-driver package.
69 On recent Red Hat systems, such as CentOS and RHEL 7, a
71 mongo-c-driver-devel package is available in the EPEL repository. The
72 package can be installed with:
73 $ yum install mongo-c-driver-devel
75 On macOS systems with Homebrew, the mongo-c-driver package can be in‐
77 stalled with:
78 $ brew install mongo-c-driver
80
82 The libbson package is available on recent versions of Debian and
83 Ubuntu. If you have installed libmongoc, then libbson will have already
84 been installed as a dependency. It is also possible to install libbson
85 without libmongoc.
86 $ apt-get install libbson-dev
88 The libbson-dev package includes headers required to build applications
90 using libbson. To check which version is available, run apt-cache pol‐
91 icy libbson-dev. To only install the libraries without headers, install
92 the libbson-1.0-0 package.
93 On Fedora, a libbson package is available in the default repositories
95 and can be installed with:
96 $ dnf install libbson-devel
98 The libbson-devel package includes headers required to build applica‐
100 tions using libbson. To check which version is available, see
101 https://packages.fedoraproject.org/pkgs/mongo-c-driver/libbson-devel.
102 To only install the libraries without headers, install the libbson
103 package.
104 On recent Red Hat systems, such as CentOS and RHEL 7, a libbson package
106 is available in the EPEL repository. The package can be installed
107 with:
108 $ yum install libbson-devel
110
112 Build environment on Unix
113 Prerequisites for libmongoc
114 OpenSSL is required for authentication or for TLS connections to Mon‐
115 goDB. Kerberos or LDAP support requires Cyrus SASL.
116 To install all optional dependencies on RedHat / Fedora:
118 $ sudo yum install cmake openssl-devel cyrus-sasl-devel
120 On Debian / Ubuntu:
122 $ sudo apt-get install cmake libssl-dev libsasl2-dev
124 On FreeBSD:
126 $ su -c 'pkg install cmake openssl cyrus-sasl'
128 Prerequisites for libbson
130 The only prerequisite for building libbson is cmake. The command lines
131 above can be adjusted to install only cmake.
132 Build environment on macOS
134 Install the XCode Command Line Tools:
135 $ xcode-select --install
137 The cmake utility is also required. First install Homebrew according to
139 its instructions, then:
140 $ brew install cmake
142 Build environment on Windows with Visual Studio
144 Building on Windows requires Windows Vista or newer and Visual Studio
145 2013 or newer. Additionally, cmake is required to generate Visual Stu‐
146 dio project files. Installation of these components on Windows is be‐
147 yond the scope of this document.
148 Build environment on Windows with MinGW-W64 and MSYS2
150 Install MSYS2 from msys2.github.io. Choose the x86_64 version, not
151 i686.
152 Open the MingGW shell with c:\msys64\ming64.exe (not the msys2_shell).
154 Install dependencies:
155 $ pacman --noconfirm -Syu
157 $ pacman --noconfirm -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake
158 $ pacman --noconfirm -S mingw-w64-x86_64-extra-cmake-modules make tar
159 $ pacman --noconfirm -S mingw64/mingw-w64-x86_64-cyrus-sasl
160
162 Before building libmongoc and/or libbson, it is necessary to configure,
163 or prepare, the build. The steps to prepare the build depend on how
164 you obtained the source code and the build platform.
165 Preparing a build from a release tarball
167 The most recent release of libmongoc and libbson, both of which are in‐
168 cluded in mongo-c-driver, can be downloaded here. The instructions in
169 this document utilize cmake's out-of-source build feature to keep build
170 artifacts separate from source files. While the $ prompt is used
171 throughout, the instructions below will work on Linux, macOS, and Win‐
172 dows (assuming that CMake is in the user's shell path in all cases).
173 See the subsequent sections for additional platform-specific instruc‐
174 tions.
175 The following snippet will download and extract the driver, and config‐
177 ure it:
178 $ wget https://github.com/mongodb/mongo-c-driver/releases/download/1.24.3/mongo-c-driver-1.24.3.tar.gz
180 $ tar xzf mongo-c-driver-1.24.3.tar.gz
181 $ cd mongo-c-driver-1.24.3
182 $ mkdir cmake-build
183 $ cd cmake-build
184 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..
185 The -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF option is recommended, see
187 Initialization and cleanup. Another useful cmake option is -DC‐
188 MAKE_BUILD_TYPE=Release for a release optimized build and -DC‐
189 MAKE_BUILD_TYPE=Debug for a debug build. For a list of all configure
190 options, run cmake -L ...
191 If cmake completed successfully, you will see a considerable amount of
193 output describing your build configuration. The final line of output
194 should look something like this:
195 -- Build files have been written to: /home/user/mongo-c-driver-1.24.3/cmake-build
197 If cmake concludes with anything different, then it is likely an error
199 occurred.
200 mongo-c-driver contains a copy of libbson, in case your system does not
202 already have libbson installed. The configuration will detect if libb‐
203 son is not installed and use the bundled libbson.
204 Additionally, it is possible to build only libbson by setting the -DEN‐
206 ABLE_MONGOC=OFF option:
207 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF -DENABLE_MONGOC=OFF ..
209 A build configuration description similar to the one above will be dis‐
211 played, though with fewer entries. Once the configuration is complete,
212 the selected items can be built and installed with these commands:
213 Preparing a build from a git repository clone
215 Clone the repository and prepare the build on the current branch or a
216 particular release tag:
217 $ git clone https://github.com/mongodb/mongo-c-driver.git
219 $ cd mongo-c-driver
220 $ git checkout 1.24.3 # To build a particular release
221 $ python build/calc_release_version.py > VERSION_CURRENT
222 $ mkdir cmake-build
223 $ cd cmake-build
224 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..
225 Preparing a build on Windows with Visual Studio
227 On the Windows platform with Visual Studio, it may be necessary to
228 specify the CMake generator to use. This is especially important if
229 multiple versions of Visual Studio are installed on the system or if
230 alternate build tools (e.g., MinGW, MSYS2, Cygwin, etc.) are present on
231 the system. Specifying the generator will ensure that the build con‐
232 figuration is known with certainty, rather than relying on the
233 toolchain that CMake happens to find.
234 Start by generating Visual Studio project files. The following assumes
236 you are compiling for 64-bit Windows using Visual Studio 2015 Express,
237 which can be freely downloaded from Microsoft. The sample commands uti‐
238 lize cmake's out-of-source build feature to keep build artifacts sepa‐
239 rate from source files.
240 $ cd mongo-c-driver-1.24.3
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 To see a complete list of the CMake generators available on your spe‐
252 cific system, use a command like this:
253 $ cmake --help
255
257 Building on Unix, macOS, and Windows (MinGW-W64 and MSYS2)
258 $ cmake --build .
259 $ sudo cmake --build . --target install
260 (Note that the sudo command may not be applicable or available depend‐
262 ing on the configuration of your system.)
263 In the above commands, the first relies on the default target which
265 builds all configured components. For fine grained control over what
266 gets built, the following command can be used (for Ninja and Make‐
267 file-based build systems) to list all available targets:
268 $ cmake --build . help
270 Building on Windows with Visual Studio
272 Once the project files are generated, the project can be opened di‐
273 rectly in Visual Studio or compiled from the command line.
274 Build using the CMake build tool mode:
276 $ cmake --build . --config RelWithDebInfo
278 Visual Studio's default build type is Debug, but we recommend a release
280 build with debug info for production use. Now that libmongoc and libb‐
281 son are compiled, install them. Components will be installed to the
282 path specified by CMAKE_INSTALL_PREFIX.
283 $ cmake --build . --config RelWithDebInfo --target install
285 You should now see libmongoc and libbson installed in C:\mongo-c-driver
287 For Visual Studio 2019 (16.4 and newer), this command can be used to
289 list all available targets:
290 $ cmake --build . -- /targets
292 Alternately, you can examine the files matching the glob *.vcxproj in
294 the cmake-build directory.
295 To use the driver libraries in your program, see Using libmongoc in a
297 Microsoft Visual Studio project.
298 Generating the documentation
300 Install Sphinx, then:
301 $ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
303 $ cmake --build . --target mongoc-doc
304 To build only the libbson documentation:
306 $ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
308 $ cmake --build . --target bson-doc
309 The -DENABLE_MAN_PAGES=ON and -DENABLE_HTML_DOCS=ON can also be added
311 as options to a normal build from a release tarball or from git so that
312 the documentation is built at the same time as other components.
313 Uninstalling the installed components
315 There are two ways to uninstall the components that have been in‐
316 stalled. The first is to invoke the uninstall program directly. On
317 Linux/Unix:
318 $ sudo /usr/local/share/mongo-c-driver/uninstall.sh
320 On Windows:
322 $ C:\mongo-c-driver\share\mongo-c-driver\uninstall.bat
324 The second way to uninstall is from within the build directory, assum‐
326 ing that it is in the exact same state as when the install command was
327 invoked:
328 $ sudo cmake --build . --target uninstall
330 The second approach simply invokes the uninstall program referenced in
332 the first approach.
333 Dealing with Build Failures
335 If your attempt to build the C driver fails, please see the README for
336 instructions on requesting assistance.
337
339 In the event that you are building the BSON library and/or the C driver
340 to embed with other components and you wish to avoid the potential for
341 collision with components installed from a standard build or from a
342 distribution package manager, you can make use of the BSON_OUTPUT_BASE‐
343 NAME and MONGOC_OUTPUT_BASENAME options to cmake.
344 $ cmake -DBSON_OUTPUT_BASENAME=custom_bson -DMONGOC_OUTPUT_BASENAME=custom_mongoc ..
346 The above command would produce libraries named libcustom_bson.so and
348 libcustom_mongoc.so (or with the extension appropriate for the build
349 platform). Those libraries could be placed in a standard system direc‐
350 tory or in an alternate location and could be linked to by specifying
351 something like -lcustom_mongoc -lcustom_bson on the linker command line
352 (possibly adjusting the specific flags to those required by your
353 linker).
354
356 MongoDB, Inc
357
359 2017-present, MongoDB, Inc
3601.24.3 Aug 17, 2023 MONGOC_INSTALLING(3)