Skip to content

Setup

The library itself has no dependencies other than C++14. Although not tested with older versions of GCC, this should make it compatible with CY2018 and newer versions of the VFX Reference Platform.

Supported operating systems:

  • Linux
  • macOS
  • Windows

Supported architectures:

  • x86-64
  • AArch64
  • NVIDIA

Tested compilers:

  • Clang 6
  • GCC 7.5
  • Apple Clang 13
  • NVCC 10

Installation

You can install OpenQMC via either a package manager, or by cloning the source and installing it directly. The former is easier to get up and going, but the later will give you some build options to play with.

NixOS package

OpenQMC is available as a Nix flake package on NixOS and other supported platforms. The flake can also be used to load a reproducible developer environment. Install the package with:

nix profile install github:AcademySoftwareFoundation/openqmc

Cloning the source

Alternatively for installing from source, you can download a release from the site, or clone the project with:

git clone git@github.com:AcademySoftwareFoundation/openqmc.git

Adding to your project

There are three methods for adding the library as an upstream dependency to another project. Examples of each are in the cmake/examples directory. These are working examples and are continuously validated.

Add library as a submodule

The first and most recommended method is to add the library as a submodule to your downstream project, and then include the library using CMake. This is the fastest and simplest approach.

# Optionally set options (they are OFF by default)
set(OPENQMC_ARCH_TYPE AVX CACHE STRING "" FORCE)
set(OPENQMC_ENABLE_BINARY ON CACHE BOOL "" FORCE)
set(OPENQMC_SHARED_LIB ON CACHE BOOL "" FORCE)

# Load external dependencies
add_subdirectory(path/to/submodule EXCLUDE_FROM_ALL)

# Optionally mark options as advanced
mark_as_advanced(FORCE OPENQMC_ARCH_TYPE)
mark_as_advanced(FORCE OPENQMC_BUILD_TOOLS)
mark_as_advanced(FORCE OPENQMC_BUILD_TESTING)
mark_as_advanced(FORCE OPENQMC_FORCE_DOWNLOAD)
mark_as_advanced(FORCE OPENQMC_ENABLE_BINARY)
mark_as_advanced(FORCE OPENQMC_SHARED_LIB)
mark_as_advanced(FORCE OPENQMC_FORCE_PIC)

# Add dependencies
target_link_libraries(${PROJECT_NAME} PRIVATE OpenQMC::OpenQMC)

Add library as a config-module

Another good option is to install the library and use the same configuration across multiple downstream projects. You may want to do this if the library is shared between projects.

If you haven't used a package manager before or want to avoid the default configuration, then you will need to install it from the source. The CMake installation process will follow an idiomatic approach that provides you the opportunity to set library build options. An example:

cmake -B build -D CMAKE_INSTALL_PREFIX=/install/path -D OPENQMC_ENABLE_BINARY=ON
cmake --build build --target install

Adding the library then requires a find_package call in your downstream CMake project. find_package will access a CMake config file which was created upon installation, allowing the installed requirements to be loaded automatically.

# Find external dependencies
find_package(OpenQMC CONFIG REQUIRED)

# Optionally mark DIR variable as advanced
mark_as_advanced(OpenQMC_DIR)

# Add dependencies
target_link_libraries(${PROJECT_NAME} PRIVATE OpenQMC::OpenQMC)

Add library manually

Alternatively you can add the library manually as header-only. However, this method isn't recommended, as it can be error-prone and prevents using build options otherwise available via CMake.

# Enable C++14 support
target_compile_features(${PROJECT_NAME} PRIVATE cxx_std_14)

# Add dependencies
target_include_directories(${PROJECT_NAME} PRIVATE path/to/library/include)

Library build options

When adding the library using CMake, there are a set of configuration options which apply to downstream projects. The options are:

  • OPENQMC_ARCH_TYPE: Sets the architecture to optimise for on the CPU, or to target NVIDIA GPUs. Option values can be Scalar, SSE, AVX, ARM or GPU. Default value is Scalar.
  • OPENQMC_ENABLE_BINARY: You can reduce binary size of downstream projects by opting for a binary variant of the library. Option values can be ON or OFF. Default value is OFF.
  • OPENQMC_SHARED_LIB: You can request a shared library instead of the default static. This also automatically enables PIC. Option values can be ON or OFF. Default value is OFF.
  • OPENQMC_FORCE_PIC: When compiling a static library and the downstream project is a shared library, you can force enable PIC. Option values can be ON or OFF. Default value is OFF.

Versioning

Version numbers follow Semantic Versioning to indicate how changes affect the API between releases of the library. Given a version number MAJOR.MINOR.PATCH, incrementing a version means:

  1. MAJOR indicates an incompatible API change.
  2. MINOR indicates a backwards compatible feature addition.
  3. PATCH indicates a backwards compatible bug fix.

Additional labels for pre-release and build metadata may be present as extensions to the MAJOR.MINOR.PATCH format.

You can access details on what changed for each new version at CHANGELOG.md. This follows the format from Keep a Changelog.