Provided by: libmongoc-doc_1.26.0-1.1ubuntu2_all bug

LIBMONGOC

       A Cross Platform MongoDB Client Library for C

   Introduction
       The  MongoDB C Driver, also known as "libmongoc", is a library for using MongoDB from C applications, and
       for writing MongoDB drivers in higher-level languages.

       It depends on libbson to generate and parse BSON documents, the native data format of MongoDB.

   Tutorials
       This section contains tutorials on how to get started with the basics of using the C driver.

   Obtaining the MongoDB C Driver Libraries
       There are a few methods of obtaining the mongo-c-driver codebase:

   Building the C Driver Libraries from Source
       This page details how to download, unpack, configure, and build libbson and libmongoc from their original
       source-code form.

       Extra information

       Dropdowns (like this one) contain extra information and explanatory details  that  are  not  required  to
       complete  the  tutorial,  but  may  be  helpful for curious readers, and more advanced users that want an
       explanation of the meaning of certain tutorial steps.

       The following page uses a few named "variables" that you must decide up-front.  When you see such a value
       referrenced in a tutorial step, you should substitute the value into that step.

       SEE ALSO:
          Before building, you may want to check that you are running on a supported platform. For the  list  of
          supported platforms, refer to the mongo-c-driver Platform Support page.

   Choose a Version
       Before  we  begin,  know  what  version  of  mongo-c-driver you will be downloading.  A list of available
       versions can be found on the  GitHub  repository  tags  page.  (The  current  version  written  for  this
       documentation is 1.26.0.)

       For the remainder of this page, $VERSION will refer to the version number of mongo-c-driver that you will
       be building for this tutorial.

   Obtaining the Source
       There are two primary recommended methods of obtaining the mongo-c-driver source code:

       1. Clone the repository using git (recommended).  (See below)

       2. Download a source archive at a specific version.  (See below)

       IMPORTANT:
          It  is  highly  recommended  that  new  users use a stable released version of the driver, rather than
          building from a development branch. When you git clone or download an archive of  the  repository,  be
          sure to specify a release tag (e.g. with Git's --branch argument).

   Downloading Using Git
       Using     Git,    the    C    driver    repository    can    be    cloned    from    the    GitHub    URL
       https://github.com/mongodb/mongo-c-driver.git. Git tags for released versions are named after the version
       for which they correspond (e.g. "1.26.0"). To clone the repository using the command line, the  following
       command may be used:

          $ git clone https://github.com/mongodb/mongo-c-driver.git --branch="$VERSION" "$SOURCE"

       TIP:
          Despite the name, git-clone's --branch argument may also be used to clone from repository tags.

   Downloading a Release Archive
       An   archived   snapshot  of  the  repository  can  be  obtained  from  the  GitHub  Releases  Page.  The
       mongo-c-driver-x.y.z.tar.gz archive attached to any release contains the minimal set of files that you'll
       need for the build.

       Using wget + tar

          ## Download using wget:
          $ wget "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.tar.gz" \
              --output-document="mongo-c-driver-$VERSION.tar.gz"
          ## Extract using tar:
          $ tar xf "mongo-c-driver-$VERSION.tar.gz"

       Using curl + tar

          ## Using curl:
          $ curl "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.tar.gz" \
              --output="mongo-c-driver-$VERSION.tar.gz"
          ## Extract using tar:
          $ tar xf "mongo-c-driver-$VERSION.tar.gz"

       PowerShell

          ## Use Invoke-WebRequest:
          PS> $url = "https://github.com/mongodb/mongo-c-driver/archive/refs/tags/$VERSION.zip"
          PS> $file = "mongo-c-driver-$VERSION.zip"
          PS> Invoke-WebRequest -UseBasicParsing -Uri $url -OutFile $file
          ## Extract using Expand-Archive:
          PS> Expand-Archive mongo-c-driver-$VERSION.zip

       The above commands will create a new directory mongo-c-driver-$VERSION within the directory in which  you
       ran  the tar/Expand-Archive command (note: PowerShell will create an additional intermediate subdirectory
       of the same name). This directory is the root of the driver source tree (which we refer to as $SOURCE  in
       these documents). The $SOURCE directory should contain the top-level CMakeLists.txt file.

   Obtaining Prerequisites
       In order to build the project, a few prerequisites need to be available.

       Both libmongoc and libbson projects use CMake for build configuration.

       NOTE:
          It  is  highly  recommended -- but not required -- that you download the latest stable CMake available
          for your platform.

       Getting the Latest CMake

       A new stable release of CMake can be obtained from the CMake downloads page.

       For Windows and macOS, simply download the CMake .msi/.dmg (not the .zip/.tar.gz) and use it  to  install
       CMake.

       On  Linux,  download  the  self-extracting  shell  script  (ending  with .sh) and execute it using the sh
       utility, passing the appropriate arguments to perform the install. For example, with the CMake 3.27.0  on
       the x86_64 platform, the following command can be used on the cmake-3.27.0-linux-x86_64.sh script:

          $ sh cmake-3.27.0-linux-x86_64.sh --prefix="$HOME/.local" --exclude-subdir --skip-license

       Assuming  that  $HOME/.local/bin  is  on  your  $PATH list, the cmake command for 3.27.0 will then become
       available.

       The --help option can be passed to the shell script for more information.

       For the remainder of this page, it will be assumed that cmake is available as  a  command  on  your  PATH
       environment  variable  and  can  be executed as "cmake" from a shell. You can test this by requesting the
       --version from CMake from the command line:

          $ cmake --version
          cmake version 3.21.4

          CMake suite maintained and supported by Kitware (kitware.com/cmake).

       NOTE:
          If you intend to build libbson only, then CMake is sufficient  for  the  build.  Additional  C  driver
          features  may  require additional external dependencies be installed, but we will not worry about them
          here.

   Configuring for libbson
       IMPORTANT:
          If you are building with Xcode [1] or Visual Studio [2], you may need to execute CMake from  within  a
          special environment in which the respective toolchain is available.

       Let  the name $BUILD be the path $SOURCE/_build. This will be the directory where our built files will be
       written by CMake.

       With the source directory for mongo-c-driver at $SOURCE and build directory $BUILD, the following command
       can be executed from a command-line to configure the project with both libbson and libmongoc:

          $ cmake -S $SOURCE -B $BUILD \
            -D ENABLE_EXTRA_ALIGNMENT=OFF \
            -D ENABLE_AUTOMATIC_INIT_AND_CLEANUP=OFF \
            -D CMAKE_BUILD_TYPE=RelWithDebInfo \
            -D BUILD_VERSION="$VERSION" \
            -D ENABLE_MONGOC=OFF

       If all dependencies are satisfied, the above command should succeed and end with:

          $ cmake …
          ## … (Lines of output) …
          -- Generating done
          -- Build files have been written to: $BUILD

       If configuration failed with an error, refer to the CMake output  for  error  messages  and  information.
       Ensure that configuration succeeds before proceeding.

       What do these CMake arguments mean?

       The  BUILD_VERSION sets the version number that will be included in the build results. This should be set
       to the same value as the version of the source driver that was downloaded in Obtaining the Source.

       The  ENABLE_EXTRA_ALIGNMENT  and  ENABLE_AUTOMATIC_INIT_AND_CLEANUP  are  part  of  mongo-c-driver,   and
       correspond  to deprecated features that are only enabled by default for ABI compatibility purposes. It is
       highly recommended to disable these features whenever possible.

       The ENABLE_MONGOC=OFF argument disabled building libmongoc. We'll build that in the next section.

       The CMAKE_BUILD_TYPE setting tells CMake what  variant  of  code  will  be  generated.  In  the  case  of
       RelWithDebInfo,   optimized  binaries  will  be  produced,  but  still  include  debug  information.  The
       CMAKE_BUILD_TYPE has no effect on Multi-Config generators (i.e. Visual Studio), which instead rely on the
       --config option when building/installing.

   Building the Project
       After successfully configuring the project, the build can be executed by using CMake:

          $ cmake --build $BUILD --config RelWithDebInfo --parallel

       If configured properly and all dependencies are satisfied, then  the  above  command  should  proceed  to
       compile  and  link  the  configured components. If the above command fails, then there is likely an error
       with your environment, or you are using an unsupported/untested platform. Refer to the build tool  output
       for more information.

       The --config option

       The  --config option is used to set the build configuration to use in the case of Multi-Config generators
       (i.e. Visual Studio). It has no effect on other generators, which instead use CMAKE_BUILD_TYPE.

   Installing the Built Results
       Let $PREFIX be the path $SOURCE/_install. We can use CMake to install the built results:

          $ cmake --install "$BUILD" --prefix "$PREFIX" --config RelWithDebInfo

       This command will install the mongo-c-driver build results into the $PREFIX directory.

       The --config option

       The --config option is only used for Multi-Config  generators  (i.e.  Visual  Studio)  and  is  otherwise
       ignored. The value given for --config must be the same as was given for --config with cmake --build.

       SEE ALSO:
          The above snippet simply installs mongo-c-driver in a subdirectory of the source directory itself, but
          this   is  not  a  normal  workflow.  Once  you  feel  compfortable  about  configuring  and  building
          mongo-c-driver, the page How to: Install libbson/libmongoc from  Source  will  do  a  deeper  dive  on
          from-source installation options.

   Configuring with libmongoc
       If  you  followed  the  above  steps  starting  from Configuring for libbson, your final result with only
       contain libbson and not the full C database driver library. Building  of  libmongoc  is  enabled/disabled
       using the ENABLE_MONGOC CMake variable. Re-run CMake again, but set ENABLE_MONGOC to TRUE:

          $ cmake -D ENABLE_MONGOC=ON $BUILD

       If the above command succeeds, then the project has been reconfigured to build with libmongoc. Follow the
       process at Building the Project and Installing the Built Results again to build and install libmongoc.

FOOTNOTES

       [1]  If  you  wish to configure and build the project with Xcode, the Xcode command-line tools need to be
            installed and made available in the environment.  From within a command-line environment, run:

          $ xcode-select --install

       This will ensure that the compilers and linkers are available on your $PATH.

       [2]  If you wish to configure and build the project using Microsoft Visual C++, then the Visual C++ tools
            and environment variables may need to be set when running any CMake or build command.

            In many cases, CMake will detect a Visual Studio installation and automatically load the environment
            itself when it is executed. This automatic detection can be controlled with CMake's -G, -T,  and  -A
            options.  The  -G  option is the most significant, as it selects which Visual Studio version will be
            used. The versions of Visual Studio supported  depends  on  the  version  of  CMake  that  you  have
            installed.  A list of supported Visual Studio versions can be found here

            For greater control and more tooling options, it is recommended to run commands from within a Visual
            Studio Developer PowerShell (preferred) or Developer Command Prompt (legacy).

            For  more information, refer to: Visual Studio Developer Command Prompt and Developer PowerShell and
            Use the Microsoft C++ toolset from the command line on the  Microsoft  Visual  Studio  documentation
            pages.

   Installing Prebuilt MongoDB C Driver Libraries
       The  libmongoc and libbson libraries are often available in the package management repositories of common
       Linux distributions and macOS via Homebrew.

       NOTE:
          For Windows, it is recommended to instead build the libraries from source, for  maximum  compatibility
          with the local toolchain. Building from source can be automated by using a from-source library package
          management tool such as Conan or vcpkg (See: Cross Platform Installs Using Library Package Managers).

       CAUTION:
          If  you  install  and  use  prebuilt binaries from a third-party packager, it is possible that it lags
          behind the version of the libraries described in these documentation pages (1.26.0). Note the  version
          that you install and keep it in mind when reading these pages.

          For the most up-to-date versions of the C driver libraries, prefer to instead build from source.

       SEE ALSO:
          For a listing and common reference on available packages, refer to Package Installation Reference.

   Cross Platform Installs Using Library Package Managers
       Various library package managers offer libbson and libmongoc as installable packages, including Conan and
       vcpkg. This section will detail how to install using those tools.

   Installing using vcpkg
       NOTE:
          This page will not detail how to get started using vcpkg. For that, refer to Get started with vcpkg

       vcpkg  Manifest  Mode  (Recommended)  In vcpkg manifest mode, add the desired libraries to your project's
       vcpkg.json manifest file:

       vcpkg.json

          {
            // ...
            "dependencies": [
              // ...
              "mongo-c-driver"
            ]
          }

       When you build a CMake project with vcpkg integration and have a vcpkg.json  manifest  file,  vcpkg  will
       automatically  install  the  project's dependencies before proceeding with the configuration phase, so no
       additional manual work is required.

       vcpkg Classic Mode In vcpkg classic mode, libbson and  libmongoc  can  be  installed  through  the  names
       libbson and mongo-c-driver, respectively:

          $ vcpkg install mongo-c-driver

       (Installing mongo-c-driver will transitively install libbson as well.)

       When  the  libmongoc  and libbson packages are installed and vcpkg has been properly integrated into your
       build system, the desired libraries will be available for import.

       With CMake, the standard config-file package will  be  available,  as  well  as  the  generated  IMPORTED
       targets:

       CMakeLists.txt

          find_package(mongoc-1.0 CONFIG REQUIRED)
          target_link_libraries(my-application
              PRIVATE $<IF:$<TARGET_EXISTS:mongo::mongoc_shared>,mongo::mongoc_shared,mongo::mongoc_static>)

       NOTE:
          The  large  $<IF:$<TARGET_EXISTS...>:...> generator expression (cmake-generator-expressions(7)) can be
          used to switch the link type of libmongoc based on whichever form is available from the find_package()
          command. libmongoc supports building with both dynamic and static library types, but vcpkg  will  only
          install one of the two library types at a time.

       Configuring a CMake project with vcpkg integration is a matter of setting the CMake toolchain file at the
       initial configure command:

          $ cmake -S . -B _build -D CMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake

   Installing in Linux
       The  names  and  process  of installing libbson and libmongoc varies between distributions, but generally
       follows a similar pattern.

       The following Linux distributions provide libbson and libmongoc packages:

       • Fedora via dnfRedHat Enterprise Linux (RHEL) 7 and Newer and distribusions  based  on  RHEL  7  or  newer,  including
         CentOS, Rocky Linux, and AlmaLinux, via yum/dnf and EPEL.

       • Debian and Debian-based distributions, including Ubuntu and Ubuntu derivatives, via APT.

       SEE ALSO:
          For a list of available packages and package options, see: Package Installation Reference.

   RedHat-based Systems
       In  RedHat-based  Linux distributions, including Fedora, CentOS, Rocky Linux, and AlmaLinux, the C driver
       libraries can be installed with Yum/DNF.

       NOTE:
          For Fedora and enterprise Linux of version 8 or greater, it is recommended to use the dnf  command  in
          place of any yum command.

       IMPORTANT:
          Except for Fedora:

          The  C  driver  libraries are only available in version 7 and newer of the respective enterprise Linux
          distributions. However, the C driver libraries are not available in the default repositories, but  can
          be  obtained  by  enabling  the  EPEL  repositories.  This  can be done by installing the epel-release
          package:

              # yum install epel-release

          epel-release must be installed before attempting to install the C driver libraries  (i.e.  one  cannot
          install them both in a single yum install command).

       To install libbson only, install the libbson-devel package:

          # yum install libbson-devel

       To install the full C database driver (libmongoc), install mongo-c-driver-devel:

          ## (This package will transitively install libbson-devel)
          # yum install mongo-c-driver-devel

       To            check            which            version            is            available,           see
       https://packages.fedoraproject.org/pkgs/mongo-c-driver/mongo-c-driver-devel.

       The development packages (ending in -devel) include files required to build  applications  using  libbson
       and  libmongoc.   To  only  install  the  libraries  without  development  files,  install the libbson or
       mongo-c-driver-libs packages.

   Debian-based Systems
       In Debian-based Linux distributions, including Ubuntu and Ubuntu derivatives, libbson and  libmongoc  are
       available   in  the  distribution  repositories  via  APT,  and  can  be  installed  as  libbson-dev  and
       libmongoc-dev, respectively:

          ## Update repository information, if necessary:
          # apt update

       To install only libbson:

          # apt install libbson-dev

       To install libmongoc (which will also install libbson):

          # apt install libmongoc-dev

       To check which version is available, run apt-cache policy libmongoc-dev.

       The development packages (ending in -dev) include files required to build applications using libbson  and
       libmongoc.   To  only  install  the  libraries  without  development  files, install the libbson-1.0-0 or
       libmongoc-1.0-0 packages.

   Installing on macOS with Homebrew
       If you are using a macOS system, the C driver libraries (including both libmongoc  and  libbson)  may  be
       installed using the Homebrew package manager [1] with the following command:

          $ brew install mongo-c-driver

       NOTE:
          Homebrew does not provide separate packages for libbson and libmongoc.

       [1]  The  Homebrew  package  manager  is not installed by default on macOS. For information on installing
            Homebrew, refer to the Homebrew installation documentation page.

   Building the mongo-c-driver Documentation Pages
       This documentation is rendered using Sphinx. To easily ensure that all tooling matches expected versions,
       it is recommended to use Poetry to install and run the required tools.

       TIP:
          Poetry itself may be installed externally, but can also be automatically managed  using  the  included
          wrapping  scripts for Bash (At tools/poetry.sh) or PowerShell (at tools/poetry.ps1). These scripts can
          stand in for poetry in any command written below.

   Setting Up the Environment
       To install the required tooling, use the poetry install command, enabling documentation dependencies:

          $ poetry install --with=docs

       This will create a user-local Python virtualenv that contains  the  necessary  tools  for  building  this
       documentation. The poetry install command only needs to be run when the pyproject.toml file is changed.

   Running Sphinx
       Poetry can be used to execute the sphinx-build command:

          $ poetry run sphinx-build -b dirhtml "./src/libmongoc/doc" "./_build/docs/html"

       This command will generate the HTML documentation in the _build/docs/html subdirectory.

       TIP:
          Because Sphinx builds many pages, the build may run quite slowly. For faster builds, it is recommended
          to use the --jobs command-line option when invoking sphinx-build.

   Viewing the Documentation
       To quickly view the rendered HTML pages, a simple local HTTP server can be spawned on the command line by
       using Python's built-in http.server module:

          $ poetry run python -m http.server --directory=_build/docs/html

       By  default,  this  will  serve the documentation at http://127.0.0.1:8000, which you can open in any web
       browser to see the rendered pages.

   How-To Guides
       IMPORTANT:
          The "cookbook" is for problem-solving, and deeper dives into approach particular tasks. It may  assume
          some  prior  knowledge,  and  these  are  not  tutorials  themselves! For learning the basics, see the
          Tutorials section.

   How to: Install libbson/libmongoc from Source
       IMPORTANT:
          This page assumes that you can successfully configure and  build  the  components  that  you  wish  to
          install,  which  is detailed and explained on the Building the C Driver Libraries from Source tutorial
          page. Whereas that tutorial walks through getting the sources built and  a  minimal  install  working,
          this  page  will  offer  deeper  guidance  on  the  nuance  and  available  options for installing the
          mongo-c-driver libraries from such a from-source build.

       mongo-c-driver uses CMake to generate its installation rules, and installs  a  variety  of  artifacts  of
       interest.  For  integration with downstream programs, the Config-file Packages and pkg-config files would
       be of particular interest.

       If you are intending to import libbson or libmongoc via CMake or pkg-config, it  can  be  helpful  to  be
       aware of how the respective tool searches for package metadata.

       CMake  Package  Lookup CMake builds a set of search paths based on a set of prefixes, which are read from
       both the environment and from configure-time CMake settings.

       In particular, the $PATH environment variable will be used to construct the  standard  prefixes  for  the
       system. For each directory D in $PATH:

       1. If the final path component of D is "bin" or "sbin", D is replaced with the parent path of D.

       2. D is added as a search prefix.

       This  has  the effect that common Unix-specific directories on $PATH, such as /usr/bin and /usr/local/bin
       will end up causing CMake to search in /usr and /usr/local is prefixes, respectively.  If  you  have  the
       directory  $HOME/.local/bin  on  your  $PATH,  then  the $HOME/.local directory will also be added to the
       search path. Having $HOME/.local/bin on $PATH is an increasingly common pattern for many Unix shells, and
       is recommended if you intend to do use a per-user-prefix for your installion.

       Additionally, the CMAKE_PREFIX_PATH environment variable will be used to construct a list  of  paths.  By
       default, this environment variable is not defined.

       On  Windows,  the  directories %ProgramW6432%, %ProgramFiles%, %ProgramFiles(x86)%, %SystemDrive%\Program
       Files,  and  %SystemDrive%\Program  Files  (x86)   will   also   be   added.   (These   come   from   the
       CMAKE_SYSTEM_PREFIX_PATH CMake variable, which is defined during CMake's platform detection.)

       SEE ALSO:
          For  detailed information on package lookup, refer to CMake's Config Mode Search Procedure section for
          full details.

       pkg-config Package Lookup The pkg-config command-line tool looks for .pc files in various directories, by
       default relative to the path of the pkg-config tool itself. To get the  list  of  directories  that  your
       pkg-config will search by default, use the following command:

       Ask pkg-config what directories it will search by default

          $ pkg-config "pkg-config" --variable="pc_path"

       Additional  directories can be specified using the $PKG_CONFIG_PATH environment variable. Such paths will
       be searched before the default pkg-config paths.

       On        Windows,        registry        keys        HKCU\Software\pkgconfig\PKG_CONFIG_PATH         and
       HKLM\Software\pkgconfig\PKG_CONFIG_PATH  can  be  used  to  specify  additional  search  directories  for
       pkg-config. Adding directories to the HKCU\… key  is  recommended  for  persisting  user-specific  search
       directories.

       SEE ALSO:
          If  you  have  man  and  pkg-config  installed on your system, lookup procedures are detailed in man 1
          pkg-config. This documentation may also be found at many  man  page  archives  on  the  web,  such  as
          pkg-config at linux.die.net.

   Choosing a Prefix
       We  will call the directory for the user-local installation $PREFIX. Selecting the path to this directory
       is somewhat arbitrary, but there are some recommendations to consider. The $PREFIX directory is the  path
       that you will give to CMake or pkg-config when configuring a downstream project.

   Using an Unprivileged User-Local Install Prefix (Recommended)
       It  is  recommended  that you install custom-built mongo-c-driver libraries in an unprivileged filesystem
       location particular to the user account.

       macOS Unlike other Unix-like systems, macOS does not have a specific  directory  for  user-local  package
       installations, and it is up to the individual to create such directories themselves.

       The choice of directory to use is essentially arbitrary. For per-user installations, the only requirement
       is that the directory be writeable by the user that wishes to perform and use the installation.

       For  the  purposes  of  uniformity  with  other  Unix  variants,  this guide will lightly recommend using
       $HOME/.local as a user-local installation prefix.  This is based on the behavior  specified  by  the  XDG
       base  directory specifications and the systemd file-hierarchy common on Linux and various BSDs, but it is
       not a standard on other platforms.

       Linux & Other Unixes On Linux and BSD systems, it is common to use  the  $HOME/.local  directory  as  the
       prefix  for  user-specific  package  installations.  This convention originates in the XDG base directory
       specification and the systemd file-hierarchy

       Because of its wide-spread use and support in many other tools, this guide recommends using  $HOME/.local
       as a user-local installation prefix.

       Windows    On    Windows,    there    exists    a   dedicated   directory   for   user-local   files   in
       %UserProfile%\AppData\Local. To reference it, expand the %LocalAppData% environment variable. (Do not use
       the %AppData% environment variable!)

       Despite this directory existing, it has no prescribed structure that suits our purposes.  The  choice  of
       user-local  installation  prefix is arbitrary.  This guide strongly discourages creating additional files
       and directories directly within the user's home directory.

       Consider using %LocalAppData%\MongoDB as a prefix for the purposes of manually installed components.

   Selecting a System-Wide Installation Prefix
       If you wish to install the mongo-c-driver libraries in a directory that is visible to  all  users,  there
       are a few standard options.

       Linux,  macOS,  BSD,  or Other Unix Using an install $PREFIX of /usr/local/ is the primary recommendation
       for all Unix platforms, but this may vary on some obscure systems.

       WARNING:
          DO NOT use /usr/ nor / (the root directory)  as  a  prefix:  These  directories  are  designed  to  be
          carefully managed by the system. The /usr/local directory is intentionally reserved for the purpose of
          unmanaged software installation.

       Alternatively,  consider installing to a distinct directory that can be easily removed or relocated, such
       as /opt/mongo-c-driver/. This will be easily identifiable and not interact with  other  software  on  the
       system without explicitly opting-in.

       Windows

       WARNING:
          It  is strongly discouraged to manually install software system-wide on Windows. Prefer instead to use
          a per-user unprivileged installation prefix.

       If you wish to perform a system-wide installation on Windows, prefer  to  use  a  named  subdirectory  of
       %ProgramData%,   which   does   not   require   administrative   privileges  to  read  and  write.  (e.g.
       %ProgramData%\mongo-c-driver)

   Installing with CMake
       After you have successfully configured and built the libraries and have selected a suitable $PREFIX,  you
       can  install  the  built results. Let the name $BUILD refer to the directory where you executed the build
       (this is the directory that contains CMakeCache.txt, among many other files).

       From a command line, the installation into your chosen $PREFIX can be  run  via  CMake  using  the  cmake
       --install subcommand:

          $ cmake --install "$BUILD" --prefix "$PREFIX"

       IMPORTANT:
          If  you configured the libraries while using a multi-config generator (e.g Visual Studio, Xcode), then
          you will also need to pass the --config command-line option, and must pass the  value  for  the  build
          configuration  that  you  wish to install. For any chosen value of --config used for installation, you
          must also have previously executed a cmake --build within  that  directory  with  that  same  --config
          value.

       NOTE:
          If  you  chose to use a system-wide installation $PREFIX, it is possible that you will need to execute
          the installation as a privileged user. If you cannot run or do not want to run the installation  as  a
          privileged user, you should instead use a per-user installation prefix.

       HINT:
          It  is  not  necessary  to set a CMAKE_INSTALL_PREFIX if you use the --prefix command-line option with
          cmake --install. The --prefix option will override whatever was specified by CMAKE_INSTALL_PREFIX when
          the project was configured.

   Reference
   Package Installation Reference
       libbson and libmongoc are available from several package management tools on a variety of systems.

       IMPORTANT:
          The third-party packages detailed here are not directly controlled via the mongo-c-driver maintainers,
          and the information found here may be incomplete or out-of-date.

   Package Names and Availability
       This table details the names and usage notes of such packages.

       NOTE:
          The development packages (ending in -dev or -devel) include files required to build applications using
          libbson and libmongoc.

       SEE ALSO:
          For a step-by-step tutorial on installing packages, refer to  Installing  Prebuilt  MongoDB  C  Driver
          Libraries.
    ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
      Packaging Tool      Platform(s)           libbson package(s)   libmongoc               Notes
                                                                     package(s)
    ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
      APT (apt/apt-get)   Debian-based  Linux   libbson-1.0-0,       libmongoc-1.0-0,
                          distributions         libbson-dev,         libmongoc-dev,
                          (Debian,    Ubuntu,   libbson-doc          libmongoc-doc
                          Linux Mint, etc.)
    ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
      Yum/DNF             RHEL-based  systems   libbson,             mongo-c-driver-libs,    Except  on   Fedora
                          (RHEL,      Fedora,   libbson-devel        mongo-c-driver-devel    the            EPEL
                          CentOS,       Rocky                                                repositories   must
                          Linux, AlmaLinux)                                                  be   enabled  (i.e.
                                                                                             install         the
                                                                                             epel-release
                                                                                             package first)
    ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
      APK                 Alpine Linux          libbson,             mongo-c-driver,
                                                libbson-dev,         mongo-c-driver-dev,
                                                libbson-static       mongo-c-driver-static
    ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
      pacman              Arch Linux            mongo-c-driver       mongo-c-driver          A   single  package
                                                                                             provides       both
                                                                                             runtime         and
                                                                                             development support
                                                                                             for  both   libbson
                                                                                             and libmongoc
    ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
      Homebrew            macOS                 mongo-c-driver       mongo-c-driver
    ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
      Conan               Cross-platform        mongo-c-driver       mongo-c-driver          See: Conan Settings
                                                                                             and Features
    ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
      vcpkg               Cross-platform        libbson              mongo-c-driver          See: vcpkg Optional
                                                                                             Features
    ┌───────────────────┬─────────────────────┬────────────────────┬───────────────────────┬─────────────────────┐
    │                   │                     │                    │                       │                     │
--

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2017-present, MongoDB, Inc

1.26.0                                            Mar 31, 2024                               MONGOC_REFERENCE(3)