`project_options` function

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

`project` and `project_options`

Here is an example of the usage:

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)

include(FetchContent)
if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.24.0")
  cmake_policy(SET CMP0135 NEW)
endif()

# Add project_options from 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)
set(PROJECT_OPTIONS_VERSION "v0.41.0")
FetchContent_Declare(
  _project_options
  URL https://github.com/aminya/project_options/archive/refs/tags/${PROJECT_OPTIONS_VERSION}.zip)
FetchContent_MakeAvailable(_project_options)
include(${_project_options_SOURCE_DIR}/Index.cmake)

# install vcpkg dependencies: - should be called before defining project()
run_vcpkg(
    VCPKG_URL "https://github.com/microsoft/vcpkg.git"
    VCPKG_REV "86a181505ac6460f98496a79abdee6a0f49905ec"
)
# Install conan dependencies: - should be called before defining project()
run_conan()

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

# Build Features
option(FEATURE_TESTS "Enable the tests" OFF)
option(FEATURE_DOCS "Enable the docs" OFF)

# vcpkg test feature
if(FEATURE_TESTS)
  list(APPEND VCPKG_MANIFEST_FEATURES "tests")
endif()

# Enable sanitizers and static analyzers when running the tests
if(FEATURE_TESTS)
  set(ENABLE_CLANG_TIDY "ENABLE_CLANG_TIDY")
  set(ENABLE_CPPCHECK "ENABLE_CPPCHECK")
  set(ENABLE_COVERAGE "ENABLE_COVERAGE")

  set(ENABLE_SANITIZER_ADDRESS "ENABLE_SANITIZER_ADDRESS")
  set(ENABLE_SANITIZER_UNDEFINED "ENABLE_SANITIZER_UNDEFINED")
endif()

# Enable doxgen for the docs
if(FEATURE_DOCS)
  set(ENABLE_DOXYGEN "ENABLE_DOXYGEN")
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(
      PREFIX "myproject"
      ENABLE_CACHE
      ${ENABLE_CPPCHECK}
      ${ENABLE_CLANG_TIDY}
      ENABLE_VS_ANALYSIS
      # ENABLE_INTERPROCEDURAL_OPTIMIZATION
      # ENABLE_NATIVE_OPTIMIZATION
      ${ENABLE_DOXYGEN}
      ${ENABLE_COVERAGE}
      ${ENABLE_SANITIZER_ADDRESS}
      ${ENABLE_SANITIZER_UNDEFINED}
      # ${ENABLE_SANITIZER_THREAD}
      # ${ENABLE_SANITIZER_MEMORY}
      # ENABLE_SANITIZER_POINTER_COMPARE
      # ENABLE_SANITIZER_POINTER_SUBTRACT
      # ENABLE_CONTROL_FLOW_PROTECTION
      # ENABLE_STACK_PROTECTION
      # ENABLE_OVERFLOW_PROTECTION
      # ENABLE_ELF_PROTECTION
      # ENABLE_RUNTIME_SYMBOLS_RESOLUTION
      # ENABLE_COMPILE_COMMANDS_SYMLINK
      # ENABLE_PCH
      # PCH_HEADERS
      # WARNINGS_AS_ERRORS
      # ENABLE_INCLUDE_WHAT_YOU_USE
      # ENABLE_GCC_ANALYZER
      # ENABLE_BUILD_WITH_TIME_TRACE
      # ENABLE_UNITY
      # LINKER "lld"
)

Then add the executables or libraries to the project:

executable usage 

add_executable(main main.cpp)

# link project_options/warnings
target_link_libraries(main
  PRIVATE myproject_project_options myproject_project_warnings
)

# Find dependencies:
target_find_dependencies(main
  PRIVATE_CONFIG
  fmt
  Eigen3
)

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

# Package the project
package_project(TARGETS main)

library usage 

add_library(my_lib "./src/my_lib/lib.cpp")

# link project_options/warnings
target_link_libraries(my_lib
  PRIVATE myproject_project_options myproject_project_warnings
)

# Includes:
target_include_interface_directories(my_lib "${CMAKE_CURRENT_SOURCE_DIR}/include")

# Find dependencies:
target_find_dependencies(my_lib
  PRIVATE_CONFIG
  fmt
  Eigen3
)

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

# Package the project
package_project(
  # Note that you must export `myproject_project_options` and `myproject_project_warnings` for `my_lib`
  TARGETS my_lib myproject_project_options myproject_project_warnings
)

header-only library usage 

add_library(my_header_lib INTERFACE)

# link project_options/warnings
target_link_libraries(my_header_lib
  INTERFACE myproject_project_options myproject_project_warnings
)

# Includes:
target_include_interface_directories(my_header_lib "${CMAKE_CURRENT_SOURCE_DIR}/include")

# Find dependencies:
target_find_dependencies(my_header_lib
  INTERFACE_CONFIG
  fmt
  Eigen3
)

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

# Package the project
package_project(
  TARGETS my_header_lib myproject_project_options myproject_project_warnings
)

`project_options` parameters

project_options function 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_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: Enable undefined behavior sanitizer
ENABLE_SANITIZER_THREAD: Enable thread sanitizer
ENABLE_SANITIZER_MEMORY: Enable memory sanitizer
ENABLE_COMPILE_COMMANDS_SYMLINK: Enable compile_commands.json symlink creation
ENABLE_PCH: Enable Precompiled Headers
ENABLE_INCLUDE_WHAT_YOU_USE: Enable static analysis with include-what-you-use
ENABLE_GCC_ANALYZER: Enable static analysis with GCC (10+) analyzer
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.

`run_vcpkg`

Install vcpkg and vcpkg dependencies:

run_vcpkg()

Or by specifying the options

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

Note that it should be called before defining project().

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
VCPKG_UPDATE_THRESHOLD: (Defaults to 3600 seconds). This option allows setting the time threshold in seconds for updating the vcpkg registry. If ENABLE_VCPKG_UPDATE is enabled, the vcpkg registry will be updated if the last update was more than VCPKG_UPDATE_THRESHOLD seconds ago.

`package_project`

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}

`target_include_interface_directories`

target_include_interface_directories(<target_name> [<include_dir> ...])

This function includes include_dir as the header interface directory of target_name. If the given include_dir path is relative, the function assumes the path is ${CMAKE_CURRENT_SOURCE_DIR}/${include_dir} (i.e. the path is related to the path of CMakeLists.txt which calls the function).

A property named PROJECT_OPTIONS_INTERFACE_DIRECTORIES will be created in target_name to represent the header directory path. When adding the target to package_project, directories in this property will be automatically added.

You can call this function with the same target_name multiple times to add more header interface directories.

add_library(my_header_lib INTERFACE)
target_include_interface_directories(my_header_lib "${CMAKE_CURRENT_SOURCE_DIR}/include")
target_include_interface_directories(my_header_lib ../include)

add_library(my_lib)
target_sources(my_lib PRIVATE function.cpp)
target_include_interface_directories(my_lib include ../include)

package_project(TARGETS my_header_lib my_lib)

`target_find_dependencies`

target_find_dependencies(<target_name>
  [
   <INTERFACE|PUBLIC|PRIVATE|INTERFACE_CONFIG|PUBLIC_CONFIG|PRIVATE_CONFIG>
   [dependency1...]
  ]...
  [
   <INTERFACE|PUBLIC|PRIVATE|INTERFACE_CONFIG|PUBLIC_CONFIG|PRIVATE_CONFIG>
   [PACKAGE <dependency_name> [find_package() argument1...]]...
  ]...
)

This macro calls find_package(${dependency} [CONFIG] REQUIRED [OTHER_ARGUMENTS]) for all dependencies required and binds them to the target.

Properties named PROJECT_OPTIONS_<PRIVATE|PUBLIC|INTERFACE>[_CONFIG]_DEPENDENCIES will be created in target_name to represent corresponding dependencies. When adding the target to package_project, directories in this property will be automatically added.

You can call this function with the same target_name multiple times to add more dependencies.

add_library(my_lib)
target_sources(my_lib PRIVATE function.cpp)
target_include_interface_directories(my_lib "${CMAKE_CURRENT_SOURCE_DIR}/include")

