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

name
supported platforms
install libmongoc with a package manager
install libbson with a package manager
building on unix
building on macos
building on windows with visual studio
building on windows with mingw-w64 and msys2
additional options for integrators
author
copyright

Provided by: libmongoc-doc_1.16.1-1build2_all

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 continuously tested on variety of platforms including:

       • Archlinux

       • Debian 9.2

       • macOS 10.12

       • Microsoft Windows Server 2008

       • RHEL 7.0, 7.1, 7.2

       • Ubuntu 16.04, 18.04

       • Clang 3.4, 3.5, 3.7, 3.8

       • GCC 4.6, 4.8, 4.9, 5.4, 6.3

       • MinGW-W64

       • Visual Studio 2010, 2013, 2015

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

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.

       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

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

       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

BUILDING ON UNIX

Prerequisites for libmongoc
OpenSSL is required for authentication or for SSL 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'

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

Building from a release tarball
Unless you intend to contribute to mongo-c-driver and/or libbson, you will want to build from a release
tarball.

The most recent release of libmongoc and libbson, both of which are included in mongo-c-driver, can be
downloaded here. The instructions in this document utilize cmake's out-of-source build feature to keep
build artifacts separate from source files.

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

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

The -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF option is recommended, see init-cleanup. Another useful cmake
option is -DCMAKE_BUILD_TYPE=Release for a release optimized build and -DCMAKE_BUILD_TYPE=Debug for a
debug build. For a list of all configure options, run cmake -L ...

If cmake completed successfully, you will see a considerable amount of output describing your build
configuration. The final line of output should look something like this:

-- Build files have been written to: /home/user/mongo-c-driver-x.y.z/cmake-build

If cmake concludes with anything different, then there is likely an error or some other problem with the
build. Review the output to identify and correct the problem.

mongo-c-driver contains a copy of libbson, in case your system does not already have libbson installed.
The build will detect if libbson is not installed and use the bundled libbson.

Additionally, it is possible to build only libbson by setting the -DENABLE_MONGOC=OFF option:

$ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF -DENABLE_MONGOC=OFF ..

A build configuration description similar to the one above will be displayed, though with fewer entries.
Once the configuration is complete, the selected items can be built and installed with these commands:

$ sudo make install

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 make uninstall

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

Building from git
Clone the repository and build the current master or a particular release tag:

$ git clone https://github.com/mongodb/mongo-c-driver.git
$ cd mongo-c-driver
$ git checkout x.y.z # 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 ..
$ sudo make install

Generating the documentation
Install Sphinx, then:

$ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
$ make mongoc-doc

To build only the libbson documentation:

$ cmake -DENABLE_MAN_PAGES=ON -DENABLE_HTML_DOCS=ON ..
$ make 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.

BUILDING ON MACOS

       Install the XCode Command Line Tools:

          $ xcode-select --install

       The cmake utility is also required. First install Homebrew according to its instructions, then:

          $ brew install cmake

       Download the latest release tarball:

          $ curl -LO https://github.com/mongodb/mongo-c-driver/releases/download/x.y.z/mongo-c-driver-x.y.z.tar.gz
          $ tar xzf mongo-c-driver-x.y.z.tar.gz
          $ cd mongo-c-driver-x.y.z

       Build and install the driver:

          $ mkdir cmake-build
          $ cd cmake-build
          $ cmake -DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..
          $ make install

       All of the same variations described above (e.g., building only libbson,  building  documentation,  etc.)
       are available when building on macOS.

BUILDING ON WINDOWS WITH VISUAL STUDIO

Building on Windows requires Windows Vista or newer and Visual Studio 2010 or newer. Additionally, cmake
is required to generate Visual Studio project files.

Let's start by generating Visual Studio project files. The following assumes we are compiling for 64-bit
Windows using Visual Studio 2015 Express, which can be freely downloaded from Microsoft. We will be
utilizing cmake's out-of-source build feature to keep build artifacts separate from source files.

$ cd mongo-c-driver-x.y.z
$ 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.)

Now that we have project files generated, we can either open the project in Visual Studio or compile from
the command line. Let's build using the command line program msbuild.exe:

$ msbuild.exe /p:Configuration=RelWithDebInfo ALL_BUILD.vcxproj

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, let's install them using msbuild. It will be
installed to the path specified by CMAKE_INSTALL_PREFIX.

$ msbuild.exe INSTALL.vcxproj

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

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

BUILDING ON WINDOWS WITH MINGW-W64 AND MSYS2

       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

       Download and untar the latest tarball.

          $ curl -LO https://github.com/mongodb/mongo-c-driver/releases/download/x.y.z/mongo-c-driver-x.y.z.tar.gz
          $ tar xzf mongo-c-driver-x.y.z.tar.gz
          $ cd mongo-c-driver-x.y.z

       Create a build directory and build and install with cmake:

          $ mkdir cmake-build
          $ cd cmake-build
          $ CC=/mingw64/bin/gcc.exe /mingw64/bin/cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX="C:/mongo-c-driver" -DCMAKE_C_FLAGS="-D__USE_MINGW_ANSI_STDIO=1" ..
          $ make install

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.

          $ mkdir cmake-build
          $ cd cmake-build
          $ 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

COPYRIGHT

       2017-present, MongoDB, Inc