Configuring, Building, & Using

Configuring, Building, & Using#

Building amongoc is supported with the following build tools:

Build Configuration#

The following CMake configuration options are supported:

AMONGOC_INSTALL_CMAKEDIR#

Set the installation path for CMake package files that are to be found using find_package

Default:

${CMAKE_INSTALL_LIBDIR}/cmake

This is based on the similar variables that are used in GNUInstallDirs.

MONGO_SANITIZE#

A comma-separated list of sanitizers to enable for the build. Note that if this is enabled, then the exported library will attempt to link to the sanitizer libraries as well.

MONGO_USE_CCACHE#

If enabled, the amongoc build will use ccache for compilation. This defaults to ON if a suitable ccache executable is found.

MONGO_USE_LLD#

If enabled, thne amongoc build will link using the LLD linker instead of the default.

BUILD_TESTING#

This variables comes from the CTest CMake module and can toggle the generation/building of tests.

CMAKE_INSTALL_LIBDIR#
CMAKE_INSTALL_BINDIR#
CMAKE_INSTALL_INCLUDEDIR#

These variables come from GNUInstallDirs and control the paths to installed files for separate package components. Refer to that module for details.

AMONGOC_USE_PMM#

Toggle usage of PMM to automatically download and import dependencies at configure-time.

Default:

ON

If this toggle is enabled, then vcpkg will be executed during CMake configuration to download and build the dependencies required by amongoc.

If you want to manage dependencies yourself, disable this toggle. You will need to ensure that the configure-time dependencies are available to find_package.

Third-Party Dependencies#

The following external libraries are required by amongoc:

Building with Earthly#

Earthly is a container-based build automation tool. amongoc ships with an

Earthfile (repository file)#

The configuration file building and package with Earthly.

+build-alpine (Earthly target)#
+build-debian (Earthly target)#
+build-rl (Earthly target)#

Build targets that build for Alpine Linux (with libmusl), Debian, and RockyLinux (for RedHat-compatible binaries).

The Alpine and Debian build uses the system’s default toolchain. The RockyLinux build uses the RedHat devtoolset to obtain an up-to-date compiler for producing RedHat-compatible binaries.

+build-xyz/pkg (Earthly artifact)#
+build-xyz/install (Earthly artifact)#

Built artifacts from the build targets. The /pkg artifact contains binary packages create by CPack: A .tar.gz archive, a .zip archive, and a self-extracting shell script .sh. The /install artifact contains an install tree from the build.

+build-multi (Earthly target)#

Builds all of +build-alpine, +build-debian, and +build-rl at once.

+build-multi/ (Earthly artifact)#

The root artifact directory contains all artifacts from all other build targets.

Importing in CMake#

To use amongoc in a CMake project, import the amongoc package:

find_package(amongoc 0.1.0 REQUIRED)

Using the Imported Target#

The CMake package defines a primary imported target: amongoc::amongoc, which can be linked into an application:

add_executbale(my-program main.c)
target_link_libraries(my-program PRIVATE amongoc::amongoc)

Dependency Imports#

By default, the amongoc CMake package will attempt to import dependencies using find_dependency. This import can be disabled by changing AMONGOC_FIND_DEPENDENCIES.

AMONGOC_FIND_DEPENDENCIES#
Default:

ON

Note

This is an import-time CMake setting that is defined for projects that call find_package to import amongoc. It has no effect on building amongoc itself.

If enabled (the default), then amongoc will try to find its dependencies during import. If disabled, then amongoc will assume that the necessary imported targets will be defined elsewhere by the importing package.

The following imported targets are used by the imported amongoc::amongoc target:

  • fmt::fmt

  • Boost::url

  • Boost::container

  • OpenSSL::SSL

  • Threads::Threads (from the FindThreads module)

Contents