target_find_dependencies(my_lib
  PUBLIC_CONFIG
    fmt

  PRIVATE_CONFIG
    PACKAGE Microsoft.GSL
    PACKAGE Qt6 COMPONENTS Widgets
)
target_find_dependencies(my_lib
  PRIVATE
    PACKAGE range-v3 CONFIG QUIET  # you can also set CONFIG here
)

target_link_system_libraries(my_lib
  PUBLIC
  fmt::fmt

  PRIVATE
  Microsoft.GSL::GSL
  Qt6::Widgets
  range-v3::range-v3
)

package_project(TARGETS my_lib)

`target_include_system_directories`

Include a system directory (which suppresses its warnings).

The function accepts the same arguments as target_include_directories. It has the mentioned features of target_link_system_libraries.

`target_link_system_libraries`

Link multiple library targets as system libraries (which suppresses their warnings).

The function 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}.

`dynamic_project_options`

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 dynamic 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.

Here is an example of how to use dynamic_project_options:

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)

include(FetchContent)
if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.24.0")
  cmake_policy(SET CMP0135 NEW)
endif()

# Add project_options from 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)
set(PROJECT_OPTIONS_VERSION "v0.41.0")
FetchContent_Declare(
  _project_options
  URL https://github.com/aminya/project_options/archive/refs/tags/${PROJECT_OPTIONS_VERSION}.zip)
FetchContent_MakeAvailable(_project_options)
include(${_project_options_SOURCE_DIR}/Index.cmake)

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

# 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)

# 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.

`target_disable_static_analysis`

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)
target_disable_include_what_you_use(target)
target_disable_gcc_analyzer(target)

`check_sanitizers_support`

Detect sanitizers support for compiler. You don’t need to call this function directly anymore.

Note that some sanitizers cannot be enabled together, and this function doesn’t check that. You should decide which sanitizers to enable based on your needs.

Output variables:

ENABLE_SANITIZER_ADDRESS: Address sanitizer is supported
ENABLE_SANITIZER_UNDEFINED: Undefined behavior sanitizer is supported
ENABLE_SANITIZER_LEAK: Leak sanitizer is supported
ENABLE_SANITIZER_THREAD: Thread sanitizer is supported
ENABLE_SANITIZER_MEMORY: Memory sanitizer is supported
ENABLE_SANITIZER_POINTER_COMPARE: Pointer compare sanitizer is supported
ENABLE_SANITIZER_POINTER_SUBTRACT: Pointer subtract sanitizer is supported

check_sanitizers_support(ENABLE_SANITIZER_ADDRESS
                         ENABLE_SANITIZER_UNDEFINED
                         ENABLE_SANITIZER_LEAK
                         ENABLE_SANITIZER_THREAD
                         ENABLE_SANITIZER_MEMORY
                         ENABLE_SANITIZER_POINTER_COMPARE
                         ENABLE_SANITIZER_POINTER_SUBTRACT)

# then pass the sanitizers (e.g. ${ENABLE_SANITIZER_ADDRESS}) to project_options(... ${ENABLE_SANITIZER_ADDRESS} ...)

`find_linker`

Find a linker prefering the linkers in this order: sold, mold, lld, gold, the system linker

Output variables:

LINKER: the linker to use

find_linker(LINKER)
# then pass ${LINKER} to project_options(... LINKER ${LINKER} ...)

`enable_cross_compiler`

NOTE: more documentation/examples for this feature is welcome. See the tests/rpi3, tests/rpi4, tests/emscripten, tests-rpi4-vcpkg directories in the repositpry for full examples.

The following calls enable_cross_compiler to enable the cross-compiler as the current toolchain.

enable_cross_compiler(
  CC "arm-none-eabi-gcc"
  CXX "arm-none-eabi-g++"
  TARGET_ARCHITECTURE "arm"
  CROSS_ROOT "/usr/arm-none-eabi-gcc"
  CROSS_TRIPLET "arm-none-eabi-gcc"
)

The following examples enables cross-compiling when it is opt-in.

# opt-in cross-compiling
if(ENABLE_AARCH64_CROSS_COMPILING)
  # my custom aarch64 settings
  enable_cross_compiler(
    DEFAULT_TRIPLET "arm64-linux"
    CC "aarch64-linux-gnu-gcc"
    CXX "aarch64-linux-gnu-g++"
    TARGET_ARCHITECTURE "arm64-linux"
    CROSS_ROOT "/usr/gcc-aarch64-linux-gnu"
    CROSS_TRIPLET "aarch64-linux-gnu"
    #TOOLCHAIN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/cmake/my-toolchain.cmake"
  )
else()
  option(ENABLE_CROSS_COMPILING "Detect cross compiler and setup toolchain" OFF)
  if(ENABLE_CROSS_COMPILING)
    enable_cross_compiler()
  endif()
endif()

enable_cross_compiler auto-detects the following cross-compilers, when setting DEFAULT_TRIPLET:

mingw-w64 x86_64-w64-mingw32.toolchain.cmake
emscripten

Example:

-DENABLE_CROSS_COMPILING:BOOL=ON -DDEFAULT_TRIPLET=x64-mingw-dynamic
-DENABLE_CROSS_COMPILING:BOOL=ON -DDEFAULT_TRIPLET=wasm32-emscripten

For arm-linux or arm64-linux, you must set the compiler:

aarch64-linux-gnu aarch64-linux.toolchain.cmake
arm-linux-gnueabi, arm-linux-gnueabihf arm-linux.toolchain.cmake

Example:

-DENABLE_CROSS_COMPILING:BOOL=ON -DCMAKE_C_COMPILER=gcc-aarch64-linux-gnu-gcc -DCMAKE_CXX_COMPILER=gcc-aarch64-linux-gnu-g++ -DDEFAULT_TRIPLET=arm64-linux
-DENABLE_CROSS_COMPILING:BOOL=ON -DCMAKE_C_COMPILER=arm-linux-gnueabihf-gcc -DCMAKE_CXX_COMPILER=arm-linux-gnueabi-g++ -DDEFAULT_TRIPLET=arm-linux -DCROSS_ROOT=/usr/gcc-arm-linux-gnueabihf

For (bare-metal) you don’t need/can’t set arm-linux/arm64-linux for vcpkg:

arm-none-eabi arm.toolchain.cmake

Example:

-DENABLE_CROSS_COMPILING:BOOL=ON -DCMAKE_C_COMPILER=arm-none-eabi-gcc -DCMAKE_CXX_COMPILER=arm-none-eabi-g++
-DENABLE_CROSS_COMPILING:BOOL=ON -DCMAKE_C_COMPILER=arm-none-eabi-gcc -DCMAKE_CXX_COMPILER=arm-none-eabi-g++ -DTARGET_ARCHITECTURE:STRING=arm -DCROSS_ROOT:STRING="/usr/arm-none-eabi-gcc" -DCROSS_TRIPLET:STRING=arm-none-eabi-gcc

The option for DEFAULT_TRIPLET are the similar to vcpkg triplets

x64-mingw-dynamic
x64-mingw-static
x86-mingw-dynamic
x86-mingw-static
wasm32-emscripten
arm-linux
arm64-linux

`target_link_cuda`

Link 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)

`git_clone`

Clone the given repository to the given path

Input variables:

REPOSITORY_PATH: The path to the repository
REMOTE_URL: The url of the remote to add
REMOTE_NAME: The name of the remote to add (defaults to the remote user)
SHALLOW_SINCE: Create a shallow clone with a history after the specified time. date should be in format of git log –date=raw.
BRANCH: Only clone the given branch
FORCE_CLONE: Force the clone even if the directory exists

Simple example:

git_clone(
  REPOSITORY_PATH
  "./vcpkg"
  REMOTE_URL
  "https://github.com/microsoft/vcpkg.git"
)

Example for a shallow clone and checking out of a specific revision:

git_clone(
  REPOSITORY_PATH
  "$ENV{HOME}/vcpkg"
  REMOTE_URL
  "https://github.com/microsoft/vcpkg.git"
  SHALLOW_SINCE
  "1686087993 -0700"
  BRANCH
  "master"
)
git_checkout(
  REPOSITORY_PATH
  "$ENV{HOME}/vcpkg"
  REVISION
  ecd22cc3acc8ee3c406e566db1e19ece1f17f409
)

`git_pull`

Pull the given repository

If TARGET_REVISION is given, the pull is skipped if the current revision is the same as the target revision.

It will temporarily switch back to the previous branch if the head is detached for updating.

Input variables:

REPOSITORY_PATH: The path to the repository
TARGET_REVISION: if the current revision of the repository is the same as this given revision, the pull is skipped

`git_checkout`

Checkout the given revision

Input variables:

REPOSITORY_PATH: The path to the repository
REVISION: The revision to checkout

git_checkout(
  REPOSITORY_PATH
  "$ENV{HOME}/vcpkg"
  REVISION
  ecd22cc3acc8ee3c406e566db1e19ece1f17f409
)

git_checkout(
  REPOSITORY_PATH
  "./some_repo"
  REVISION
  v1.0.0
)

`git_parse_url`

Parse the given Git url into its components

It expects the url to be in the form of: [protocol://][host]/user/repo[.git]

Input variables:

INPUT_URL: The url to parse

Output variables:

PROTOCOL: The protocol of the url (http, https, ssh, etc)
HOST: The host of the url (github, gitlab, etc)
USER: The user of the url (username, organization, etc)
REPOSITORY_NAME: The repository of the url (project name)
FULL_URL: The url of the repository (protocol + host + user + repo)

`git_add_remote`

Add a remote to the given repository on the given path

Input variables:

REPOSITORY_PATH: The path to the repository
REMOTE_URL: The url of the remote to add
REMOTE_NAME: The name of the remote to add (defaults to the remote user)

`git_revision`

Find the current git revision of the given repository

Input variables:

REPOSITORY_PATH: The path to the repository

Output variables:

REVISION: The variable to store the revision in

`git_is_detached`

Check if the given repository is in a detached state

Input variables:

REPOSITORY_PATH: The path to the repository

Output variables:

IS_DETACHED: The variable to store the result in

`git_switch_back`

Detect if the head is detached, if so, switch/checkout back If the switch/checkout back fails or goes to a detached state, try to checkout the default branch

This is used before updating the repository in a pull

Input variables:

REPOSITORY_PATH: The path to the repository

`git_wait`

Wait for the git lock file to be released

Input variables:

REPOSITORY_PATH: The path to the repository
TIMEOUT_COUNTER: The number of times to wait before timing out, each time 1 seconds (defaults to 120)

`git_default_branch`

Get the default branch of the given repository. Defaults to master in case of failure

Input variables: - REPOSITORY_PATH: The path to the repository

Output variables: - default_branch: The variable to store the default branch in

git_default_branch(
  REPOSITORY_PATH
  "$ENV{HOME}/vcpkg"
  default_branch
)

project_options function

project and project_options

executable usage

library usage

header-only library usage

project_options parameters

run_vcpkg

package_project

target_include_interface_directories

target_find_dependencies

target_include_system_directories

target_link_system_libraries

dynamic_project_options

target_disable_static_analysis

check_sanitizers_support

find_linker

enable_cross_compiler

target_link_cuda

git_clone

git_pull

git_checkout

git_parse_url

git_add_remote

git_revision

git_is_detached

git_switch_back

git_wait

git_default_branch

`project_options` function

`project` and `project_options`

executable usage 

library usage 

header-only library usage 

`project_options` parameters

`run_vcpkg`

`package_project`

`target_include_interface_directories`

`target_find_dependencies`

`target_include_system_directories`

`target_link_system_libraries`

`dynamic_project_options`

`target_disable_static_analysis`

`check_sanitizers_support`

`find_linker`

`enable_cross_compiler`

`target_link_cuda`

`git_clone`

`git_pull`

`git_checkout`

`git_parse_url`

`git_add_remote`

`git_revision`

`git_is_detached`

`git_switch_back`

`git_wait`

`git_default_branch`