1MONGOC_INSTALLING(3)               libmongoc              MONGOC_INSTALLING(3)
2
3
4

NAME

6       mongoc_installing  -  Installing  the  MongoDB C Driver (libmongoc) and
7       BSON library (libbson)
8
9       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

SUPPORTED PLATFORMS

14       The MongoDB C Driver is continuously tested on a variety  of  platforms
15       including:
16
17       • Archlinux
18
19       • Debian 9.2, 10.0
20
21       • macOS 10.14
22
23       • Microsoft Windows Server 2008, 2016
24
25       • RHEL 6.2, 7.0, 7.1, 8.2
26
27       • Ubuntu 16.04, 18.04
28
29       • Clang 3.4, 3.5, 3.7, 3.8, 6.0
30
31       • GCC 4.8, 4.9, 5.4, 6.3, 8.2, 8.3
32
33       • MinGW-W64
34
35       • Visual Studio 2013, 2015, 2017
36
37       • x86, x86_64, ARM (aarch64), Power8 (ppc64le), zSeries (s390x)
38

INSTALL LIBMONGOC WITH A PACKAGE MANAGER

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
47       The libmongoc package is available on recent  versions  of  Debian  and
48       Ubuntu.
49
50          $ apt-get install libmongoc-1.0-0
51
52       On Fedora, a mongo-c-driver package is available in the default reposi‐
53       tories and can be installed with:
54
55          $ dnf install mongo-c-driver
56
57       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
62          $ yum install mongo-c-driver
63
64       On  macOS  systems with Homebrew, the mongo-c-driver package can be in‐
65       stalled with:
66
67          $ brew install mongo-c-driver
68

INSTALL LIBBSON WITH A PACKAGE MANAGER

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
75          $ apt-get install libbson-1.0-0
76
77       On  Fedora,  a libbson package is available in the default repositories
78       and can be installed with:
79
80          $ dnf install libbson
81
82       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
87          $ yum install libbson
88

BUILD ENVIRONMENT

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
95       To install all optional dependencies on RedHat / Fedora:
96
97          $ sudo yum install cmake openssl-devel cyrus-sasl-devel
98
99       On Debian / Ubuntu:
100
101          $ sudo apt-get install cmake libssl-dev libsasl2-dev
102
103       On FreeBSD:
104
105          $ su -c 'pkg install cmake openssl cyrus-sasl'
106
107   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
111   Build environment on macOS
112       Install the XCode Command Line Tools:
113
114          $ xcode-select --install
115
116       The cmake utility is also required. First install Homebrew according to
117       its instructions, then:
118
119          $ brew install cmake
120
121   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
127   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
131       Open the MingGW shell with c:\msys64\ming64.exe (not the  msys2_shell).
132       Install dependencies:
133
134          $ 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

CONFIGURING THE BUILD

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
144   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
154       The following snippet will download and extract the driver, and config‐
155       ure it:
156
157          $ 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
164       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
169       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
173          -- Build files have been written to: /home/user/mongo-c-driver-1.20.0/cmake-build
174
175       If cmake concludes with anything different, then it is likely an  error
176       occurred.
177
178       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
182       Additionally, it is possible to build only libbson by setting the -DEN‐
183       ABLE_MONGOC=OFF option:
184
185          $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF -DENABLE_MONGOC=OFF ..
186
187       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
191   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
195          $ 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
203   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
212       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
218          $ 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
226       (Run cmake -LH .. for a list of other options.)
227
228       To  see  a complete list of the CMake generators available on your spe‐
229       cific system, use a command like this:
230
231          $ cmake --help
232

EXECUTING A BUILD

234   Building on Unix, macOS, and Windows (MinGW-W64 and MSYS2)
235          $ cmake --build .
236          $ sudo cmake --build . --target install
237
238       (Note that the sudo command may not be applicable or available  depend‐
239       ing on the configuration of your system.)
240
241       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
246          $ cmake --build . help
247
248   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
252       Build using the CMake build tool mode:
253
254          $ cmake --build . --config RelWithDebInfo
255
256       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
261          $ cmake --build . --config RelWithDebInfo --target install
262
263       You should now see libmongoc and libbson installed in C:\mongo-c-driver
264
265       For Visual Studio 2019 (16.4 and newer), this command can  be  used  to
266       list all available targets:
267
268          $ cmake --build . -- /targets
269
270       Alternately,  you  can examine the files matching the glob *.vcxproj in
271       the cmake-build directory.
272
273       To use the driver libraries in your program, see visual-studio-guide.
274
275   Generating the documentation
276       Install Sphinx, then:
277
278          $ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
279          $ cmake --build . --target mongoc-doc
280
281       To build only the libbson documentation:
282
283          $ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
284          $ cmake --build . --target bson-doc
285
286       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
290   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
295          $ sudo /usr/local/share/mongo-c-driver/uninstall.sh
296
297       On Windows:
298
299          $ C:\mongo-c-driver\share\mongo-c-driver\uninstall.bat
300
301       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
305          $ sudo cmake --build . --target uninstall
306
307       The second approach simply invokes the uninstall program referenced  in
308       the first approach.
309
310   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

ADDITIONAL OPTIONS FOR INTEGRATORS

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
322          $ cmake -DBSON_OUTPUT_BASENAME=custom_bson -DMONGOC_OUTPUT_BASENAME=custom_mongoc ..
323
324       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

AUTHOR

333       MongoDB, Inc
334
336       2017-present, MongoDB, Inc
337
338
339
340
3411.20.0                           Nov 18, 2021             MONGOC_INSTALLING(3)
Impressum