project_options

A general-purpose CMake library that provides functions that improve the CMake experience following the best practices.

Features

project_options:
- compiler warnings,
- compiler optimizations (intraprocedural, native),
- caching (ccache, sccache),
- sanitizers,
- static code analyzers (clang-tidy, cppcheck, visual studio, include-what-you-use),
- document generation (doxygen),
- test coverage analysis,
- precompiled headers,
- build time measurement,
- unity builds
- using custom linkers (e.g. lld)
package_project: automatic packaging/installation of the project for seamless usage via find_package/target_link through CMake's FetchContent, vcpkg, etc.
run_vcpkg: automatic installation of vcpkg and the project dependencies
ENABLE_CONAN in project_options: automatic installation of Conan and the project dependencies
dynamic_project_options: a wrapper around project_options to change the options on the fly dynamically
target_link_system_libraries and target_include_system_directories: linking/including external dependencies/headers without warnings
target_link_cuda: linking Cuda to a target

Usage

See project_options() in action in this template repository. cpp_vcpkg_project has prepared all the best practices for a production-ready C++ project.

Here is a full example:

cmake_minimum_required(VERSION 3.20)

# set a default CXX standard for the tools and targets that do not specify them.
# If commented, the latest supported standard for your compiler is automatically set.
# set(CMAKE_CXX_STANDARD 20)

