vcpkg/docs/maintainers/vcpkg_cmake_configure.md

vcpkg_cmake_configure

The latest version of this document lives in the vcpkg repo.

Configure a CMake-based project.

Usage

vcpkg_cmake_configure(
    SOURCE_PATH <source-path>
    [DISABLE_PARALLEL_CONFIGURE]
    [NO_CHARSET_FLAG]
    [WINDOWS_USE_MSBUILD]
    [GENERATOR <generator>]
    [LOGFILE_BASE <logname-base>]
    [OPTIONS
        <configure-setting>...]
    [OPTIONS_RELEASE
        <configure-setting>...]
    [OPTIONS_DEBUG
        <configure-setting>...]
    [MAYBE_UNUSED_VARIABLES
        <option-name>...]
)

To use this function, you must depend on the helper port vcpkg-cmake:

"dependencies": [
  {
    "name": "vcpkg-cmake",
    "host": true
  }
]

Parameters

SOURCE_PATH

Specifies the directory containing the CMakeLists.txt.

This value is usually obtained as a result of calling a source acquisition command like vcpkg_from_github().

DISABLE_PARALLEL_CONFIGURE

Disables running the CMake configure step in parallel.

By default vcpkg disables writing back to the source directory (via the undocumented CMake flag CMAKE_DISABLE_SOURCE_CHANGES) and (on Windows) configures Release and Debug in parallel. This flag instructs vcpkg to allow source directory writes and to execute the configure steps sequentially.

NO_CHARSET_FLAG

Disables passing /utf-8 when using the built-in Windows toolchain.

This is needed for libraries that set their own source code's character set when targeting MSVC. See the MSVC documentation for /utf-8 for more information.

WINDOWS_USE_MSBUILD

Use MSBuild instead of another generator when targeting a Windows platform.

By default vcpkg prefers to use Ninja as the CMake Generator for all platforms. However, there are edge cases where MSBuild has different behavior than Ninja. This flag should only be passed if the project requires MSBuild to build correctly. This flag has no effect for MinGW targets.

GENERATOR

Specifies the Generator to use.

By default vcpkg prefers to use Ninja as the CMake Generator for all platforms, or "Unix Makefiles" for non-Windows platforms when Ninja is not available. This parameter can be used for edge cases where project-specific buildsystems depend on a particular generator.

LOGFILE_BASE

An alternate root name for the configure logs.

Defaults to config-${TARGET_TRIPLET}. It should not contain any path separators. Logs will be generated matching the pattern ${CURRENT_BUILDTREES_DIR}/${LOGFILE_BASE}-<suffix>.log

OPTIONS

Additional options to pass to CMake during the configuration.

See also Implicit Options.

OPTIONS_RELEASE

Additional options to pass to CMake during the Release configuration.

These are in addition to OPTIONS.

OPTIONS_DEBUG

Additional options to pass to CMake during the Debug configuration.

These are in addition to OPTIONS.

MAYBE_UNUSED_VARIABLES

List of CMake options that may not be read during the configure step.

vcpkg will warn about any options outside this list that were not read during the CMake configure step. This list should contain options that are only read during certain configurations (such as when VCPKG_LIBRARY_LINKAGE is "static" or when certain features are enabled).

Implicit Options

This command automatically provides several options to CMake.

• CMAKE_BUILD_TYPE is set to "Release" or "Debug" as appropriate.
• BUILD_SHARED_LIBS is set according to the value of VCPKG_LIBRARY_LINKAGE.
• CMAKE_INSTALL_PREFIX=${CURRENT_PACKAGES_DIR}</debug> as appropriate to the configuration
• CMAKE_TOOLCHAIN_FILE and VCPKG_CHAINLOAD_TOOLCHAIN_FILE are set to include the vcpkg toolchain file and the triplet toolchain.
• CMAKE_SYSTEM_NAME=${VCPKG_CMAKE_SYSTEM_NAME}. If VCPKG_CMAKE_SYSTEM_NAME is unset, defaults to "Windows".
• CMAKE_SYSTEM_VERSION=${VCPKG_CMAKE_SYSTEM_VERSION} if VCPKG_CMAKE_SYSTEM_VERSION is set.
• CMAKE_EXPORT_NO_PACKAGE_REGISTRY=ON
• CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY=ON
• CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY=ON
• CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP=TRUE
• CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION=ON
• CMAKE_INSTALL_LIBDIR:STRING=lib
• CMAKE_INSTALL_BINDIR:STRING=bin

This command also passes all options in VCPKG_CMAKE_CONFIGURE_OPTIONS and the configuration-specific options from VCPKG_CMAKE_CONFIGURE_OPTIONS_RELEASE or VCPKG_CMAKE_CONFIGURE_OPTIONS_DEBUG.

Finally, there are additional internal options passed in (with a VCPKG_ prefix) that should not be depended upon.

Examples

vcpkg_from_github(OUT_SOURCE_PATH source_path ...)
vcpkg_cmake_configure(
    SOURCE_PATH "${source_path}"
    OPTIONS
        -DBUILD_EXAMPLES=OFF
        -DBUILD_TESTS=OFF
)
vcpkg_cmake_install()

Search microsoft/vcpkg for Examples

Remarks

This command replaces vcpkg_configure_cmake().

Source

ports/vcpkg-cmake/vcpkg_cmake_configure.cmake