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
60 https://packages.fedoraproject.org/pkgs/mongo-c-driver/mongo-c-driver/.
61 The package can be installed with:
62 $ yum install mongo-c-driver
64 On macOS systems with Homebrew, the mongo-c-driver package can be in‐
66 stalled with:
67 $ brew install mongo-c-driver
69
71 The libbson package is available on recent versions of Debian and
72 Ubuntu. If you have installed libmongoc, then libbson will have already
73 been installed as a dependency. It is also possible to install libbson
74 without libmongoc.
75 $ apt-get install libbson-1.0-0
77 On Fedora, a libbson package is available in the default repositories
79 and can be installed with:
80 $ dnf install libbson
82 On recent Red Hat systems, such as CentOS and RHEL 7, a libbson package
84 is available in the EPEL repository. To check which version is avail‐
85 able, see https://apps.fedoraproject.org/packages/libbson. The package
86 can be installed with:
87 $ yum install libbson
89
91 Build environment on Unix
92 Prerequisites for libmongoc
93 OpenSSL is required for authentication or for TLS connections to Mon‐
94 goDB. Kerberos or LDAP support requires Cyrus SASL.
95 To install all optional dependencies on RedHat / Fedora:
97 $ sudo yum install cmake openssl-devel cyrus-sasl-devel
99 On Debian / Ubuntu:
101 $ sudo apt-get install cmake libssl-dev libsasl2-dev
103 On FreeBSD:
105 $ su -c 'pkg install cmake openssl cyrus-sasl'
107 Prerequisites for libbson
109 The only prerequisite for building libbson is cmake. The command lines
110 above can be adjusted to install only cmake.
111 Build environment on macOS
113 Install the XCode Command Line Tools:
114 $ xcode-select --install
116 The cmake utility is also required. First install Homebrew according to
118 its instructions, then:
119 $ brew install cmake
121 Build environment on Windows with Visual Studio
123 Building on Windows requires Windows Vista or newer and Visual Studio
124 2013 or newer. Additionally, cmake is required to generate Visual Stu‐
125 dio project files. Installation of these components on Windows is be‐
126 yond the scope of this document.
127 Build environment on Windows with MinGW-W64 and MSYS2
129 Install MSYS2 from msys2.github.io. Choose the x86_64 version, not
130 i686.
131 Open the MingGW shell with c:\msys64\ming64.exe (not the msys2_shell).
133 Install dependencies:
134 $ pacman --noconfirm -Syu
136 $ pacman --noconfirm -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake
137 $ pacman --noconfirm -S mingw-w64-x86_64-extra-cmake-modules make tar
138 $ pacman --noconfirm -S mingw64/mingw-w64-x86_64-cyrus-sasl
139
141 Before building libmongoc and/or libbson, it is necessary to configure,
142 or prepare, the build. The steps to prepare the build depend on how
143 you obtained the source code and the build platform.
144 Preparing a build from a release tarball
146 The most recent release of libmongoc and libbson, both of which are in‐
147 cluded in mongo-c-driver, can be downloaded here. The instructions in
148 this document utilize cmake's out-of-source build feature to keep build
149 artifacts separate from source files. While the $ prompt is used
150 throughout, the instructions below will work on Linux, macOS, and Win‐
151 dows (assuming that CMake is in the user's shell path in all cases).
152 See the subsequent sections for additional platform-specific instruc‐
153 tions.
154 The following snippet will download and extract the driver, and config‐
156 ure it:
157 $ wget https://github.com/mongodb/mongo-c-driver/releases/download/1.23.1/mongo-c-driver-1.23.1.tar.gz
159 $ tar xzf mongo-c-driver-1.23.1.tar.gz
160 $ cd mongo-c-driver-1.23.1
161 $ mkdir cmake-build
162 $ cd cmake-build
163 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..
164 The -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF option is recommended, see
166 Initialization and cleanup. Another useful cmake option is -DC‐
167 MAKE_BUILD_TYPE=Release for a release optimized build and -DC‐
168 MAKE_BUILD_TYPE=Debug for a debug build. For a list of all configure
169 options, run cmake -L ...
170 If cmake completed successfully, you will see a considerable amount of
172 output describing your build configuration. The final line of output
173 should look something like this:
174 -- Build files have been written to: /home/user/mongo-c-driver-1.23.1/cmake-build
176 If cmake concludes with anything different, then it is likely an error
178 occurred.
179 mongo-c-driver contains a copy of libbson, in case your system does not
181 already have libbson installed. The configuration will detect if libb‐
182 son is not installed and use the bundled libbson.
183 Additionally, it is possible to build only libbson by setting the -DEN‐
185 ABLE_MONGOC=OFF option:
186 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF -DENABLE_MONGOC=OFF ..
188 A build configuration description similar to the one above will be dis‐
190 played, though with fewer entries. Once the configuration is complete,
191 the selected items can be built and installed with these commands:
192 Preparing a build from a git repository clone
194 Clone the repository and prepare the build on the current branch or a
195 particular release tag:
196 $ git clone https://github.com/mongodb/mongo-c-driver.git
198 $ cd mongo-c-driver
199 $ git checkout 1.23.1 # To build a particular release
200 $ python build/calc_release_version.py > VERSION_CURRENT
201 $ mkdir cmake-build
202 $ cd cmake-build
203 $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..
204 Preparing a build on Windows with Visual Studio
206 On the Windows platform with Visual Studio, it may be necessary to
207 specify the CMake generator to use. This is especially important if
208 multiple versions of Visual Studio are installed on the system or if
209 alternate build tools (e.g., MinGW, MSYS2, Cygwin, etc.) are present on
210 the system. Specifying the generator will ensure that the build con‐
211 figuration is known with certainty, rather than relying on the
212 toolchain that CMake happens to find.
213 Start by generating Visual Studio project files. The following assumes
215 you are compiling for 64-bit Windows using Visual Studio 2015 Express,
216 which can be freely downloaded from Microsoft. The sample commands uti‐
217 lize cmake's out-of-source build feature to keep build artifacts sepa‐
218 rate from source files.
219 $ cd mongo-c-driver-1.23.1
221 $ mkdir cmake-build
222 $ cd cmake-build
223 $ cmake -G "Visual Studio 14 2015 Win64" \
224 "-DCMAKE_INSTALL_PREFIX=C:\mongo-c-driver" \
225 "-DCMAKE_PREFIX_PATH=C:\mongo-c-driver" \
226 ..
227 (Run cmake -LH .. for a list of other options.)
229 To see a complete list of the CMake generators available on your spe‐
231 cific system, use a command like this:
232 $ cmake --help
234
236 Building on Unix, macOS, and Windows (MinGW-W64 and MSYS2)
237 $ cmake --build .
238 $ sudo cmake --build . --target install
239 (Note that the sudo command may not be applicable or available depend‐
241 ing on the configuration of your system.)
242 In the above commands, the first relies on the default target which
244 builds all configured components. For fine grained control over what
245 gets built, the following command can be used (for Ninja and Make‐
246 file-based build systems) to list all available targets:
247 $ cmake --build . help
249 Building on Windows with Visual Studio
251 Once the project files are generated, the project can be opened di‐
252 rectly in Visual Studio or compiled from the command line.
253 Build using the CMake build tool mode:
255 $ cmake --build . --config RelWithDebInfo
257 Visual Studio's default build type is Debug, but we recommend a release
259 build with debug info for production use. Now that libmongoc and libb‐
260 son are compiled, install them. Components will be installed to the
261 path specified by CMAKE_INSTALL_PREFIX.
262 $ cmake --build . --config RelWithDebInfo --target install
264 You should now see libmongoc and libbson installed in C:\mongo-c-driver
266 For Visual Studio 2019 (16.4 and newer), this command can be used to
268 list all available targets:
269 $ cmake --build . -- /targets
271 Alternately, you can examine the files matching the glob *.vcxproj in
273 the cmake-build directory.
274 To use the driver libraries in your program, see Using libmongoc in a
276 Microsoft Visual Studio project.
277 Generating the documentation
279 Install Sphinx, then:
280 $ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
282 $ cmake --build . --target mongoc-doc
283 To build only the libbson documentation:
285 $ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
287 $ cmake --build . --target bson-doc
288 The -DENABLE_MAN_PAGES=ON and -DENABLE_HTML_DOCS=ON can also be added
290 as options to a normal build from a release tarball or from git so that
291 the documentation is built at the same time as other components.
292 Uninstalling the installed components
294 There are two ways to uninstall the components that have been in‐
295 stalled. The first is to invoke the uninstall program directly. On
296 Linux/Unix:
297 $ sudo /usr/local/share/mongo-c-driver/uninstall.sh
299 On Windows:
301 $ C:\mongo-c-driver\share\mongo-c-driver\uninstall.bat
303 The second way to uninstall is from within the build directory, assum‐
305 ing that it is in the exact same state as when the install command was
306 invoked:
307 $ sudo cmake --build . --target uninstall
309 The second approach simply invokes the uninstall program referenced in
311 the first approach.
312 Dealing with Build Failures
314 If your attempt to build the C driver fails, please see the README for
315 instructions on requesting assistance.
316
318 In the event that you are building the BSON library and/or the C driver
319 to embed with other components and you wish to avoid the potential for
320 collision with components installed from a standard build or from a
321 distribution package manager, you can make use of the BSON_OUTPUT_BASE‐
322 NAME and MONGOC_OUTPUT_BASENAME options to cmake.
323 $ cmake -DBSON_OUTPUT_BASENAME=custom_bson -DMONGOC_OUTPUT_BASENAME=custom_mongoc ..
325 The above command would produce libraries named libcustom_bson.so and
327 libcustom_mongoc.so (or with the extension appropriate for the build
328 platform). Those libraries could be placed in a standard system direc‐
329 tory or in an alternate location and could be linked to by specifying
330 something like -lcustom_mongoc -lcustom_bson on the linker command line
331 (possibly adjusting the specific flags to those required by your
332 linker).
333
335 MongoDB, Inc
336
338 2017-present, MongoDB, Inc
3391.23.1 Oct 20, 2022 MONGOC_INSTALLING(3)