1:man_page: mongoc_installing 2 3Installing the MongoDB C Driver 4=============================== 5 6The following guide will step you through the process of downloading, building, and installing the current release of the MongoDB C Driver. 7 8Supported Platforms 9------------------- 10 11The MongoDB C Driver is `continuously tested <https://evergreen.mongodb.com/waterfall/mongo-c-driver>`_ on variety of platforms including: 12 13- Archlinux 14- Debian 8.1 15- macOS 10.10 16- Microsoft Windows Server 2008 17- RHEL 7.0, 7.1, 7.2 18- SUSE 12 19- Ubuntu 12.04, 14.04, 16.04 20- Clang 3.4, 3.5, 3.7, 3.8 21- GCC 4.6, 4.8, 4.9, 5.3 22- MinGW-W64 23- Visual Studio 2010, 2013, 2015 24- x86, x86_64, ARM (aarch64), Power8 (ppc64le), zSeries (s390x) 25 26 27Install with a Package Manager 28------------------------------ 29 30The libmongoc package is available on recent versions of Debian and Ubuntu. 31 32.. code-block:: none 33 34 $ apt-get install libmongoc-1.0-0 35 36On Fedora, a mongo-c-driver package is available in the default repositories and can be installed with: 37 38.. code-block:: none 39 40 $ dnf install mongo-c-driver 41 42On recent Red Hat systems, such as CentOS and RHEL 7, a mongo-c-driver package is available in the `EPEL <https://fedoraproject.org/wiki/EPEL>`_ repository. To check version available, see `https://apps.fedoraproject.org/packages/mongo-c-driver <https://apps.fedoraproject.org/packages/mongo-c-driver>`_. The package can be installed with: 43 44.. code-block:: none 45 46 $ yum install mongo-c-driver 47 48Building on Unix 49---------------- 50 51Prerequisites 52^^^^^^^^^^^^^ 53 54OpenSSL is required for authentication or for SSL connections to MongoDB. Kerberos or LDAP support requires Cyrus SASL. 55 56To install all optional dependencies on RedHat / Fedora: 57 58.. code-block:: none 59 60 $ sudo yum install pkg-config openssl-devel cyrus-sasl-devel 61 62On Debian / Ubuntu: 63 64.. code-block:: none 65 66 $ sudo apt-get install pkg-config libssl-dev libsasl2-dev 67 68On FreeBSD: 69 70.. code-block:: none 71 72 $ su -c 'pkg install pkgconf openssl cyrus-sasl' 73 74Building from a release tarball 75^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 76 77Unless you intend on contributing to the mongo-c-driver, you will want to build from a release tarball. 78 79The most recent release of libmongoc is |release| and can be :release:`downloaded here <>`. The following snippet will download and extract the driver, and configure it: 80 81.. parsed-literal:: 82 83 $ wget |release_download| 84 $ tar xzf mongo-c-driver-|release|.tar.gz 85 $ cd mongo-c-driver-|release| 86 $ ./configure --disable-automatic-init-and-cleanup 87 88The ``--disable-automatic-init-and-cleanup`` option is recommended, see :doc:`init-cleanup`. For a list of all configure options, run ``./configure --help``. 89 90If ``configure`` completed successfully, you'll see something like the following describing your build configuration. 91 92.. parsed-literal:: 93 94 libmongoc |release| was configured with the following options: 95 96 Build configuration: 97 Enable debugging (slow) : no 98 Compile with debug symbols (slow) : no 99 Enable GCC build optimization : yes 100 Enable automatic init and cleanup : no 101 Enable maintainer flags : no 102 Code coverage support : no 103 Cross Compiling : no 104 Fast counters : no 105 Shared memory performance counters : yes 106 SASL : sasl2 107 SSL : openssl 108 Snappy Compression : bundled 109 Zlib Compression : bundled 110 Libbson : bundled 111 112 Documentation: 113 man : no 114 HTML : no 115 116mongo-c-driver contains a copy of libbson, in case your system does not already have libbson installed. The configure script will detect if libbson is not installed and use the bundled libbson. 117 118.. code-block:: none 119 120 $ make 121 $ sudo make install 122 123 124Building from git 125^^^^^^^^^^^^^^^^^ 126 127To build an unreleased version of the driver from git requires additional dependencies. 128 129RedHat / Fedora: 130 131.. code-block:: none 132 133 $ sudo yum install git gcc automake autoconf libtool 134 135Debian / Ubuntu: 136 137.. code-block:: none 138 139 $ sudo apt-get install git gcc automake autoconf libtool 140 141FreeBSD: 142 143.. code-block:: none 144 145 $ su -c 'pkg install git gcc automake autoconf libtool' 146 147Once you have the dependencies installed, clone the repository and build the current master or a particular release tag: 148 149.. code-block:: none 150 151 $ git clone https://github.com/mongodb/mongo-c-driver.git 152 $ cd mongo-c-driver 153 $ git checkout x.y.z # To build a particular release 154 $ ./autogen.sh --with-libbson=bundled 155 $ make 156 $ sudo make install 157 158 159Generating the documentation 160^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 161 162Install `Sphinx <http://www.sphinx-doc.org/>`_, then: 163 164.. code-block:: none 165 166 $ ./configure --enable-html-docs --enable-man-pages 167 $ make man html 168 169Building on Mac OS X 170-------------------- 171 172Install the XCode Command Line Tools:: 173 174 $ xcode-select --install 175 176The ``pkg-config`` utility is also required. First `install Homebrew according to its instructions <http://brew.sh/>`_, then:: 177 178 $ brew install pkgconfig 179 180Download the latest release tarball: 181 182.. parsed-literal:: 183 184 $ curl -LO |release_download| 185 $ tar xzf mongo-c-driver-|release|.tar.gz 186 $ cd mongo-c-driver-|release| 187 188Build and install the driver: 189 190.. code-block:: none 191 192 $ ./configure 193 $ make 194 $ sudo make install 195 196Native TLS Support on Mac OS X / Darwin (Secure Transport) 197^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 198 199The MongoDB C Driver supports the Darwin native TLS and crypto libraries. 200Using the native libraries there is no need to install OpenSSL. By 201default however, the driver will compile against OpenSSL if it 202detects it being available. If OpenSSL is not available, it will 203fallback on the native libraries. 204 205To compile against the Darwin native TLS and crypto libraries, even when 206OpenSSL is available, configure the driver like so: 207 208.. code-block:: none 209 210 $ ./configure --enable-ssl=darwin 211 212OpenSSL support on El Capitan 213^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 214 215Beginning in OS X 10.11 El Capitan, OS X no longer includes the OpenSSL headers. To build the driver with SSL on El Capitan and later: 216 217.. code-block:: none 218 219 $ brew install openssl 220 $ export LDFLAGS="-L/usr/local/opt/openssl/lib" 221 $ export CPPFLAGS="-I/usr/local/opt/openssl/include" 222 223.. _build-on-windows: 224 225Building on Windows 226------------------- 227 228Building on Windows requires Windows Vista or newer and Visual Studio 2010 or newer. Additionally, ``cmake`` is required to generate Visual Studio project files. 229 230Let's start by generating Visual Studio project files for libbson, a dependency of the C driver. The following assumes we are compiling for 64-bit Windows using Visual Studio 2015 Express, which can be freely downloaded from Microsoft. 231 232.. parsed-literal:: 233 234 cd mongo-c-driver-|release|\\src\\libbson 235 cmake -G "Visual Studio 14 2015 Win64" \\ 236 "-DCMAKE_INSTALL_PREFIX=C:\\mongo-c-driver" \\ 237 "-DCMAKE_BUILD_TYPE=Release" # Defaults to debug builds 238 239(Run ``cmake -LH .`` for a list of other options.) 240 241Now 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`` 242 243.. code-block:: none 244 245 msbuild.exe /p:Configuration=Release ALL_BUILD.vcxproj 246 247Now that libbson is compiled, let's install it using msbuild. It will be installed to the path specified by ``CMAKE_INSTALL_PREFIX``. 248 249.. code-block:: none 250 251 msbuild.exe /p:Configuration=Release INSTALL.vcxproj 252 253You should now see libbson installed in ``C:\mongo-c-driver`` 254 255Now let's do the same for the MongoDB C driver. 256 257.. parsed-literal:: 258 259 cd mongo-c-driver-|release| 260 cmake -G "Visual Studio 14 2015 Win64" \\ 261 "-DENABLE_SSL=WINDOWS" \\ 262 "-DENABLE_SASL=SSPI" \\ 263 "-DCMAKE_INSTALL_PREFIX=C:\\mongo-c-driver" \\ 264 "-DCMAKE_PREFIX_PATH=C:\\mongo-c-driver" \\ 265 "-DCMAKE_BUILD_TYPE=Release" # Defaults to debug builds 266 267 msbuild.exe /p:Configuration=Release ALL_BUILD.vcxproj 268 msbuild.exe /p:Configuration=Release INSTALL.vcxproj 269 270All of the MongoDB C Driver's components will now have been build in release 271mode and can be found in ``C:\mongo-c-driver``. 272To build and install debug binaries, remove the 273``"-DCMAKE_BUILD_TYPE=Release"`` argument to ``cmake`` and 274``/p:Configuration=Release`` to ``msbuild.exe``. 275 276To use the driver libraries in your program, see :doc:`visual-studio-guide`. 277 278Native TLS Support on Windows (Secure Channel) 279^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 280 281The MongoDB C Driver supports the Windows native TLS and crypto libraries. 282Using the native libraries there is no need to install OpenSSL. By 283default however, the driver will compile against OpenSSL if it 284detects it being available. If OpenSSL is not available, it will 285fallback on the native libraries. 286 287 288To compile against the Windows native TLS and crypto libraries, even when 289OpenSSL is available, configure the driver like so: 290 291.. code-block:: none 292 293 cmake -G "Visual Studio 14 2015 Win64" \ 294 "-DENABLE_SSL=WINDOWS" \ 295 "-DCMAKE_INSTALL_PREFIX=C:\\mongo-c-driver" \ 296 "-DCMAKE_PREFIX_PATH=C:\\mongo-c-driver" 297 298 299Native SASL Support on Windows (SSPI) 300^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 301 302The MongoDB C Driver supports the Windows native Kerberos and Active Directory 303interface, SSPI. Using the native libraries there is no need to install any 304dependencies, such as cyrus-sasl. By default however, the driver will compile 305against cyrus-sasl. 306 307 308To compile against the Windows native SSPI, configure the driver like so: 309 310.. code-block:: none 311 312 cmake -G "Visual Studio 14 2015 Win64" \ 313 "-DENABLE_SASL=SSPI" \ 314 "-DCMAKE_INSTALL_PREFIX=C:\\mongo-c-driver" \ 315 "-DCMAKE_PREFIX_PATH=C:\\mongo-c-driver" 316 317OpenSSL support on Windows 318^^^^^^^^^^^^^^^^^^^^^^^^^^ 319 320For backwards compatibility CMake will default to OpenSSL support. 321If not found, it will fallback to native TLS support provided by the platform. 322 323OpenSSL 1.1.0 support requires CMake 3.7 or later on Windows. 324 325