# Add project_options v0.26.3
# https://github.com/aminya/project_options
# Change the version in the following URL to update the package (watch the releases of the repository for future updates)
include(FetchContent)
FetchContent_Declare(_project_options URL https://github.com/aminya/project_options/archive/refs/tags/v0.26.3.zip)
FetchContent_MakeAvailable(_project_options)
include(${_project_options_SOURCE_DIR}/Index.cmake)

# install vcpkg dependencies: - should be called before defining project()
run_vcpkg()

# Set the project name and language
project(myproject LANGUAGES CXX C)

# Build Features
option(FEATURE_TESTS "Enable the tests" OFF)
if(FEATURE_TESTS)
  list(APPEND VCPKG_MANIFEST_FEATURES "tests")
endif()

option(FEATURE_DOCS "Enable the docs" OFF)

# Enable sanitizers and static analyzers when running the tests
set(ENABLE_CLANG_TIDY OFF)
set(ENABLE_CPPCHECK OFF)
set(ENABLE_SANITIZER_ADDRESS OFF)
set(ENABLE_SANITIZER_UNDEFINED_BEHAVIOR OFF)
set(ENABLE_COVERAGE OFF)

if(FEATURE_TESTS)
  set(ENABLE_CLANG_TIDY "ENABLE_CLANG_TIDY")
  set(ENABLE_CPPCHECK "ENABLE_CPPCHECK")
  set(ENABLE_COVERAGE "ENABLE_COVERAGE")

  if(NOT
     "${CMAKE_SYSTEM_NAME}"
     STREQUAL
     "Windows")
    set(ENABLE_SANITIZER_ADDRESS "ENABLE_SANITIZER_ADDRESS")
    set(ENABLE_SANITIZER_UNDEFINED_BEHAVIOR "ENABLE_SANITIZER_UNDEFINED_BEHAVIOR")
  else()
    # or it is MSVC and has run vcvarsall
    string(FIND "$ENV{PATH}" "$ENV{VSINSTALLDIR}" index_of_vs_install_dir)
    if(MSVC AND "${index_of_vs_install_dir}" STREQUAL "-1")
      set(ENABLE_SANITIZER_ADDRESS "ENABLE_SANITIZER_ADDRESS")
    endif()
  endif()
endif()

if(FEATURE_DOCS)
  set(ENABLE_DOXYGEN "ENABLE_DOXYGEN")
else()
  set(ENABLE_DOXYGEN OFF)
endif()

# Initialize project_options variable related to this project
# This overwrites `project_options` and sets `project_warnings`
# uncomment to enable the options. Some of them accept one or more inputs:
project_options(
      ENABLE_CACHE
      ${ENABLE_CPPCHECK}
      ${ENABLE_CLANG_TIDY}
      ENABLE_VS_ANALYSIS
      # ENABLE_CONAN
      # ENABLE_INTERPROCEDURAL_OPTIMIZATION
      # ENABLE_NATIVE_OPTIMIZATION
      ${ENABLE_DOXYGEN}
      ${ENABLE_COVERAGE}
      ${ENABLE_SANITIZER_ADDRESS}
      ${ENABLE_SANITIZER_UNDEFINED_BEHAVIOR}
      # ENABLE_SANITIZER_THREAD
      # ENABLE_SANITIZER_MEMORY
      # ENABLE_PCH
      # PCH_HEADERS
      # WARNINGS_AS_ERRORS
      # ENABLE_INCLUDE_WHAT_YOU_USE
      # ENABLE_USER_LINKER
      # ENABLE_BUILD_WITH_TIME_TRACE
      # ENABLE_UNITY
      # CONAN_PROFILE ${profile_path}  # passes a profile to conan: see https://docs.conan.io/en/latest/reference/profiles.html
)

Then add the executables or libraries to the project:

An executable:

add_executable(main main.cpp)
target_link_libraries(main PRIVATE project_options project_warnings) # link project_options/warnings

# Find dependencies:
set(DEPENDENCIES_CONFIGURED fmt Eigen3)

foreach(DEPENDENCY ${DEPENDENCIES_CONFIGURED})
  find_package(${DEPENDENCY} CONFIG REQUIRED)
endforeach()

# Link dependencies
target_link_system_libraries(
  main
  PRIVATE
  fmt::fmt
  Eigen3::Eigen
)

# Package the project
package_project(TARGETS main)

A header-only library:

add_library(my_header_lib INTERFACE)
target_link_libraries(my_header_lib INTERFACE project_options project_warnings) # link project_options/warnings

# Includes
set(INCLUDE_DIR "include") # must be relative paths
target_include_directories(my_header_lib INTERFACE "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/${INCLUDE_DIR}>"
                                          "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>")

# Find dependencies:
set(DEPENDENCIES_CONFIGURED fmt Eigen3)

foreach(DEPENDENCY ${DEPENDENCIES_CONFIGURED})
  find_package(${DEPENDENCY} CONFIG REQUIRED)
endforeach()

# Link dependencies:
target_link_system_libraries(
  my_header_lib
  INTERFACE
  fmt::fmt
  Eigen3::Eigen
)

# Package the project
package_project(
  TARGETS my_header_lib project_options project_warnings
  INTERFACE_DEPENDENCIES_CONFIGURED ${DEPENDENCIES_CONFIGURED}
  INTERFACE_INCLUDES ${INCLUDE_DIR}
)

A library with separate header and source files

add_library(my_lib "./src/my_lib/lib.cpp")
target_link_libraries(my_lib PRIVATE project_options project_warnings) # link project_options/warnings

# Includes
set(INCLUDE_DIR "include") # must be relative paths
target_include_directories(my_lib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/${INCLUDE_DIR}>"
                                         "$<INSTALL_INTERFACE:./${CMAKE_INSTALL_INCLUDEDIR}>")

# Find dependencies:
set(DEPENDENCIES_CONFIGURED fmt Eigen3)

foreach(DEPENDENCY ${DEPENDENCIES_CONFIGURED})
  find_package(${DEPENDENCY} CONFIG REQUIRED)
endforeach()

# Link dependencies:
target_link_system_libraries(
  my_lib
  PRIVATE
  fmt::fmt
  Eigen3::Eigen
)

# Package the project
package_project(
  TARGETS my_lib
  PUBLIC_INCLUDES ${INCLUDE_DIR}
)

`project_options` function

It accepts the following named flags:

ENABLE_CACHE: Enable cache if available
ENABLE_CPPCHECK: Enable static analysis with Cppcheck
ENABLE_CLANG_TIDY: Enable static analysis with clang-tidy
ENABLE_VS_ANALYSIS: Enable Visual Studio IDE code analysis if the generator is Visual Studio.
ENABLE_CONAN: Use Conan for dependency management
ENABLE_INTERPROCEDURAL_OPTIMIZATION: Enable Interprocedural Optimization (Link Time Optimization, LTO) in the release build
ENABLE_NATIVE_OPTIMIZATION: Enable the optimizations specific to the build machine (e.g. SSE4_1, AVX2, etc.).
ENABLE_COVERAGE: Enable coverage reporting for gcc/clang
ENABLE_DOXYGEN: Enable Doxygen documentation. The added doxygen-docs target can be built via cmake --build ./build --target doxygen-docs.
WARNINGS_AS_ERRORS: Treat compiler and static code analyzer warnings as errors. This also affects CMake warnings related to those.
ENABLE_SANITIZER_ADDRESS: Enable address sanitizer
ENABLE_SANITIZER_LEAK: Enable leak sanitizer
ENABLE_SANITIZER_UNDEFINED_BEHAVIOR: Enable undefined behavior sanitizer
ENABLE_SANITIZER_THREAD: Enable thread sanitizer
ENABLE_SANITIZER_MEMORY: Enable memory sanitizer
ENABLE_PCH: Enable Precompiled Headers
ENABLE_INCLUDE_WHAT_YOU_USE: Enable static analysis with include-what-you-use
ENABLE_USER_LINKER: Enable a specific linker if available
ENABLE_BUILD_WITH_TIME_TRACE: Enable -ftime-trace to generate time tracing .json files on clang
ENABLE_UNITY: Enable Unity builds of projects

It gets the following named parameters that can have different values in front of them:

PREFIX: the optional prefix that is used to define ${PREFIX}_project_options and ${PREFIX}_project_warnings targets when the function is used in a multi-project fashion.
DOXYGEN_THEME: the name of the Doxygen theme to use. Supported themes:
- awesome-sidebar (default)
- awesome
- original
- Alternatively you can supply a list of css files to be added to DOXYGEN_HTML_EXTRA_STYLESHEET
LINKER: choose a specific linker (e.g. lld, gold, bfd). If set to OFF (default), the linker is automatically chosen.
PCH_HEADERS: the list of the headers to precompile
MSVC_WARNINGS: Override the defaults for the MSVC warnings
CLANG_WARNINGS: Override the defaults for the CLANG warnings
GCC_WARNINGS: Override the defaults for the GCC warnings
CUDA_WARNINGS: Override the defaults for the CUDA warnings
CPPCHECK_OPTIONS: Override the defaults for the options passed to cppcheck
VS_ANALYSIS_RULESET: Override the defaults for the code analysis rule set in Visual Studio.
CONAN_OPTIONS: Extra Conan options

`run_vcpkg` function

run_vcpkg()

Or by specifying the options

run_vcpkg(
    VCPKG_URL "https://github.com/microsoft/vcpkg.git"
    VCPKG_REV "33c8f025390f8682811629b6830d2d66ecedcaa5"
    ENABLE_VCPKG_UPDATE
)

Named Option:

ENABLE_VCPKG_UPDATE: (Disabled by default). If enabled, the vcpkg registry is updated before building (using git pull).

If VCPKG_REV is set to a specific commit sha, no rebuilds are triggered. If VCPKG_REV is not specified or is a branch, enabling ENABLE_VCPKG_UPDATE will rebuild your updated vcpkg dependencies.

Named String:

VCPKG_DIR: (Defaults to ~/vcpkg). You can provide the vcpkg installation directory using this optional parameter. If the directory does not exist, it will automatically install vcpkg in this directory.
VCPKG_URL: (Defaults to https://github.com/microsoft/vcpkg.git). This option allows setting the URL of the vcpkg repository. By default, the official vcpkg repository is used.
VCPKG_REV: This option allows checking out a specific branch name or a commit sha. If VCPKG_REV is set to a specific commit sha, the builds will become reproducible because that exact commit is always used for the builds. To make sure that this commit sha is pulled, enable ENABLE_VCPKG_UPDATE

`target_link_system_libraries` function

A function that accepts the same arguments as target_link_libraries. It has the following features:

The include directories of the library are included as SYSTEM to suppress their warnings. This helps in enabling WARNINGS_AS_ERRORS for your own source code.
For installation of the package, the includes are considered to be at ${CMAKE_INSTALL_INCLUDEDIR}.

`target_include_system_directories` function

A function that accepts the same arguments as target_include_directories. It has the above mentioned features of target_link_system_libraries

`target_link_cuda` function

A function that links Cuda to the given target.

add_executable(main_cuda main.cu)
target_compile_features(main_cuda PRIVATE cxx_std_17)
target_link_libraries(main_cuda PRIVATE project_options project_warnings)
target_link_cuda(main_cuda)

`package_project` function

A function that packages the project for external usage (e.g. from vcpkg, Conan, etc).

The following arguments specify the package:

TARGETS: the targets you want to package. It is recursively found for the current folder if not specified
INTERFACE_INCLUDES or PUBLIC_INCLUDES: a list of interface/public include directories or files.

_{NOTE: The given include directories are directly installed to the install destination. To have an include folder in the install destination with the content of your include directory, name your directory include.}
INTERFACE_DEPENDENCIES_CONFIGURED or PUBLIC_DEPENDENCIES_CONFIGURED: the names of the interface/public dependencies that are found using CONFIG.
INTERFACE_DEPENDENCIES or PUBLIC_DEPENDENCIES: the interface/public dependencies that will be found by any means using find_dependency. The arguments must be specified within quotes (e.g."<dependency> 1.0.0 EXACT" or "<dependency> CONFIG").
PRIVATE_DEPENDENCIES_CONFIGURED: the names of the PRIVATE dependencies found using CONFIG. Only included when BUILD_SHARED_LIBS is OFF.
PRIVATE_DEPENDENCIES: the PRIVATE dependencies found by any means using find_dependency. Only included when BUILD_SHARED_LIBS is OFF

Other arguments that are automatically found and manually specifying them is not recommended:

NAME: the name of the package. Defaults to ${PROJECT_NAME}.
VERSION: the version of the package. Defaults to ${PROJECT_VERSION}.
COMPATIBILITY: the compatibility version of the package. Defaults to SameMajorVersion.
CONFIG_EXPORT_DESTINATION: the destination for exporting the configuration files. Defaults to ${CMAKE_BINARY_DIR}/${NAME}
CONFIG_INSTALL_DESTINATION: the destination for installation of the configuration files. Defaults to ${CMAKE_INSTALL_DATADIR}/${NAME}

Disabling static analysis for external targets

This function disables static analysis for the given target:

target_disable_static_analysis(some_external_target)

There is also individual functions to disable a specific analysis for the target:

target_disable_cpp_check(target)
target_disable_vs_analysis(target)
target_disable_clang_tidy(target)

Changing the project_options dynamically

During the test and development, it can be useful to change options on the fly. For example, to enable sanitizers when running tests. You can include DynamicOptions.cmake, which imports the dynamic_project_options function.

dynamic_project_options provides a recommended set of defaults (all static analysis and runtime analysis enabled for platforms where that is possible) while also providing a high-level option ENABLE_DEVELOPER_MODE (defaulted to ON) which can be turned off for easy use by non-developers.

The goal of the dynamic_project_options is to give a safe and well-analyzed environment to the developer by default while simultaneously making it easy for a user of the project to compile while not having to worry about clang-tidy, sanitizers, cppcheck, etc.

The defaults presented to the user can be modified with

set(<featurename>_DEFAULT value) - for user and developer builds
set(<featurename>_USER_DEFAULT value) - for user builds
set(<featureoptionname>_DEVELOPER_DEFAULT value) - for developer builds

If you need to fix a setting for the sake of a command-line configuration, you can use:

cmake -DOPT_<featurename>:BOOL=value

See dynamic_project_options() in action in this template repository.

👉 Click to show the example:

cmake_minimum_required(VERSION 3.20)

# set a default CXX standard for the tools and targets that do not specify them.
# If commented, the latest supported standard for your compiler is automatically set.
# set(CMAKE_CXX_STANDARD 20)

# Add project_options v0.26.3
# https://github.com/aminya/project_options
# Change the version in the following URL to update the package (watch the releases of the repository for future updates)
include(FetchContent)
FetchContent_Declare(_project_options URL https://github.com/aminya/project_options/archive/refs/tags/v0.26.3.zip)
FetchContent_MakeAvailable(_project_options)
include(${_project_options_SOURCE_DIR}/Index.cmake)

 # ❗ Add dynamic CMake options
include(${_project_options_SOURCE_DIR}/src/DynamicOptions.cmake)

# install vcpkg dependencies: - should be called before defining project()
# run_vcpkg()

# Set the project name and language
project(myproject LANGUAGES CXX C)

# Set PCH to be on by default for all non-Developer Mode Builds
set(ENABLE_PCH_USER_DEFAULT ON)

# enable Conan
set(ENABLE_CONAN_DEFAULT ON)

# Initialize project_options variable related to this project
# This overwrites `project_options` and sets `project_warnings`
# This also accepts the same arguments as `project_options`.
dynamic_project_options(
  # set the common headers you want to precompile
  PCH_HEADERS <vector> <string> <fmt/format.h> <Eigen/Dense>
)

Add your executables, etc., as described above.

License

This project can be used under the terms of either the MIT license or the Unlicense depending on your choice (as you wish). Both are permissive open-source licenses that allow any usage, commercial or non-commercial, copying, distribution, publishing, modification, etc. Feel free to choose whichever is more suitable for you.

License

Jason5480/project_options

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages