mongoc_installing - Installing the MongoDB C Driver (libmongoc) and BSON library (libbson)

Additional Options For Integrators

       In  the  event  that you are building the BSON library and/or the C driver to embed with other components
       and you wish to avoid the potential for collision with components installed from a standard build or from
       a distribution package manager, you can make use of the BSON_OUTPUT_BASENAME  and  MONGOC_OUTPUT_BASENAME
       options to cmake.

          $ cmake -DBSON_OUTPUT_BASENAME=custom_bson -DMONGOC_OUTPUT_BASENAME=custom_mongoc ..

       The  above  command  would produce libraries named libcustom_bson.so and libcustom_mongoc.so (or with the
       extension appropriate for the build platform).  Those libraries could be  placed  in  a  standard  system
       directory or in an alternate location and could be linked to by specifying something like -lcustom_mongoc-lcustom_bson on the linker command line (possibly adjusting the specific flags to those required by your
       linker).

Author

       MongoDB, Inc

Build Environment

BuildenvironmentonUnixPrerequisitesforlibmongoc
OpenSSL is required for authentication or for TLS connections to MongoDB. Kerberos or LDAP support
requires Cyrus SASL.

To install all optional dependencies on RedHat / Fedora:

$ sudo yum install cmake openssl-devel cyrus-sasl-devel

On Debian / Ubuntu:

$ sudo apt-get install cmake libssl-dev libsasl2-dev

On FreeBSD:

$ su -c 'pkg install cmake openssl cyrus-sasl'

Prerequisitesforlibbson
The only prerequisite for building libbson is cmake. The command lines above can be adjusted to install
only cmake.

BuildenvironmentonmacOS
Install the XCode Command Line Tools:

$ xcode-select --install

The cmake utility is also required. First installHomebrewaccordingtoitsinstructions, then:

$ brew install cmake

BuildenvironmentonWindowswithVisualStudio
Building on Windows requires Windows Vista or newer and Visual Studio 2010 or newer. Additionally, cmake
is required to generate Visual Studio project files. Installation of these components on Windows is
beyond the scope of this document.

BuildenvironmentonWindowswithMinGW-W64andMSYS2
Install MSYS2 from msys2.github.io. Choose the x86_64 version, not i686.

Open the MingGW shell with c:\msys64\ming64.exe (not the msys2_shell). Install dependencies:

$ pacman --noconfirm -Syu
$ pacman --noconfirm -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake
$ pacman --noconfirm -S mingw-w64-x86_64-extra-cmake-modules make tar
$ pacman --noconfirm -S mingw64/mingw-w64-x86_64-cyrus-sasl

