.\" Man page generated from reStructuredText.
.
.TH "MONGOC_INSTALLING" "3" "Feb 23, 2019" "1.14.0" "MongoDB C Driver"
.SH NAME
mongoc_installing \- Installing the MongoDB C Driver (libmongoc) and BSON library (libbson)
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
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).
.SH SUPPORTED PLATFORMS
.sp
The MongoDB C Driver is \fI\%continuously tested\fP on variety of platforms including:
.INDENT 0.0
.IP \(bu 2
Archlinux
.IP \(bu 2
Debian 8.1
.IP \(bu 2
macOS 10.10
.IP \(bu 2
Microsoft Windows Server 2008
.IP \(bu 2
RHEL 7.0, 7.1, 7.2
.IP \(bu 2
SUSE 12
.IP \(bu 2
Ubuntu 12.04, 14.04, 16.04
.IP \(bu 2
Clang 3.4, 3.5, 3.7, 3.8
.IP \(bu 2
GCC 4.6, 4.8, 4.9, 5.3
.IP \(bu 2
MinGW\-W64
.IP \(bu 2
Visual Studio 2010, 2013, 2015
.IP \(bu 2
x86, x86_64, ARM (aarch64), Power8 (ppc64le), zSeries (s390x)
.UNINDENT
.SH INSTALL LIBMONGOC WITH A PACKAGE MANAGER
.sp
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.
.sp
The libmongoc package is available on recent versions of Debian and Ubuntu.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ apt\-get install libmongoc\-1.0\-0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On Fedora, a mongo\-c\-driver package is available in the default repositories and can be installed with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ dnf install mongo\-c\-driver
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On recent Red Hat systems, such as CentOS and RHEL 7, a mongo\-c\-driver package is available in the \fI\%EPEL\fP repository. To check which version is available, see \fI\%https://apps.fedoraproject.org/packages/mongo\-c\-driver\fP\&. The package can be installed with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ yum install mongo\-c\-driver
.ft P
.fi
.UNINDENT
.UNINDENT
.SH INSTALL LIBBSON WITH A PACKAGE MANAGER
.sp
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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ apt\-get install libbson\-1.0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On Fedora, a libbson package is available in the default repositories and can be installed with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ dnf install libbson
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On recent Red Hat systems, such as CentOS and RHEL 7, a libbson package
is available in the \fI\%EPEL\fP repository. To check
which version is available, see \fI\%https://apps.fedoraproject.org/packages/libbson\fP\&.
The package can be installed with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ yum install libbson
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BUILDING ON UNIX
.SS Prerequisites for libmongoc
.sp
OpenSSL is required for authentication or for SSL connections to MongoDB. Kerberos or LDAP support requires Cyrus SASL.
.sp
To install all optional dependencies on RedHat / Fedora:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ sudo yum install cmake openssl\-devel cyrus\-sasl\-devel
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On Debian / Ubuntu:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ sudo apt\-get install cmake libssl\-dev libsasl2\-dev
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On FreeBSD:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ su \-c \(aqpkg install cmake openssl cyrus\-sasl\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Prerequisites for libbson
.sp
The only prerequisite for building libbson is \fBcmake\fP\&. The command lines above can be adjusted to install only \fBcmake\fP\&.
.SS Building from a release tarball
.sp
Unless you intend to contribute to mongo\-c\-driver and/or libbson, you will want to build from a release tarball.
.sp
The most recent release of libmongoc and libbson, both of which are included in mongo\-c\-driver, can be downloaded here <\fI\%https://github.com/mongodb/mongo\-c\-driver/releases/latest\fP>. The instructions in this document utilize \fBcmake\fP\(aqs out\-of\-source build feature to keep build artifacts separate from source files.
.sp
The following snippet will download and extract the driver, and configure it:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ wget \fI\%https://github.com/mongodb/mongo\-c\-driver/releases/download/x.y.z/mongo\-c\-driver\-x.y.z.tar.gz\fP
$ 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 ..
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fB\-DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF\fP option is recommended, see init\-cleanup\&. Another useful \fBcmake\fP option is \fB\-DCMAKE_BUILD_TYPE=Release\fP for a release optimized build and \fB\-DCMAKE_BUILD_TYPE=Debug\fP for a debug build. For a list of all configure options, run \fBcmake \-L ..\fP\&.
.sp
If \fBcmake\fP completed successfully, you will see a considerable amount of output describing your build configuration. The final line of output should look something like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-\- Build files have been written to: /home/user/mongo\-c\-driver\-x.y.z/cmake\-build
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If \fBcmake\fP 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.
.sp
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.
.sp
Additionally, it is possible to build only libbson by setting the \fB\-DENABLE_MONGOC=OFF\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ cmake \-DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF \-DENABLE_MONGOC=OFF ..
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ make
$ sudo make install
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
There are two ways to uninstall the components that have been installed.  The first is to invoke the uninstall program directly.  On Linux/Unix:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ sudo /usr/local/share/mongo\-c\-driver/uninstall.sh
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On Windows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
C:\eUsers\euser> C:\emongo\-c\-driver\eshare\emongo\-c\-driver\euninstall.bat
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ sudo make uninstall
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The second approach simply invokes the uninstall program referenced in the first approach.
.SS Building from git
.sp
Clone the repository and build the current master or a particular release tag:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ 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 ..
$ make
$ sudo make install
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Generating the documentation
.sp
Install \fI\%Sphinx\fP, then:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ cmake \-DENABLE_MAN_PAGES=ON \-DENABLE_HTML_DOCS=ON ..
$ make mongoc\-doc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To build only the libbson documentation:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ cmake \-DENABLE_MAN_PAGES=ON \-DENABLE_HTML_DOCS=ON ..
$ make bson\-doc
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fB\-DENABLE_MAN_PAGES=ON\fP and \fB\-DENABLE_HTML_DOCS=ON\fP 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.
.SH BUILDING ON MACOS
.sp
Install the XCode Command Line Tools:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ xcode\-select \-\-install
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBcmake\fP utility is also required. First \fI\%install Homebrew according to its instructions\fP, then:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ brew install cmake
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Download the latest release tarball:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ curl \-LO \fI\%https://github.com/mongodb/mongo\-c\-driver/releases/download/x.y.z/mongo\-c\-driver\-x.y.z.tar.gz\fP
$ tar xzf mongo\-c\-driver\-x.y.z.tar.gz
$ cd mongo\-c\-driver\-x.y.z
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Build and install the driver:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ mkdir cmake\-build
$ cd cmake\-build
$ cmake \-DENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF ..
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
All of the same variations described above (e.g., building only libbson, building documentation, etc.) are available when building on macOS.
.SH BUILDING ON WINDOWS WITH VISUAL STUDIO
.sp
Building on Windows requires Windows Vista or newer and Visual Studio 2010 or newer. Additionally, \fBcmake\fP is required to generate Visual Studio project files.
.sp
Let\(aqs 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 \fBcmake\fP\(aqs out\-of\-source build feature to keep build artifacts separate from source files.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cd mongo\-c\-driver\-x.y.z
mkdir cmake\-build
cd cmake\-build
cmake \-G "Visual Studio 14 2015 Win64" \e
  "\-DCMAKE_INSTALL_PREFIX=C:\emongo\-c\-driver" \e
  "\-DCMAKE_PREFIX_PATH=C:\emongo\-c\-driver" \e
  ..
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
(Run \fBcmake \-LH ..\fP for a list of other options.)
.sp
Now that we have project files generated, we can either open the project in Visual Studio or compile from the command line. Let\(aqs build using the command line program \fBmsbuild.exe\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
msbuild.exe /p:Configuration=RelWithDebInfo ALL_BUILD.vcxproj
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Visual Studio\(aqs default build type is \fBDebug\fP, but we recommend a release build with debug info for production use. Now that libmongoc and libbson are compiled, let\(aqs install them using msbuild. It will be installed to the path specified by \fBCMAKE_INSTALL_PREFIX\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
msbuild.exe INSTALL.vcxproj
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You should now see libmongoc and libbson installed in \fBC:\emongo\-c\-driver\fP
.sp
To use the driver libraries in your program, see visual\-studio\-guide\&.
.SH BUILDING ON WINDOWS WITH MINGW-W64 AND MSYS2
.sp
Install MSYS2 from \fI\%msys2.github.io\fP\&. Choose the x86_64 version, not i686.
.sp
Open \fBc:\emsys64\eming64_shell.bat\fP (not the msys2_shell). Install dependencies:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Download and untar the latest tarball, enter its directory, and build with CMake:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
CC=/mingw64/bin/gcc.exe /mingw64/bin/cmake \-G "MSYS Makefiles" \-DCMAKE_INSTALL_PREFIX="C:/mongo\-c\-driver" ..
make
.ft P
.fi
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.