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 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:
If the final path component of \(D\) is “
bin” or “sbin”, \(D\) is replaced with the parent path of \(D\).\(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.
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:
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.
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.
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.
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.
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.
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.