Obtaining CMakePPLang

This section details two ways of obtaining CMakePPLang for use in your build system. The easiest way to use the CMakePP language in your project is Automatically Downloading and Including CMakePPLang.

Alternatively you can choose Downloading CMakePPLang and Building Manually, which is a bit more complicated.

Automatically Downloading and Including CMakePPLang

As a convenience to your users you can make it so that your build system automatically downloads CMakePPLang and includes it. The easiest way to do this is to put the following CMake script in a file PROJECT_ROOT/cmake/get_cmakepp_lang.cmake:

include_guard()

#[[
# This function encapsulates the process of getting CMakePPLang using CMake's
# FetchContent module. We have encapsulated it in a function so we can set
# the options for its configure step without affecting the options for the
# parent project's configure step (namely we do not want to build CMakePPLang's
# unit tests).
#]]
function(get_cmakepp_lang)

    # Store whether we are building tests or not, then turn off the tests
    set(build_testing_old "${BUILD_TESTING}")
    set(BUILD_TESTING OFF CACHE BOOL "" FORCE)

    # Download CMakePPLang and bring it into scope
    include(FetchContent)
    FetchContent_Declare(
        cmakepp_lang
        GIT_REPOSITORY https://github.com/CMakePP/CMakePPLang
    )
    FetchContent_MakeAvailable(cmakepp_lang)

    set(
        CMAKE_MODULE_PATH "${CMAKE_MODULE_PATH}" "${cmakepp_lang_SOURCE_DIR}/cmake"
        PARENT_SCOPE
    )

    # Restore the previous value
    set(BUILD_TESTING "${build_testing_old}" CACHE BOOL "" FORCE)
endfunction()

# Call the function we just wrote to get CMakePPLang
get_cmakepp_lang()

# Include CMakePPLang
include(cmakepp_lang/cmakepp_lang)

and then in your top level CMakeLists.txt (assumed to be in the same directory as the cmake directory you put get_cmakepp_lang.cmake in) add the line:

include("${PROJECT_SOURCE_DIR}/cmake/get_cmakepp_lang.cmake")

Your project will now download CMakePPLang automatically as part of the CMake configuration.

Pinning a CMakePPLang Version

Sometimes bugs may be found in a particular version of CMakePPLang (that will hopefully be fixed quickly in the next version!). In this case, it is useful to pin a previous version so you can continue your work uninterupted. To pin a specific version of CMakePPLang, use the GIT_TAG <version_tag> argument for FetchContent_Declare(). For example, to pin version v1.0.2, use the following FetchContent_Declare() call:

FetchContent_Declare(
    cmakepp_lang
    GIT_REPOSITORY https://github.com/CMakePP/CMakePPLang
    GIT_TAG v1.0.2
)

Downloading CMakePPLang and Building Manually

Although convenient, automatically downloading and including CMakePPLang is not as useful when attempting to test local changes made to CMakePPLang. In this scenario, CMakePPLang can be manually downloaded from GitHub either through the web interface or by using the git clone command:

git clone https://github.com/CMakePP/CMakePPLang.git

Once CMakePPLang has been downloaded and changes have been made, create or navigate to your project that relies on the new CMakePPLang functionality, which we will refer to here as ExampleProject. Create a CMake file to fetch CMakePPLang in ExampleProject that will use CMakePPLang at ExampleProject/cmake/get_cmakepp_lang.cmake, and add the following text:

include_guard()

#[[
# This function encapsulates the process of getting CMakePPLang using CMake's
# FetchContent module. We have encapsulated it in a function so we can set
# the options for its configure step without affecting the options for the
# parent project's configure step (namely we do not want to build CMakePPLang's
# unit tests).
#]]
function(get_cmakepp_lang)

    # Store whether we are building tests or not, then turn off the tests
    set(build_testing_old "${BUILD_TESTING}")
    set(BUILD_TESTING OFF CACHE BOOL "" FORCE)

    # Download CMakePPLang and bring it into scope
    include(FetchContent)
    FetchContent_Declare(
        cmakepp_lang
        GIT_REPOSITORY https://github.com/CMakePP/CMakePPLang
    )
    FetchContent_MakeAvailable(cmakepp_lang)

    set(
        CMAKE_MODULE_PATH "${CMAKE_MODULE_PATH}" "${cmakepp_lang_SOURCE_DIR}/cmake"
        PARENT_SCOPE
    )

    # Restore the previous value
    set(BUILD_TESTING "${build_testing_old}" CACHE BOOL "" FORCE)
endfunction()

# Call the function we just wrote to get CMakePPLang
get_cmakepp_lang()

# Include CMakePPLang
include(cmakepp_lang/cmakepp_lang)

Then, in the top-level CMakeLists.txt at the root of ExampleProject, add the following line before any code using CMakePPLang:

include("${PROJECT_SOURCE_DIR}/cmake/get_cmakepp_lang.cmake")

So far, ExampleProject is set up to automatically fetch the latest version of CMakePPLang from https://github.com/CMakePP/CMakePPLang, but we want to use your modified, local version. ExampleProject can be instructed to use your local CMakePPLang if you set the FETCHCONTENT_SOURCE_DIR_CMAKEPP_LANG variable to the directory containing your modified, local version. There are multiple ways to set the FETCHCONTENT_SOURCE_DIR_CMAKEPP_LANG variable, ranked here from most recommended to least recommended:

Set the value in a CMake toolchain file (toolchain.cmake). You can specify for your project to use this toolchain by adding one of the following arguments to your CMake configure step command: -DCMAKE_TOOLCHAIN_FILE=path/to/file or --toolchain /path/to/file.
Set the value as an argument to the CMake configure command with the argument: -DFETCHCONTENT_SOURCE_DIR_CMAKEPP_LANG=path/to/ cmakepp_lang
Set the value directly in a CMakeLists.txt file. However, since CMake build files should be portable to different systems, it is strongly discouraged to hard-code local paths into your CMake files.

Your project will now use your modified, local version of CMakePPLang during CMake configuration.