Configuring The Build

       Before building libmongoc and/or libbson, it is necessary to configure, or prepare, the build.  The steps
       to prepare the build depend on how you obtained the source code and the build platform.

   Preparingabuildfromareleasetarball
       The  most  recent  release of libmongoc and libbson, both of which are included in mongo-c-driver, can be
       downloadedhere. The instructions in this document utilize cmake's out-of-source build  feature  to  keep
       build artifacts separate from source files. While the $ prompt is used throughout, the instructions below
       will  work  on  Linux, macOS, and Windows (assuming that CMake is in the user's shell path in all cases).
       See the subsequent sections for additional platform-specific instructions.

       The following snippet will download and extract the driver, and configure it:

          $ wget https://github.com/mongodb/mongo-c-driver/releases/download/1.21.0/mongo-c-driver-1.21.0.tar.gz
          $ tar xzf mongo-c-driver-1.21.0.tar.gz
          $ cd mongo-c-driver-1.21.0
          $ mkdir cmake-build
          $ cd cmake-build
          $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..

       The-DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFFoptionisrecommended,seeinit-cleanup.Anotherusefulcmakeoptionis-DCMAKE_BUILD_TYPE=Releaseforareleaseoptimizedbuildand-DCMAKE_BUILD_TYPE=Debugforadebugbuild.Foralistofallconfigureoptions,runcmake-L...Ifcmakecompletedsuccessfully,youwillseeaconsiderableamountofoutputdescribingyourbuildconfiguration.Thefinallineofoutputshouldlooksomethinglikethis:--Buildfileshavebeenwrittento:/home/user/mongo-c-driver-1.21.0/cmake-buildIfcmakeconcludeswithanythingdifferent,thenitislikelyanerroroccurred.mongo-c-drivercontainsacopyoflibbson,incaseyoursystemdoesnotalreadyhavelibbsoninstalled.Theconfigurationwilldetectiflibbsonisnotinstalledandusethebundledlibbson.Additionally,itispossibletobuildonlylibbsonbysettingthe-DENABLE_MONGOC=OFFoption:$cmake-DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF-DENABLE_MONGOC=OFF..Abuildconfigurationdescriptionsimilartotheoneabovewillbedisplayed,thoughwithfewerentries.Oncetheconfigurationiscomplete,theselecteditemscanbebuiltandinstalledwiththesecommands:Preparingabuildfromagitrepositoryclone
       Clone the repository and prepare the build on the current branch or a particular release tag:

          $ git clone https://github.com/mongodb/mongo-c-driver.git
          $ cd mongo-c-driver
          $ git checkout 1.21.0  # To build a particular release
          $ python build/calc_release_version.py > VERSION_CURRENT
          $ mkdir cmake-build
          $ cd cmake-build
          $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..

   PreparingabuildonWindowswithVisualStudio
       On the Windows platform with Visual Studio, it may be necessary to specify the CMake  generator  to  use.
       This  is  especially  important  if  multiple versions of Visual Studio are installed on the system or if
       alternate build tools (e.g., MinGW, MSYS2, Cygwin, etc.) are  present  on  the  system.   Specifying  the
       generator  will  ensure  that the build configuration is known with certainty, rather than relying on the
       toolchain that CMake happens to find.

       Start by generating Visual Studio project files. The following  assumes  you  are  compiling  for  64-bit
       Windows  using  Visual  Studio  2015  Express,  which can be freely downloaded from Microsoft. The sample
       commands utilize cmake's out-of-source build feature to keep build artifacts separate from source files.

          $ cd mongo-c-driver-1.21.0
          $ mkdir cmake-build
          $ cd cmake-build
          $ cmake -G "Visual Studio 14 2015 Win64" \
              "-DCMAKE_INSTALL_PREFIX=C:\mongo-c-driver" \
              "-DCMAKE_PREFIX_PATH=C:\mongo-c-driver" \
              ..

       (Run cmake-LH.. for a list of other options.)

       To see a complete list of the CMake generators available on your specific  system,  use  a  command  like
       this:

          $ cmake --help

Copyright

       2017-present, MongoDB, Inc

1.21.0                                            Feb 09, 2022                              MONGOC_INSTALLING(3)

Executing A Build

BuildingonUnix,macOS,andWindows(MinGW-W64andMSYS2)
$ cmake --build .
$ sudo cmake --build . --target install

(Note that the sudo command may not be applicable or available depending on the configuration of your
system.)

In the above commands, the first relies on the default target which builds all configured components.
For fine grained control over what gets built, the following command can be used (for Ninja and
Makefile-based build systems) to list all available targets:

$ cmake --build . help

BuildingonWindowswithVisualStudio
Once the project files are generated, the project can be opened directly in Visual Studio or compiled
from the command line.

Build using the CMake build tool mode:

$ cmake --build . --config RelWithDebInfo

Visual Studio's default build type is Debug, but we recommend a release build with debug info for
production use. Now that libmongoc and libbson are compiled, install them. Components will be installed
to the path specified by CMAKE_INSTALL_PREFIX.

$ cmake --build . --config RelWithDebInfo --target install

You should now see libmongoc and libbson installed in C:\mongo-c-driver

For Visual Studio 2019 (16.4 and newer), this command can be used to list all available targets:

$ cmake --build . -- /targets

Alternately, you can examine the files matching the glob *.vcxproj in the cmake-build directory.

To use the driver libraries in your program, see visual-studio-guide.

Generatingthedocumentation
Install Sphinx, then:

$ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
$ cmake --build . --target mongoc-doc

To build only the libbson documentation:

$ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
$ cmake --build . --target bson-doc

The -DENABLE_MAN_PAGES=ON and -DENABLE_HTML_DOCS=ON can also be added as options to a normal build from a
release tarball or from git so that the documentation is built at the same time as other components.

Uninstallingtheinstalledcomponents
There are two ways to uninstall the components that have been installed. The first is to invoke the
uninstall program directly. On Linux/Unix:

$ sudo /usr/local/share/mongo-c-driver/uninstall.sh

On Windows:

$ C:\mongo-c-driver\share\mongo-c-driver\uninstall.bat

The second way to uninstall is from within the build directory, assuming that it is in the exact same
state as when the install command was invoked:

$ sudo cmake --build . --target uninstall

The second approach simply invokes the uninstall program referenced in the first approach.

DealingwithBuildFailures
If your attempt to build the C driver fails, please see the README<https://github.com/mongodb/mongo-c-driver#how-to-ask-for-help> for instructions on requesting
assistance.

Install Libbson With A Package Manager

       The  libbson  package  is  available  on  recent  versions  of  Debian  and Ubuntu. If you have installed
       libmongoc, then libbson will have already been installed as a dependency. It is also possible to  install
       libbson without libmongoc.

          $ apt-get install libbson-1.0-0

       On Fedora, a libbson package is available in the default repositories and can be installed with:

          $ dnf install libbson

       On  recent  Red  Hat  systems,  such  as  CentOS  and  RHEL 7, a libbson package is available in the EPEL
       repository. To check which version  is  available,  see  https://apps.fedoraproject.org/packages/libbson.
       The package can be installed with:

          $ yum install libbson

Install Libmongoc With A Package Manager

       Several Linux distributions provide packages  for  libmongoc  and  its  dependencies.  One  advantage  of
       installing  libmongoc  with  a  package  manager  is  that  its  dependencies (including libbson) will be
       installed automatically. If you choose to install libmongoc from distribution packages, use  the  package
       manager to confirm the version being installed is sufficient for your needs.

       The libmongoc package is available on recent versions of Debian and Ubuntu.

          $ apt-get install libmongoc-1.0-0

       On Fedora, a mongo-c-driver package is available in the default repositories and can be installed with:

          $ dnf install mongo-c-driver

       On  recent  Red Hat systems, such as CentOS and RHEL 7, a mongo-c-driver package is available in the EPEL
       repository.        To        check        which         version         is         available,         see
       https://apps.fedoraproject.org/packages/mongo-c-driver. The package can be installed with:

          $ yum install mongo-c-driver

       On macOS systems with Homebrew, the mongo-c-driver package can be installed with:

          $ brew install mongo-c-driver

Name

       mongoc_installing - Installing the MongoDB C Driver (libmongoc) and BSON library (libbson)

       The  following  guide  will  step  you  through  the process of downloading, building, and installing the
       current release of the MongoDB C Driver (libmongoc) and BSON library (libbson).

Supported Platforms

       The MongoDB C Driver is continuouslytested on a variety of platforms including:

       • Archlinux

       • Debian 9.2, 10.0

       • macOS 10.14

       • Microsoft Windows Server 2008, 2016

       • RHEL 6.2, 7.0, 7.1, 8.2

       • Ubuntu 16.04, 18.04

       • Clang 3.4, 3.5, 3.7, 3.8, 6.0

       • GCC 4.8, 4.9, 5.4, 6.3, 8.2, 8.3

       • MinGW-W64

       • Visual Studio 2013, 2015, 2017

       • x86, x86_64, ARM (aarch64), Power8 (ppc64le), zSeries (s390x)