diff options
Diffstat (limited to 'Help/variable')
700 files changed, 9329 insertions, 0 deletions
diff --git a/Help/variable/ANDROID.rst b/Help/variable/ANDROID.rst new file mode 100644 index 0000000..68dccf2 --- /dev/null +++ b/Help/variable/ANDROID.rst @@ -0,0 +1,7 @@ +ANDROID +------- + +.. versionadded:: 3.7 + +Set to ``1`` when the target system (:variable:`CMAKE_SYSTEM_NAME`) is +``Android``. diff --git a/Help/variable/APPLE.rst b/Help/variable/APPLE.rst new file mode 100644 index 0000000..810d5fc --- /dev/null +++ b/Help/variable/APPLE.rst @@ -0,0 +1,5 @@ +APPLE +----- + +Set to ``True`` when the target system is an Apple platform +(macOS, iOS, tvOS or watchOS). diff --git a/Help/variable/BORLAND.rst b/Help/variable/BORLAND.rst new file mode 100644 index 0000000..badb733 --- /dev/null +++ b/Help/variable/BORLAND.rst @@ -0,0 +1,6 @@ +BORLAND +------- + +``True`` if the Borland compiler is being used. + +This is set to ``true`` if the Borland compiler is being used. diff --git a/Help/variable/BSD.rst b/Help/variable/BSD.rst new file mode 100644 index 0000000..fdfe5ec --- /dev/null +++ b/Help/variable/BSD.rst @@ -0,0 +1,7 @@ +BSD +--- + +.. versionadded:: 3.25 + +Set to a string value when the target system is BSD. This value can be one of +the following: DragonFlyBSD, FreeBSD, OpenBSD, or NetBSD. diff --git a/Help/variable/BUILD_SHARED_LIBS.rst b/Help/variable/BUILD_SHARED_LIBS.rst new file mode 100644 index 0000000..53087b2 --- /dev/null +++ b/Help/variable/BUILD_SHARED_LIBS.rst @@ -0,0 +1,10 @@ +BUILD_SHARED_LIBS +----------------- + +Global flag to cause :command:`add_library` to create shared libraries if on. + +If present and true, this will cause all libraries to be built shared +unless the library was explicitly added as a static library. This +variable is often added to projects as an :command:`option` so that each user +of a project can decide if they want to build the project using shared or +static libraries. diff --git a/Help/variable/CACHE.rst b/Help/variable/CACHE.rst new file mode 100644 index 0000000..d5489c8 --- /dev/null +++ b/Help/variable/CACHE.rst @@ -0,0 +1,20 @@ +CACHE +----- + +.. versionadded:: 3.13 + +Operator to read cache variables. + +Use the syntax ``$CACHE{VAR}`` to read cache entry ``VAR``. +See the :ref:`cmake-language(7) variables <CMake Language Variables>` +documentation for more complete documentation of the interaction of +normal variables and cache entries. + +When evaluating :ref:`Variable References` of the form ``${VAR}``, +CMake first searches for a normal variable with that name, and if not +found CMake will search for a cache entry with that name. +The ``$CACHE{VAR}`` syntax can be used to do direct cache lookup and +ignore any existing normal variable. + +See the :command:`set` and :command:`unset` commands to see how to +write or remove cache variables. diff --git a/Help/variable/CMAKE_ABSOLUTE_DESTINATION_FILES.rst b/Help/variable/CMAKE_ABSOLUTE_DESTINATION_FILES.rst new file mode 100644 index 0000000..b6d0054 --- /dev/null +++ b/Help/variable/CMAKE_ABSOLUTE_DESTINATION_FILES.rst @@ -0,0 +1,9 @@ +CMAKE_ABSOLUTE_DESTINATION_FILES +-------------------------------- + +List of files which have been installed using an ``ABSOLUTE DESTINATION`` path. + +This variable is defined by CMake-generated ``cmake_install.cmake`` +scripts. It can be used (read-only) by programs or scripts that +source those install scripts. This is used by some CPack generators +(e.g. RPM). diff --git a/Help/variable/CMAKE_ADSP_ROOT.rst b/Help/variable/CMAKE_ADSP_ROOT.rst new file mode 100644 index 0000000..f6f3927 --- /dev/null +++ b/Help/variable/CMAKE_ADSP_ROOT.rst @@ -0,0 +1,11 @@ +CMAKE_ADSP_ROOT +--------------- + +.. versionadded:: 3.24 + +When :ref:`Cross Compiling for ADSP SHARC/Blackfin`, +this variable holds the absolute path to the latest CCES or VDSP++ install. +The directory is expected to contain the ``cc21k.exe`` and ``ccblkfn.exe`` compilers. +This will be set automatically if a default install of CCES or VDSP++ can be found. + +See also the :envvar:`ADSP_ROOT` environment variable. diff --git a/Help/variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS.rst b/Help/variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS.rst new file mode 100644 index 0000000..699fe0f --- /dev/null +++ b/Help/variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS.rst @@ -0,0 +1,8 @@ +CMAKE_AIX_EXPORT_ALL_SYMBOLS +---------------------------- + +.. versionadded:: 3.17 + +Default value for :prop_tgt:`AIX_EXPORT_ALL_SYMBOLS` target property. +This variable is used to initialize the property on each target as it is +created. diff --git a/Help/variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS.rst b/Help/variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS.rst new file mode 100644 index 0000000..2d6b4b9 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS +------------------------------------ + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_ANT_ADDITIONAL_OPTIONS` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_API.rst b/Help/variable/CMAKE_ANDROID_API.rst new file mode 100644 index 0000000..aba9b6e --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_API.rst @@ -0,0 +1,14 @@ +CMAKE_ANDROID_API +----------------- + +.. versionadded:: 3.1 + +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this variable may be set to specify the default value for the +:prop_tgt:`ANDROID_API` target property. See that target property for +additional information. + +When :ref:`Cross Compiling for Android`, the :variable:`CMAKE_SYSTEM_VERSION` +variable represents the Android API version number targeted. For historical +reasons, if a toolchain file sets ``CMAKE_ANDROID_API``, but not +``CMAKE_SYSTEM_VERSION``, the latter will be initialized using the former. diff --git a/Help/variable/CMAKE_ANDROID_API_MIN.rst b/Help/variable/CMAKE_ANDROID_API_MIN.rst new file mode 100644 index 0000000..a0d2ab4 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_API_MIN.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_API_MIN +--------------------- + +.. versionadded:: 3.2 + +Default value for the :prop_tgt:`ANDROID_API_MIN` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_ARCH.rst b/Help/variable/CMAKE_ANDROID_ARCH.rst new file mode 100644 index 0000000..9f12742 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARCH.rst @@ -0,0 +1,21 @@ +CMAKE_ANDROID_ARCH +------------------ + +.. versionadded:: 3.4 + +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this variable may be set to specify the default value for the +:prop_tgt:`ANDROID_ARCH` target property. See that target property for +additional information. + +Otherwise, when :ref:`Cross Compiling for Android`, this variable provides +the name of the Android architecture corresponding to the value of the +:variable:`CMAKE_ANDROID_ARCH_ABI` variable. The architecture name +may be one of: + +* ``arm`` +* ``arm64`` +* ``mips`` +* ``mips64`` +* ``x86`` +* ``x86_64`` diff --git a/Help/variable/CMAKE_ANDROID_ARCH_ABI.rst b/Help/variable/CMAKE_ANDROID_ARCH_ABI.rst new file mode 100644 index 0000000..5a2e3ec --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARCH_ABI.rst @@ -0,0 +1,19 @@ +CMAKE_ANDROID_ARCH_ABI +---------------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android`, this variable specifies the +target architecture and ABI to be used. Valid values are: + +* ``arm64-v8a`` +* ``armeabi-v7a`` +* ``armeabi-v6`` +* ``armeabi`` +* ``mips`` +* ``mips64`` +* ``x86`` +* ``x86_64`` + +See also the :variable:`CMAKE_ANDROID_ARM_MODE` and +:variable:`CMAKE_ANDROID_ARM_NEON` variables. diff --git a/Help/variable/CMAKE_ANDROID_ARM_MODE.rst b/Help/variable/CMAKE_ANDROID_ARM_MODE.rst new file mode 100644 index 0000000..973ff7e --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARM_MODE.rst @@ -0,0 +1,9 @@ +CMAKE_ANDROID_ARM_MODE +---------------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android` and :variable:`CMAKE_ANDROID_ARCH_ABI` +is set to one of the ``armeabi`` architectures, set ``CMAKE_ANDROID_ARM_MODE`` +to ``ON`` to target 32-bit ARM processors (``-marm``). Otherwise, the +default is to target the 16-bit Thumb processors (``-mthumb``). diff --git a/Help/variable/CMAKE_ANDROID_ARM_NEON.rst b/Help/variable/CMAKE_ANDROID_ARM_NEON.rst new file mode 100644 index 0000000..6b9cf08 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARM_NEON.rst @@ -0,0 +1,8 @@ +CMAKE_ANDROID_ARM_NEON +---------------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android` and :variable:`CMAKE_ANDROID_ARCH_ABI` +is set to ``armeabi-v7a`` set ``CMAKE_ANDROID_ARM_NEON`` to ``ON`` to target +ARM NEON devices. diff --git a/Help/variable/CMAKE_ANDROID_ASSETS_DIRECTORIES.rst b/Help/variable/CMAKE_ANDROID_ASSETS_DIRECTORIES.rst new file mode 100644 index 0000000..3de2be4 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ASSETS_DIRECTORIES.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_ASSETS_DIRECTORIES +-------------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_ASSETS_DIRECTORIES` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_EXCEPTIONS.rst b/Help/variable/CMAKE_ANDROID_EXCEPTIONS.rst new file mode 100644 index 0000000..6dd44f8 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_EXCEPTIONS.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_EXCEPTIONS +------------------------ + +.. versionadded:: 3.20 + +When :ref:`Cross Compiling for Android with the NDK`, this variable may be set +to specify whether exceptions are enabled. diff --git a/Help/variable/CMAKE_ANDROID_GUI.rst b/Help/variable/CMAKE_ANDROID_GUI.rst new file mode 100644 index 0000000..821bbee --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_GUI.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_GUI +----------------- + +.. versionadded:: 3.1 + +Default value for the :prop_tgt:`ANDROID_GUI` target property of +executables. See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_JAR_DEPENDENCIES.rst b/Help/variable/CMAKE_ANDROID_JAR_DEPENDENCIES.rst new file mode 100644 index 0000000..80ab842 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_JAR_DEPENDENCIES.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_JAR_DEPENDENCIES +------------------------------ + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_JAR_DEPENDENCIES` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_JAR_DIRECTORIES.rst b/Help/variable/CMAKE_ANDROID_JAR_DIRECTORIES.rst new file mode 100644 index 0000000..4d148d8 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_JAR_DIRECTORIES.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_JAR_DIRECTORIES +----------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_JAR_DIRECTORIES` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_JAVA_SOURCE_DIR.rst b/Help/variable/CMAKE_ANDROID_JAVA_SOURCE_DIR.rst new file mode 100644 index 0000000..021baa0 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_JAVA_SOURCE_DIR.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_JAVA_SOURCE_DIR +----------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_JAVA_SOURCE_DIR` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES.rst b/Help/variable/CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES.rst new file mode 100644 index 0000000..41d4cc3 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES +------------------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_NATIVE_LIB_DEPENDENCIES` target +property. See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES.rst b/Help/variable/CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES.rst new file mode 100644 index 0000000..e87547d --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES +------------------------------------ + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_NATIVE_LIB_DIRECTORIES` target +property. See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_NDK.rst b/Help/variable/CMAKE_ANDROID_NDK.rst new file mode 100644 index 0000000..72ac99e --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK.rst @@ -0,0 +1,9 @@ +CMAKE_ANDROID_NDK +----------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android with the NDK`, this variable holds +the absolute path to the root directory of the NDK. The directory must +contain a ``platforms`` subdirectory holding the ``android-<api>`` +directories. diff --git a/Help/variable/CMAKE_ANDROID_NDK_DEPRECATED_HEADERS.rst b/Help/variable/CMAKE_ANDROID_NDK_DEPRECATED_HEADERS.rst new file mode 100644 index 0000000..40a5c1a --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK_DEPRECATED_HEADERS.rst @@ -0,0 +1,11 @@ +CMAKE_ANDROID_NDK_DEPRECATED_HEADERS +------------------------------------ + +.. versionadded:: 3.9 + +When :ref:`Cross Compiling for Android with the NDK`, this variable +may be set to specify whether to use the deprecated per-api-level +headers instead of the unified headers. + +If not specified, the default will be *false* if using a NDK version +that provides the unified headers and *true* otherwise. diff --git a/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG.rst b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG.rst new file mode 100644 index 0000000..9d61fa4 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG.rst @@ -0,0 +1,8 @@ +CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG +------------------------------------ + +.. versionadded:: 3.7.1 + +When :ref:`Cross Compiling for Android with the NDK`, this variable +provides the NDK's "host tag" used to construct the path to prebuilt +toolchains that run on the host. diff --git a/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst new file mode 100644 index 0000000..15fe18f --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst @@ -0,0 +1,22 @@ +CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION +----------------------------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android with the NDK`, this variable +may be set to specify the version of the toolchain to be used +as the compiler. + +On NDK r19 or above, this variable must be unset or set to ``clang``. + +On NDK r18 or below, this variable must be set to one of these forms: + +* ``<major>.<minor>``: GCC of specified version +* ``clang<major>.<minor>``: Clang of specified version +* ``clang``: Clang of most recent available version + +A toolchain of the requested version will be selected automatically to +match the ABI named in the :variable:`CMAKE_ANDROID_ARCH_ABI` variable. + +If not specified, the default will be a value that selects the latest +available GCC toolchain. diff --git a/Help/variable/CMAKE_ANDROID_NDK_VERSION.rst b/Help/variable/CMAKE_ANDROID_NDK_VERSION.rst new file mode 100644 index 0000000..5428d52 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK_VERSION.rst @@ -0,0 +1,8 @@ +CMAKE_ANDROID_NDK_VERSION +------------------------- + +.. versionadded:: 3.20 + +When :ref:`Cross Compiling for Android with the NDK` and using an +Android NDK version 11 or higher, this variable is provided by +CMake to report the NDK version number. diff --git a/Help/variable/CMAKE_ANDROID_PROCESS_MAX.rst b/Help/variable/CMAKE_ANDROID_PROCESS_MAX.rst new file mode 100644 index 0000000..be241c2 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_PROCESS_MAX.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_PROCESS_MAX +------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_PROCESS_MAX` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_PROGUARD.rst b/Help/variable/CMAKE_ANDROID_PROGUARD.rst new file mode 100644 index 0000000..bb001d3 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_PROGUARD.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_PROGUARD +---------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_PROGUARD` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_PROGUARD_CONFIG_PATH.rst b/Help/variable/CMAKE_ANDROID_PROGUARD_CONFIG_PATH.rst new file mode 100644 index 0000000..6fd4067 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_PROGUARD_CONFIG_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_PROGUARD_CONFIG_PATH +---------------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_PROGUARD_CONFIG_PATH` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_RTTI.rst b/Help/variable/CMAKE_ANDROID_RTTI.rst new file mode 100644 index 0000000..0e98206 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_RTTI.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_RTTI +------------------ + +.. versionadded:: 3.20 + +When :ref:`Cross Compiling for Android with the NDK`, this variable may be set +to specify whether RTTI is enabled. diff --git a/Help/variable/CMAKE_ANDROID_SECURE_PROPS_PATH.rst b/Help/variable/CMAKE_ANDROID_SECURE_PROPS_PATH.rst new file mode 100644 index 0000000..9f5743e --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_SECURE_PROPS_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_SECURE_PROPS_PATH +------------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_SECURE_PROPS_PATH` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_SKIP_ANT_STEP.rst b/Help/variable/CMAKE_ANDROID_SKIP_ANT_STEP.rst new file mode 100644 index 0000000..588769b --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_SKIP_ANT_STEP.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_SKIP_ANT_STEP +--------------------------- + +.. versionadded:: 3.4 + +Default value for the :prop_tgt:`ANDROID_SKIP_ANT_STEP` target property. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN.rst b/Help/variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN.rst new file mode 100644 index 0000000..3ca89f5 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN.rst @@ -0,0 +1,8 @@ +CMAKE_ANDROID_STANDALONE_TOOLCHAIN +---------------------------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android with a Standalone Toolchain`, this +variable holds the absolute path to the root directory of the toolchain. +The specified directory must contain a ``sysroot`` subdirectory. diff --git a/Help/variable/CMAKE_ANDROID_STL_TYPE.rst b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst new file mode 100644 index 0000000..3778181 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst @@ -0,0 +1,39 @@ +CMAKE_ANDROID_STL_TYPE +---------------------- + +.. versionadded:: 3.4 + +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this variable may be set to specify the default value for the +:prop_tgt:`ANDROID_STL_TYPE` target property. See that target property +for additional information. + +When :ref:`Cross Compiling for Android with the NDK`, this variable may be +set to specify the STL variant to be used. The value may be one of: + +``none`` + No C++ Support +``system`` + Minimal C++ without STL +``gabi++_static`` + GAbi++ Static +``gabi++_shared`` + GAbi++ Shared +``gnustl_static`` + GNU libstdc++ Static +``gnustl_shared`` + GNU libstdc++ Shared +``c++_static`` + LLVM libc++ Static +``c++_shared`` + LLVM libc++ Shared +``stlport_static`` + STLport Static +``stlport_shared`` + STLport Shared + +The default value is ``gnustl_static`` on NDK versions that provide it +and otherwise ``c++_static``. Note that this default differs from +the native NDK build system because CMake may be used to build projects for +Android that are not natively implemented for it and use the C++ standard +library. diff --git a/Help/variable/CMAKE_APPBUNDLE_PATH.rst b/Help/variable/CMAKE_APPBUNDLE_PATH.rst new file mode 100644 index 0000000..1c7ca51 --- /dev/null +++ b/Help/variable/CMAKE_APPBUNDLE_PATH.rst @@ -0,0 +1,6 @@ +CMAKE_APPBUNDLE_PATH +-------------------- + +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path +for macOS application bundles used by the :command:`find_program`, and +:command:`find_package` commands. diff --git a/Help/variable/CMAKE_APPLE_SILICON_PROCESSOR.rst b/Help/variable/CMAKE_APPLE_SILICON_PROCESSOR.rst new file mode 100644 index 0000000..0d5ccd1 --- /dev/null +++ b/Help/variable/CMAKE_APPLE_SILICON_PROCESSOR.rst @@ -0,0 +1,14 @@ +CMAKE_APPLE_SILICON_PROCESSOR +----------------------------- + +.. versionadded:: 3.19.2 + +On Apple Silicon hosts running macOS, set this variable to tell +CMake what architecture to use for :variable:`CMAKE_HOST_SYSTEM_PROCESSOR`. +The value must be either ``arm64`` or ``x86_64``. + +The value of this variable should never be modified by project code. +It is meant to be set as a cache entry provided by the user, +e.g. via ``-DCMAKE_APPLE_SILICON_PROCESSOR=...``. + +See also the :envvar:`CMAKE_APPLE_SILICON_PROCESSOR` environment variable. diff --git a/Help/variable/CMAKE_AR.rst b/Help/variable/CMAKE_AR.rst new file mode 100644 index 0000000..5893677 --- /dev/null +++ b/Help/variable/CMAKE_AR.rst @@ -0,0 +1,7 @@ +CMAKE_AR +-------- + +Name of archiving tool for static libraries. + +This specifies the name of the program that creates archive or static +libraries. diff --git a/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..c889321 --- /dev/null +++ b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst @@ -0,0 +1,9 @@ +CMAKE_ARCHIVE_OUTPUT_DIRECTORY +------------------------------ + +Where to put all the :ref:`ARCHIVE <Archive Output Artifacts>` +target files when built. + +This variable is used to initialize the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..d8bd82c --- /dev/null +++ b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,11 @@ +CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------------- + +.. versionadded:: 3.3 + +Where to put all the :ref:`ARCHIVE <Archive Output Artifacts>` +target files when built for a specific configuration. + +This variable is used to initialize the +:prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` property on all the targets. +See that target property for additional information. diff --git a/Help/variable/CMAKE_ARGC.rst b/Help/variable/CMAKE_ARGC.rst new file mode 100644 index 0000000..30db2a2 --- /dev/null +++ b/Help/variable/CMAKE_ARGC.rst @@ -0,0 +1,8 @@ +CMAKE_ARGC +---------- + +Number of command line arguments passed to CMake in script mode. + +When run in :ref:`-P <Script Processing Mode>` script mode, CMake sets this +variable to the number of command line arguments. See also +:variable:`CMAKE_ARGV0`, ``1``, ``2`` ... diff --git a/Help/variable/CMAKE_ARGV0.rst b/Help/variable/CMAKE_ARGV0.rst new file mode 100644 index 0000000..c4d1c21 --- /dev/null +++ b/Help/variable/CMAKE_ARGV0.rst @@ -0,0 +1,9 @@ +CMAKE_ARGV0 +----------- + +Command line argument passed to CMake in script mode. + +When run in :ref:`-P <Script Processing Mode>` script mode, CMake sets this +variable to the first command line argument. It then also sets ``CMAKE_ARGV1``, +``CMAKE_ARGV2``, ... and so on, up to the number of command line arguments +given. See also :variable:`CMAKE_ARGC`. diff --git a/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst b/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst new file mode 100644 index 0000000..f490974 --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst @@ -0,0 +1,13 @@ +CMAKE_AUTOGEN_ORIGIN_DEPENDS +---------------------------- + +.. versionadded:: 3.14 + +Switch for forwarding origin target dependencies to the corresponding +``_autogen`` targets. + +This variable is used to initialize the :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` +property on all the targets. See that target property for additional +information. + +By default ``CMAKE_AUTOGEN_ORIGIN_DEPENDS`` is ``ON``. diff --git a/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst b/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst new file mode 100644 index 0000000..8e68579 --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_PARALLEL.rst @@ -0,0 +1,12 @@ +CMAKE_AUTOGEN_PARALLEL +---------------------- + +.. versionadded:: 3.11 + +Number of parallel ``moc`` or ``uic`` processes to start when using +:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +This variable is used to initialize the :prop_tgt:`AUTOGEN_PARALLEL` property +on all the targets. See that target property for additional information. + +By default ``CMAKE_AUTOGEN_PARALLEL`` is unset. diff --git a/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst b/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst new file mode 100644 index 0000000..246bd37 --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst @@ -0,0 +1,15 @@ +CMAKE_AUTOGEN_VERBOSE +--------------------- + +.. versionadded:: 3.13 + +Sets the verbosity of :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and +:prop_tgt:`AUTORCC`. A positive integer value or a true boolean value +lets the ``AUTO*`` generators output additional processing information. + +Setting ``CMAKE_AUTOGEN_VERBOSE`` has the same effect +as setting the ``VERBOSE`` environment variable during +generation (e.g. by calling ``make VERBOSE=1``). +The extra verbosity is limited to the ``AUTO*`` generators though. + +By default ``CMAKE_AUTOGEN_VERBOSE`` is unset. diff --git a/Help/variable/CMAKE_AUTOMOC.rst b/Help/variable/CMAKE_AUTOMOC.rst new file mode 100644 index 0000000..02e5eb5 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC.rst @@ -0,0 +1,7 @@ +CMAKE_AUTOMOC +------------- + +Whether to handle ``moc`` automatically for Qt targets. + +This variable is used to initialize the :prop_tgt:`AUTOMOC` property on all the +targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst b/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst new file mode 100644 index 0000000..f1b03a0 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst @@ -0,0 +1,10 @@ +CMAKE_AUTOMOC_COMPILER_PREDEFINES +--------------------------------- + +.. versionadded:: 3.10 + +This variable is used to initialize the :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` +property on all the targets. See that target property for additional +information. + +By default it is ON. diff --git a/Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst b/Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst new file mode 100644 index 0000000..2c1551a --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst @@ -0,0 +1,14 @@ +CMAKE_AUTOMOC_DEPEND_FILTERS +---------------------------- + +.. versionadded:: 3.9 + +Filter definitions used by :variable:`CMAKE_AUTOMOC` +to extract file names from source code as additional dependencies +for the ``moc`` file. + +This variable is used to initialize the :prop_tgt:`AUTOMOC_DEPEND_FILTERS` +property on all the targets. See that target property for additional +information. + +By default it is empty. diff --git a/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst new file mode 100644 index 0000000..1153cb2 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst @@ -0,0 +1,22 @@ +CMAKE_AUTOMOC_MACRO_NAMES +---------------------------- + +.. versionadded:: 3.10 + +:ref:`Semicolon-separated list <CMake Language Lists>` list of macro names used by +:variable:`CMAKE_AUTOMOC` to determine if a C++ file needs to be +processed by ``moc``. + +This variable is used to initialize the :prop_tgt:`AUTOMOC_MACRO_NAMES` +property on all the targets. See that target property for additional +information. + +The default value is ``Q_OBJECT;Q_GADGET;Q_NAMESPACE;Q_NAMESPACE_EXPORT``. + +Example +^^^^^^^ +Let CMake know that source files that contain ``CUSTOM_MACRO`` must be ``moc`` +processed as well:: + + set(CMAKE_AUTOMOC ON) + list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "CUSTOM_MACRO") diff --git a/Help/variable/CMAKE_AUTOMOC_MOC_OPTIONS.rst b/Help/variable/CMAKE_AUTOMOC_MOC_OPTIONS.rst new file mode 100644 index 0000000..09bf5cd --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_MOC_OPTIONS.rst @@ -0,0 +1,7 @@ +CMAKE_AUTOMOC_MOC_OPTIONS +------------------------- + +Additional options for ``moc`` when using :variable:`CMAKE_AUTOMOC`. + +This variable is used to initialize the :prop_tgt:`AUTOMOC_MOC_OPTIONS` property +on all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst b/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst new file mode 100644 index 0000000..42f48b4 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst @@ -0,0 +1,13 @@ +CMAKE_AUTOMOC_PATH_PREFIX +------------------------- + +.. versionadded:: 3.16 + +Whether to generate the ``-p`` path prefix option for ``moc`` on +:prop_tgt:`AUTOMOC` enabled Qt targets. + +This variable is used to initialize the :prop_tgt:`AUTOMOC_PATH_PREFIX` +property on all the targets. See that target property for additional +information. + +The default value is ``OFF``. diff --git a/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst b/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst new file mode 100644 index 0000000..0b0b114 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst @@ -0,0 +1,15 @@ +CMAKE_AUTOMOC_RELAXED_MODE +-------------------------- + +.. deprecated:: 3.15 + +Switch between strict and relaxed automoc mode. + +By default, :prop_tgt:`AUTOMOC` behaves exactly as described in the +documentation of the :prop_tgt:`AUTOMOC` target property. When set to +``TRUE``, it accepts more input and tries to find the correct input file for +``moc`` even if it differs from the documented behavior. In this mode it +e.g. also checks whether a header file is intended to be processed by moc +when a ``"foo.moc"`` file has been included. + +Relaxed mode has to be enabled for KDE4 compatibility. diff --git a/Help/variable/CMAKE_AUTORCC.rst b/Help/variable/CMAKE_AUTORCC.rst new file mode 100644 index 0000000..7426105 --- /dev/null +++ b/Help/variable/CMAKE_AUTORCC.rst @@ -0,0 +1,7 @@ +CMAKE_AUTORCC +------------- + +Whether to handle ``rcc`` automatically for Qt targets. + +This variable is used to initialize the :prop_tgt:`AUTORCC` property on all +the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_AUTORCC_OPTIONS.rst b/Help/variable/CMAKE_AUTORCC_OPTIONS.rst new file mode 100644 index 0000000..815d39d --- /dev/null +++ b/Help/variable/CMAKE_AUTORCC_OPTIONS.rst @@ -0,0 +1,16 @@ +CMAKE_AUTORCC_OPTIONS +--------------------- + +Additional options for ``rcc`` when using :variable:`CMAKE_AUTORCC`. + +This variable is used to initialize the :prop_tgt:`AUTORCC_OPTIONS` property on +all the targets. See that target property for additional information. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set(CMAKE_AUTORCC_OPTIONS "--compress;9") + # ... diff --git a/Help/variable/CMAKE_AUTOUIC.rst b/Help/variable/CMAKE_AUTOUIC.rst new file mode 100644 index 0000000..5abefaa --- /dev/null +++ b/Help/variable/CMAKE_AUTOUIC.rst @@ -0,0 +1,7 @@ +CMAKE_AUTOUIC +------------- + +Whether to handle ``uic`` automatically for Qt targets. + +This variable is used to initialize the :prop_tgt:`AUTOUIC` property on all +the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst b/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst new file mode 100644 index 0000000..28fa92f --- /dev/null +++ b/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst @@ -0,0 +1,16 @@ +CMAKE_AUTOUIC_OPTIONS +--------------------- + +Additional options for ``uic`` when using :variable:`CMAKE_AUTOUIC`. + +This variable is used to initialize the :prop_tgt:`AUTOUIC_OPTIONS` property on +all the targets. See that target property for additional information. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(CMAKE_AUTOUIC_OPTIONS "--no-protection") + # ... diff --git a/Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst b/Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst new file mode 100644 index 0000000..0262368 --- /dev/null +++ b/Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst @@ -0,0 +1,13 @@ +CMAKE_AUTOUIC_SEARCH_PATHS +-------------------------- + +.. versionadded:: 3.9 + +Search path list used by :variable:`CMAKE_AUTOUIC` to find included +``.ui`` files. + +This variable is used to initialize the :prop_tgt:`AUTOUIC_SEARCH_PATHS` +property on all the targets. See that target property for additional +information. + +By default it is empty. diff --git a/Help/variable/CMAKE_BACKWARDS_COMPATIBILITY.rst b/Help/variable/CMAKE_BACKWARDS_COMPATIBILITY.rst new file mode 100644 index 0000000..05c366a --- /dev/null +++ b/Help/variable/CMAKE_BACKWARDS_COMPATIBILITY.rst @@ -0,0 +1,4 @@ +CMAKE_BACKWARDS_COMPATIBILITY +----------------------------- + +Deprecated. See CMake Policy :policy:`CMP0001` documentation. diff --git a/Help/variable/CMAKE_BINARY_DIR.rst b/Help/variable/CMAKE_BINARY_DIR.rst new file mode 100644 index 0000000..96c6319 --- /dev/null +++ b/Help/variable/CMAKE_BINARY_DIR.rst @@ -0,0 +1,13 @@ +CMAKE_BINARY_DIR +---------------- + +The path to the top level of the build tree. + +This is the full path to the top level of the current CMake build +tree. For an in-source build, this would be the same as +:variable:`CMAKE_SOURCE_DIR`. + +When run in :option:`cmake -P` script mode, CMake sets the variables +``CMAKE_BINARY_DIR``, :variable:`CMAKE_SOURCE_DIR`, +:variable:`CMAKE_CURRENT_BINARY_DIR` and +:variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Help/variable/CMAKE_BUILD_RPATH.rst b/Help/variable/CMAKE_BUILD_RPATH.rst new file mode 100644 index 0000000..7a8ace7 --- /dev/null +++ b/Help/variable/CMAKE_BUILD_RPATH.rst @@ -0,0 +1,12 @@ +CMAKE_BUILD_RPATH +----------------- + +.. versionadded:: 3.8 + +:ref:`Semicolon-separated list <CMake Language Lists>` specifying runtime path (``RPATH``) +entries to add to binaries linked in the build tree (for platforms that +support it). The entries will *not* be used for binaries in the install +tree. See also the :variable:`CMAKE_INSTALL_RPATH` variable. + +This is used to initialize the :prop_tgt:`BUILD_RPATH` target property +for all targets. diff --git a/Help/variable/CMAKE_BUILD_RPATH_USE_ORIGIN.rst b/Help/variable/CMAKE_BUILD_RPATH_USE_ORIGIN.rst new file mode 100644 index 0000000..ecd9278 --- /dev/null +++ b/Help/variable/CMAKE_BUILD_RPATH_USE_ORIGIN.rst @@ -0,0 +1,9 @@ +CMAKE_BUILD_RPATH_USE_ORIGIN +---------------------------- + +.. versionadded:: 3.14 + +Whether to use relative paths for the build ``RPATH``. + +This is used to initialize the :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target +property for all targets, see that property for more details. diff --git a/Help/variable/CMAKE_BUILD_TOOL.rst b/Help/variable/CMAKE_BUILD_TOOL.rst new file mode 100644 index 0000000..6133491 --- /dev/null +++ b/Help/variable/CMAKE_BUILD_TOOL.rst @@ -0,0 +1,6 @@ +CMAKE_BUILD_TOOL +---------------- + +This variable exists only for backwards compatibility. +It contains the same value as :variable:`CMAKE_MAKE_PROGRAM`. +Use that variable instead. diff --git a/Help/variable/CMAKE_BUILD_TYPE.rst b/Help/variable/CMAKE_BUILD_TYPE.rst new file mode 100644 index 0000000..bb95436 --- /dev/null +++ b/Help/variable/CMAKE_BUILD_TYPE.rst @@ -0,0 +1,21 @@ +CMAKE_BUILD_TYPE +---------------- + +Specifies the build type on single-configuration generators (e.g. +:ref:`Makefile Generators` or :generator:`Ninja`). Typical values include +``Debug``, ``Release``, ``RelWithDebInfo`` and ``MinSizeRel``, but custom +build types can also be defined. + +This variable is initialized by the first :command:`project` or +:command:`enable_language` command called in a project when a new build +tree is first created. If the :envvar:`CMAKE_BUILD_TYPE` environment +variable is set, its value is used. Otherwise, a toolchain-specific +default is chosen when a language is enabled. The default value is often +an empty string, but this is usually not desirable and one of the other +standard build types is usually more appropriate. + +Depending on the situation, the value of this variable may be treated +case-sensitively or case-insensitively. See :ref:`Build Configurations` +for discussion of this and other related topics. + +For multi-config generators, see :variable:`CMAKE_CONFIGURATION_TYPES`. diff --git a/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst b/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst new file mode 100644 index 0000000..5ba775c --- /dev/null +++ b/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst @@ -0,0 +1,9 @@ +CMAKE_BUILD_WITH_INSTALL_NAME_DIR +--------------------------------- + +.. versionadded:: 3.9 + +Whether to use :prop_tgt:`INSTALL_NAME_DIR` on targets in the build tree. + +This variable is used to initialize the :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` +property on all targets. diff --git a/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst b/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst new file mode 100644 index 0000000..839771a --- /dev/null +++ b/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst @@ -0,0 +1,14 @@ +CMAKE_BUILD_WITH_INSTALL_RPATH +------------------------------ + +Use the install path for the ``RPATH``. + +Normally CMake uses the build tree for the ``RPATH`` when building +executables etc on systems that use ``RPATH``. When the software is +installed the executables etc are relinked by CMake to have the +install ``RPATH``. If this variable is set to true then the software is +always built with the install path for the ``RPATH`` and does not need to +be relinked when installed. + +This is used to initialize the :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property +for all targets. diff --git a/Help/variable/CMAKE_CACHEFILE_DIR.rst b/Help/variable/CMAKE_CACHEFILE_DIR.rst new file mode 100644 index 0000000..3fee09f --- /dev/null +++ b/Help/variable/CMAKE_CACHEFILE_DIR.rst @@ -0,0 +1,6 @@ +CMAKE_CACHEFILE_DIR +------------------- + +This variable is used internally by CMake, and may not be set during +the first configuration of a build tree. When it is set, it has the +same value as :variable:`CMAKE_BINARY_DIR`. Use that variable instead. diff --git a/Help/variable/CMAKE_CACHE_MAJOR_VERSION.rst b/Help/variable/CMAKE_CACHE_MAJOR_VERSION.rst new file mode 100644 index 0000000..1e53ed6 --- /dev/null +++ b/Help/variable/CMAKE_CACHE_MAJOR_VERSION.rst @@ -0,0 +1,8 @@ +CMAKE_CACHE_MAJOR_VERSION +------------------------- + +Major version of CMake used to create the ``CMakeCache.txt`` file + +This stores the major version of CMake used to write a CMake cache +file. It is only different when a different version of CMake is run +on a previously created cache file. diff --git a/Help/variable/CMAKE_CACHE_MINOR_VERSION.rst b/Help/variable/CMAKE_CACHE_MINOR_VERSION.rst new file mode 100644 index 0000000..5d174a3 --- /dev/null +++ b/Help/variable/CMAKE_CACHE_MINOR_VERSION.rst @@ -0,0 +1,8 @@ +CMAKE_CACHE_MINOR_VERSION +------------------------- + +Minor version of CMake used to create the ``CMakeCache.txt`` file + +This stores the minor version of CMake used to write a CMake cache +file. It is only different when a different version of CMake is run +on a previously created cache file. diff --git a/Help/variable/CMAKE_CACHE_PATCH_VERSION.rst b/Help/variable/CMAKE_CACHE_PATCH_VERSION.rst new file mode 100644 index 0000000..22d267c --- /dev/null +++ b/Help/variable/CMAKE_CACHE_PATCH_VERSION.rst @@ -0,0 +1,8 @@ +CMAKE_CACHE_PATCH_VERSION +------------------------- + +Patch version of CMake used to create the ``CMakeCache.txt`` file + +This stores the patch version of CMake used to write a CMake cache +file. It is only different when a different version of CMake is run +on a previously created cache file. diff --git a/Help/variable/CMAKE_CFG_INTDIR.rst b/Help/variable/CMAKE_CFG_INTDIR.rst new file mode 100644 index 0000000..3a57659 --- /dev/null +++ b/Help/variable/CMAKE_CFG_INTDIR.rst @@ -0,0 +1,53 @@ +CMAKE_CFG_INTDIR +---------------- + +.. deprecated:: 3.21 + + This variable has poor support on :generator:`Ninja Multi-Config`, and + predates the existence of the :genex:`$<CONFIG>` generator expression. Use + ``$<CONFIG>`` instead. + +Build-time reference to per-configuration output subdirectory. + +For native build systems supporting multiple configurations in the +build tree (such as :ref:`Visual Studio Generators` and :generator:`Xcode`), +the value is a reference to a build-time variable specifying the name +of the per-configuration output subdirectory. On :ref:`Makefile Generators` +this evaluates to `.` because there is only one configuration in a build tree. +Example values: + +:: + + $(ConfigurationName) = Visual Studio 9 + $(Configuration) = Visual Studio 11 and above + $(CONFIGURATION) = Xcode + . = Make-based tools + . = Ninja + ${CONFIGURATION} = Ninja Multi-Config + +Since these values are evaluated by the native build system, this +variable is suitable only for use in command lines that will be +evaluated at build time. Example of intended usage: + +:: + + add_executable(mytool mytool.c) + add_custom_command( + OUTPUT out.txt + COMMAND ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool + ${CMAKE_CURRENT_SOURCE_DIR}/in.txt out.txt + DEPENDS mytool in.txt + ) + add_custom_target(drive ALL DEPENDS out.txt) + +Note that ``CMAKE_CFG_INTDIR`` is no longer necessary for this purpose but +has been left for compatibility with existing projects. Instead +:command:`add_custom_command` recognizes executable target names in its +``COMMAND`` option, so +``${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool`` can be replaced +by just ``mytool``. + +This variable is read-only. Setting it is undefined behavior. In +multi-configuration build systems the value of this variable is passed +as the value of preprocessor symbol ``CMAKE_INTDIR`` to the compilation +of all source files. diff --git a/Help/variable/CMAKE_CLANG_VFS_OVERLAY.rst b/Help/variable/CMAKE_CLANG_VFS_OVERLAY.rst new file mode 100644 index 0000000..56ac328 --- /dev/null +++ b/Help/variable/CMAKE_CLANG_VFS_OVERLAY.rst @@ -0,0 +1,9 @@ +CMAKE_CLANG_VFS_OVERLAY +----------------------- + +.. versionadded:: 3.19 + +When cross compiling for windows with clang-cl, this variable can be an +absolute path pointing to a clang virtual file system yaml file, which +will enable clang-cl to resolve windows header names on a case sensitive +file system. diff --git a/Help/variable/CMAKE_CL_64.rst b/Help/variable/CMAKE_CL_64.rst new file mode 100644 index 0000000..4e80d1f --- /dev/null +++ b/Help/variable/CMAKE_CL_64.rst @@ -0,0 +1,7 @@ +CMAKE_CL_64 +----------- + +Discouraged. Use :variable:`CMAKE_SIZEOF_VOID_P` instead. + +Set to a true value when using a Microsoft Visual Studio ``cl`` compiler that +*targets* a 64-bit architecture. diff --git a/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst b/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst new file mode 100644 index 0000000..0b2b0a0 --- /dev/null +++ b/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst @@ -0,0 +1,15 @@ +CMAKE_CODEBLOCKS_COMPILER_ID +---------------------------- + +.. versionadded:: 3.11 + +Change the compiler id in the generated CodeBlocks project files. + +CodeBlocks uses its own compiler id string which differs from +:variable:`CMAKE_<LANG>_COMPILER_ID`. If this variable is left empty, +CMake tries to recognize the CodeBlocks compiler id automatically. +Otherwise the specified string is used in the CodeBlocks project file. +See the CodeBlocks documentation for valid compiler id strings. + +Other IDEs like QtCreator that also use the CodeBlocks generator may ignore +this setting. diff --git a/Help/variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES.rst b/Help/variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES.rst new file mode 100644 index 0000000..dbb8606 --- /dev/null +++ b/Help/variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES.rst @@ -0,0 +1,9 @@ +CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES +--------------------------------------- + +.. versionadded:: 3.10 + +Change the way the CodeBlocks generator creates project files. + +If this variable evaluates to ``ON`` the generator excludes from +the project file any files that are located outside the project root. diff --git a/Help/variable/CMAKE_CODELITE_USE_TARGETS.rst b/Help/variable/CMAKE_CODELITE_USE_TARGETS.rst new file mode 100644 index 0000000..21af5f7 --- /dev/null +++ b/Help/variable/CMAKE_CODELITE_USE_TARGETS.rst @@ -0,0 +1,10 @@ +CMAKE_CODELITE_USE_TARGETS +-------------------------- + +.. versionadded:: 3.7 + +Change the way the CodeLite generator creates projectfiles. + +If this variable evaluates to ``ON`` at the end of the top-level +``CMakeLists.txt`` file, the generator creates projectfiles based on targets +rather than projects. diff --git a/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst b/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst new file mode 100644 index 0000000..a72c9e1 --- /dev/null +++ b/Help/variable/CMAKE_COLOR_DIAGNOSTICS.rst @@ -0,0 +1,37 @@ +CMAKE_COLOR_DIAGNOSTICS +----------------------- + +.. versionadded:: 3.24 + +Enable color diagnostics throughout. + +This variable uses three states: ``ON``, ``OFF`` and not defined. + +When not defined: + +* :ref:`Makefile Generators` initialize the :variable:`CMAKE_COLOR_MAKEFILE` + variable to ``ON``. It controls color buildsystem messages. + +* GNU/Clang compilers are not invoked with any color diagnostics flag. + +When ``ON``: + +* :ref:`Makefile Generators` produce color buildsystem messages by default. + :variable:`CMAKE_COLOR_MAKEFILE` is not initialized, but may be + explicitly set to ``OFF`` to disable color buildsystem messages. + +* GNU/Clang compilers are invoked with a flag enabling color diagnostics + (``-fcolor-diagnostics``). + +When ``OFF``: + +* :ref:`Makefile Generators` do not produce color buildsystem messages by + default. :variable:`CMAKE_COLOR_MAKEFILE` is not initialized, but may be + explicitly set to ``ON`` to enable color buildsystem messages. + +* GNU/Clang compilers are invoked with a flag disabling color diagnostics + (``-fno-color-diagnostics``). + +If the :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment variable is set, its +value is used. Otherwise, ``CMAKE_COLOR_DIAGNOSTICS`` is not defined by +default. diff --git a/Help/variable/CMAKE_COLOR_MAKEFILE.rst b/Help/variable/CMAKE_COLOR_MAKEFILE.rst new file mode 100644 index 0000000..bb86ecc --- /dev/null +++ b/Help/variable/CMAKE_COLOR_MAKEFILE.rst @@ -0,0 +1,7 @@ +CMAKE_COLOR_MAKEFILE +-------------------- + +Enables color output when using the :ref:`Makefile Generators`. + +When enabled, the generated Makefiles will produce colored output. +Default is ``ON``. diff --git a/Help/variable/CMAKE_COMMAND.rst b/Help/variable/CMAKE_COMMAND.rst new file mode 100644 index 0000000..e65ff8c --- /dev/null +++ b/Help/variable/CMAKE_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_COMMAND +------------- + +The full path to the :manual:`cmake(1)` executable. + +This is the full path to the CMake executable :manual:`cmake(1)` which is +useful from custom commands that want to use the :option:`cmake -E` option for +portable system commands. (e.g. ``/usr/local/bin/cmake``) diff --git a/Help/variable/CMAKE_COMPILER_2005.rst b/Help/variable/CMAKE_COMPILER_2005.rst new file mode 100644 index 0000000..134559b --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_2005.rst @@ -0,0 +1,6 @@ +CMAKE_COMPILER_2005 +------------------- + +Using the Visual Studio 2005 compiler from Microsoft + +Set to true when using the Visual Studio 2005 compiler from Microsoft. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst b/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst new file mode 100644 index 0000000..4b799c0 --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst @@ -0,0 +1,7 @@ +CMAKE_COMPILER_IS_GNUCC +----------------------- + +True if the ``C`` compiler is GNU. + +This variable is deprecated. Use +:variable:`CMAKE_C_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst b/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst new file mode 100644 index 0000000..29069d2 --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst @@ -0,0 +1,7 @@ +CMAKE_COMPILER_IS_GNUCXX +------------------------ + +True if the C++ (``CXX``) compiler is GNU. + +This variable is deprecated. Use +:variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst b/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst new file mode 100644 index 0000000..05303dc --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst @@ -0,0 +1,7 @@ +CMAKE_COMPILER_IS_GNUG77 +------------------------ + +True if the ``Fortran`` compiler is GNU. + +This variable is deprecated. Use +:variable:`CMAKE_Fortran_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. diff --git a/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..11f52c7 --- /dev/null +++ b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.rst @@ -0,0 +1,10 @@ +CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY +---------------------------------- + +.. versionadded:: 3.1 + +Output directory for MS debug symbol ``.pdb`` files +generated by the compiler while building source files. + +This variable is used to initialize the +:prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` property on all the targets. diff --git a/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..99d0bdc --- /dev/null +++ b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,13 @@ +CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> +------------------------------------------- + +.. versionadded:: 3.1 + +Per-configuration output directory for MS debug symbol ``.pdb`` files +generated by the compiler while building source files. + +This is a per-configuration version of +:variable:`CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY`. +This variable is used to initialize the +:prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>` +property on all the targets. diff --git a/Help/variable/CMAKE_COMPILE_WARNING_AS_ERROR.rst b/Help/variable/CMAKE_COMPILE_WARNING_AS_ERROR.rst new file mode 100644 index 0000000..56dc6a6 --- /dev/null +++ b/Help/variable/CMAKE_COMPILE_WARNING_AS_ERROR.rst @@ -0,0 +1,9 @@ +CMAKE_COMPILE_WARNING_AS_ERROR +------------------------------ + +.. versionadded:: 3.24 + +Specify whether to treat warnings on compile as errors. + +This variable is used to initialize the +:prop_tgt:`COMPILE_WARNING_AS_ERROR` property on all the targets. diff --git a/Help/variable/CMAKE_CONFIGURATION_TYPES.rst b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst new file mode 100644 index 0000000..887eb2f --- /dev/null +++ b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst @@ -0,0 +1,21 @@ +CMAKE_CONFIGURATION_TYPES +------------------------- + +Specifies the available build types (configurations) on multi-config +generators (e.g. :ref:`Visual Studio <Visual Studio Generators>`, +:generator:`Xcode`, or :generator:`Ninja Multi-Config`) as a +:ref:`semicolon-separated list <CMake Language Lists>`. Typical entries +include ``Debug``, ``Release``, ``RelWithDebInfo`` and ``MinSizeRel``, +but custom build types can also be defined. + +This variable is initialized by the first :command:`project` or +:command:`enable_language` command called in a project when a new build +tree is first created. If the :envvar:`CMAKE_CONFIGURATION_TYPES` +environment variable is set, its value is used. Otherwise, the default +value is generator-specific. + +Depending on the situation, the values in this variable may be treated +case-sensitively or case-insensitively. See :ref:`Build Configurations` +for discussion of this and other related topics. + +For single-config generators, see :variable:`CMAKE_BUILD_TYPE`. diff --git a/Help/variable/CMAKE_CONFIG_POSTFIX.rst b/Help/variable/CMAKE_CONFIG_POSTFIX.rst new file mode 100644 index 0000000..e686a43 --- /dev/null +++ b/Help/variable/CMAKE_CONFIG_POSTFIX.rst @@ -0,0 +1,7 @@ +CMAKE_<CONFIG>_POSTFIX +---------------------- + +Default filename postfix for libraries under configuration ``<CONFIG>``. + +When a non-executable target is created its :prop_tgt:`<CONFIG>_POSTFIX` +target property is initialized with the value of this variable if it is set. diff --git a/Help/variable/CMAKE_CPACK_COMMAND.rst b/Help/variable/CMAKE_CPACK_COMMAND.rst new file mode 100644 index 0000000..f851a18 --- /dev/null +++ b/Help/variable/CMAKE_CPACK_COMMAND.rst @@ -0,0 +1,10 @@ +CMAKE_CPACK_COMMAND +------------------- + +.. versionadded:: 3.13 + +Full path to :manual:`cpack(1)` command installed with CMake. + +This is the full path to the CPack executable :manual:`cpack(1)` +that can be used for custom commands or tests to invoke +CPack commands. diff --git a/Help/variable/CMAKE_CROSSCOMPILING.rst b/Help/variable/CMAKE_CROSSCOMPILING.rst new file mode 100644 index 0000000..7e6ec33 --- /dev/null +++ b/Help/variable/CMAKE_CROSSCOMPILING.rst @@ -0,0 +1,27 @@ +CMAKE_CROSSCOMPILING +-------------------- + +Intended to indicate whether CMake is cross compiling, but note limitations +discussed below. + +This variable will be set to true by CMake if the :variable:`CMAKE_SYSTEM_NAME` +variable has been set manually (i.e. in a toolchain file or as a cache entry +from the :manual:`cmake <cmake(1)>` command line). In most cases, manually +setting :variable:`CMAKE_SYSTEM_NAME` will only be done when cross compiling, +since it will otherwise be given the same value as +:variable:`CMAKE_HOST_SYSTEM_NAME` if not manually set, which is correct for +the non-cross-compiling case. In the event that :variable:`CMAKE_SYSTEM_NAME` +is manually set to the same value as :variable:`CMAKE_HOST_SYSTEM_NAME`, then +``CMAKE_CROSSCOMPILING`` will still be set to true. + +Another case to be aware of is that builds targeting Apple platforms other than +macOS are handled differently to other cross compiling scenarios. Rather than +relying on :variable:`CMAKE_SYSTEM_NAME` to select the target platform, Apple +device builds use :variable:`CMAKE_OSX_SYSROOT` to select the appropriate SDK, +which indirectly determines the target platform. Furthermore, when using the +:generator:`Xcode` generator, developers can switch between device and +simulator builds at build time rather than having a single +choice at configure time, so the concept +of whether the build is cross compiling or not is more complex. Therefore, the +use of ``CMAKE_CROSSCOMPILING`` is not recommended for projects targeting Apple +devices. diff --git a/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst new file mode 100644 index 0000000..e21b35d --- /dev/null +++ b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst @@ -0,0 +1,19 @@ +CMAKE_CROSSCOMPILING_EMULATOR +----------------------------- + +.. versionadded:: 3.3 + +This variable is only used when :variable:`CMAKE_CROSSCOMPILING` is on. It +should point to a command on the host system that can run executable built +for the target system. + +.. versionadded:: 3.15 + If this variable contains a :ref:`semicolon-separated list <CMake Language + Lists>`, then the first value is the command and remaining values are its + arguments. + +The command will be used to run :command:`try_run` generated executables, +which avoids manual population of the ``TryRunResults.cmake`` file. + +It is also used as the default value for the +:prop_tgt:`CROSSCOMPILING_EMULATOR` target property of executables. diff --git a/Help/variable/CMAKE_CROSS_CONFIGS.rst b/Help/variable/CMAKE_CROSS_CONFIGS.rst new file mode 100644 index 0000000..be921d6 --- /dev/null +++ b/Help/variable/CMAKE_CROSS_CONFIGS.rst @@ -0,0 +1,17 @@ +CMAKE_CROSS_CONFIGS +------------------- + +.. versionadded:: 3.17 + +Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of +configurations available from all ``build-<Config>.ninja`` files in the +:generator:`Ninja Multi-Config` generator. This variable activates +cross-config mode. Targets from each config specified in this variable can be +built from any ``build-<Config>.ninja`` file. Custom commands will use the +configuration native to ``build-<Config>.ninja``. If it is set to ``all``, all +configurations from :variable:`CMAKE_CONFIGURATION_TYPES` are cross-configs. If +it is not specified, or empty, each ``build-<Config>.ninja`` file will only +contain build rules for its own configuration. + +The value of this variable must be a subset of +:variable:`CMAKE_CONFIGURATION_TYPES`. diff --git a/Help/variable/CMAKE_CTEST_ARGUMENTS.rst b/Help/variable/CMAKE_CTEST_ARGUMENTS.rst new file mode 100644 index 0000000..4dfc8fe --- /dev/null +++ b/Help/variable/CMAKE_CTEST_ARGUMENTS.rst @@ -0,0 +1,8 @@ +CMAKE_CTEST_ARGUMENTS +--------------------- + +.. versionadded:: 3.17 + +Set this to a :ref:`semicolon-separated list <CMake Language Lists>` of +command-line arguments to pass to :manual:`ctest(1)` when running tests +through the ``test`` (or ``RUN_TESTS``) target of the generated build system. diff --git a/Help/variable/CMAKE_CTEST_COMMAND.rst b/Help/variable/CMAKE_CTEST_COMMAND.rst new file mode 100644 index 0000000..a3b751f --- /dev/null +++ b/Help/variable/CMAKE_CTEST_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_CTEST_COMMAND +------------------- + +Full path to :manual:`ctest(1)` command installed with CMake. + +This is the full path to the CTest executable :manual:`ctest(1)` +that can be used for custom commands or tests to invoke +CTest commands. diff --git a/Help/variable/CMAKE_CUDA_ARCHITECTURES.rst b/Help/variable/CMAKE_CUDA_ARCHITECTURES.rst new file mode 100644 index 0000000..d885516 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_ARCHITECTURES.rst @@ -0,0 +1,35 @@ +CMAKE_CUDA_ARCHITECTURES +------------------------ + +.. versionadded:: 3.18 + +Default value for :prop_tgt:`CUDA_ARCHITECTURES` property of targets. + +Initialized by the :envvar:`CUDAARCHS` environment variable if set. +Otherwise as follows depending on :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>`: + +- For ``Clang``: the oldest architecture that works. + +- For ``NVIDIA``: the default architecture chosen by the compiler. + See policy :policy:`CMP0104`. + +Users are encouraged to override this, as the default varies across compilers +and compiler versions. + +This variable is used to initialize the :prop_tgt:`CUDA_ARCHITECTURES` property +on all targets. See the target property for additional information. + +Examples +^^^^^^^^ + +.. code-block:: cmake + + cmake_minimum_required(VERSION) + + if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES) + set(CMAKE_CUDA_ARCHITECTURES 75) + endif() + + project(example LANGUAGES CUDA) + +``CMAKE_CUDA_ARCHITECTURES`` will default to ``75`` unless overridden by the user. diff --git a/Help/variable/CMAKE_CUDA_COMPILE_FEATURES.rst b/Help/variable/CMAKE_CUDA_COMPILE_FEATURES.rst new file mode 100644 index 0000000..c1c270c --- /dev/null +++ b/Help/variable/CMAKE_CUDA_COMPILE_FEATURES.rst @@ -0,0 +1,13 @@ +CMAKE_CUDA_COMPILE_FEATURES +--------------------------- + +.. versionadded:: 3.17 + +List of features known to the CUDA compiler + +These features are known to be available for use with the CUDA compiler. This +list is a subset of the features listed in the +:prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES` global property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CUDA_EXTENSIONS.rst b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst new file mode 100644 index 0000000..12749ce --- /dev/null +++ b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst @@ -0,0 +1,10 @@ +CMAKE_CUDA_EXTENSIONS +--------------------- + +.. versionadded:: 3.8 + +Default value for :prop_tgt:`CUDA_EXTENSIONS` target property if set when a +target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst new file mode 100644 index 0000000..9817b1a --- /dev/null +++ b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst @@ -0,0 +1,29 @@ +CMAKE_CUDA_HOST_COMPILER +------------------------ + +.. versionadded:: 3.10 + +When :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is +``NVIDIA``, ``CMAKE_CUDA_HOST_COMPILER`` selects the compiler executable to use +when compiling host code for ``CUDA`` language files. +This maps to the ``nvcc -ccbin`` option. + +The ``CMAKE_CUDA_HOST_COMPILER`` variable may be set explicitly before CUDA is +first enabled by a :command:`project` or :command:`enable_language` command. +This can be done via ``-DCMAKE_CUDA_HOST_COMPILER=...`` on the command line +or in a :ref:`toolchain file <Cross Compiling Toolchain>`. Or, one may set +the :envvar:`CUDAHOSTCXX` environment variable to provide a default value. + +Once the CUDA language is enabled, the ``CMAKE_CUDA_HOST_COMPILER`` variable +is read-only and changes to it are undefined behavior. + +.. note:: + + Since ``CMAKE_CUDA_HOST_COMPILER`` is meaningful only when the + :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``, + it does not make sense to set ``CMAKE_CUDA_HOST_COMPILER`` without also + setting ``CMAKE_CUDA_COMPILER`` to NVCC. + +.. note:: + + Ignored when using :ref:`Visual Studio Generators`. diff --git a/Help/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS.rst b/Help/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS.rst new file mode 100644 index 0000000..bd56911 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS.rst @@ -0,0 +1,10 @@ +CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS +--------------------------------- + +.. versionadded:: 3.16 + +Default value for :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target +property when defined. By default this variable is not defined. + +This variable is used to initialize the property on each target as +it is created. diff --git a/Help/variable/CMAKE_CUDA_RUNTIME_LIBRARY.rst b/Help/variable/CMAKE_CUDA_RUNTIME_LIBRARY.rst new file mode 100644 index 0000000..69b9d93 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_RUNTIME_LIBRARY.rst @@ -0,0 +1,27 @@ +CMAKE_CUDA_RUNTIME_LIBRARY +-------------------------- + +.. versionadded:: 3.17 + +Select the CUDA runtime library for use when compiling and linking CUDA. +This variable is used to initialize the :prop_tgt:`CUDA_RUNTIME_LIBRARY` +property on all targets as they are created. + +The allowed case insensitive values are: + +.. include:: ../prop_tgt/CUDA_RUNTIME_LIBRARY-VALUES.txt + +Contents of ``CMAKE_CUDA_RUNTIME_LIBRARY`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +If this variable is not set then the :prop_tgt:`CUDA_RUNTIME_LIBRARY` target +property will not be set automatically. If that property is not set then +CMake uses an appropriate default value based on the compiler to select the +CUDA runtime library. + +.. note:: + + This property has effect only when the ``CUDA`` language is enabled. To + control the CUDA runtime linking when only using the CUDA SDK with the + ``C`` or ``C++`` language we recommend using the :module:`FindCUDAToolkit` + module. diff --git a/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst b/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst new file mode 100644 index 0000000..3dbaef9 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst @@ -0,0 +1,8 @@ +CMAKE_CUDA_SEPARABLE_COMPILATION +-------------------------------- + +.. versionadded:: 3.11 + +Default value for :prop_tgt:`CUDA_SEPARABLE_COMPILATION` target property. +This variable is used to initialize the property on each target as it is +created. diff --git a/Help/variable/CMAKE_CUDA_STANDARD.rst b/Help/variable/CMAKE_CUDA_STANDARD.rst new file mode 100644 index 0000000..ee9395a --- /dev/null +++ b/Help/variable/CMAKE_CUDA_STANDARD.rst @@ -0,0 +1,10 @@ +CMAKE_CUDA_STANDARD +------------------- + +.. versionadded:: 3.8 + +Default value for :prop_tgt:`CUDA_STANDARD` target property if set when a +target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..0c85a04d --- /dev/null +++ b/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst @@ -0,0 +1,10 @@ +CMAKE_CUDA_STANDARD_REQUIRED +---------------------------- + +.. versionadded:: 3.8 + +Default value for :prop_tgt:`CUDA_STANDARD_REQUIRED` target property if set +when a target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..e586dab --- /dev/null +++ b/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,9 @@ +CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES +-------------------------------------- + +.. versionadded:: 3.8 + +When the ``CUDA`` language has been enabled, this provides a +:ref:`semicolon-separated list <CMake Language Lists>` of include directories provided +by the CUDA Toolkit. The value may be useful for C++ source files +to include CUDA headers. diff --git a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst new file mode 100644 index 0000000..1d7a111 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst @@ -0,0 +1,15 @@ +CMAKE_CURRENT_BINARY_DIR +------------------------ + +The path to the binary directory currently being processed. + +This is the full path to the build directory that is currently being +processed by cmake. Each directory added by :command:`add_subdirectory` will +create a binary directory in the build tree, and as it is being +processed this variable will be set. For in-source builds this is the +current source directory being processed. + +When run in :option:`cmake -P` script mode, CMake sets the variables +:variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, +``CMAKE_CURRENT_BINARY_DIR`` and +:variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION.rst b/Help/variable/CMAKE_CURRENT_FUNCTION.rst new file mode 100644 index 0000000..5d1a4e9 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION.rst @@ -0,0 +1,12 @@ +CMAKE_CURRENT_FUNCTION +---------------------- + +.. versionadded:: 3.17 + +When executing code inside a :command:`function`, this variable +contains the name of the current function. It can be useful for +diagnostic or debug messages. + +See also :variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE` and +:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst new file mode 100644 index 0000000..f8f553d --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_DIR.rst @@ -0,0 +1,43 @@ +CMAKE_CURRENT_FUNCTION_LIST_DIR +------------------------------- + +.. versionadded:: 3.17 + +When executing code inside a :command:`function`, this variable +contains the full directory of the listfile that defined the current function. + +It is quite common practice in CMake for modules to use some additional files, +such as templates to be copied in after substituting CMake variables. +In such cases, a function needs to know where to locate those files in a way +that doesn't depend on where the function is called. Without +``CMAKE_CURRENT_FUNCTION_LIST_DIR``, the code to do that would typically use +the following pattern: + +.. code-block:: cmake + + set(_THIS_MODULE_BASE_DIR "${CMAKE_CURRENT_LIST_DIR}") + + function(foo) + configure_file( + "${_THIS_MODULE_BASE_DIR}/some.template.in" + some.output + ) + endfunction() + +Using ``CMAKE_CURRENT_FUNCTION_LIST_DIR`` inside the function instead +eliminates the need for the extra variable which would otherwise be visible +outside the function's scope. +The above example can be written in the more concise and more robust form: + +.. code-block:: cmake + + function(foo) + configure_file( + "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/some.template.in" + some.output + ) + endfunction() + +See also :variable:`CMAKE_CURRENT_FUNCTION`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE` and +:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst new file mode 100644 index 0000000..437dfec --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_FILE.rst @@ -0,0 +1,11 @@ +CMAKE_CURRENT_FUNCTION_LIST_FILE +-------------------------------- + +.. versionadded:: 3.17 + +When executing code inside a :command:`function`, this variable +contains the full path to the listfile that defined the current function. + +See also :variable:`CMAKE_CURRENT_FUNCTION`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR` and +:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`. diff --git a/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst new file mode 100644 index 0000000..2fc7012 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_FUNCTION_LIST_LINE.rst @@ -0,0 +1,12 @@ +CMAKE_CURRENT_FUNCTION_LIST_LINE +-------------------------------- + +.. versionadded:: 3.17 + +When executing code inside a :command:`function`, this variable +contains the line number in the listfile where the current function +was defined. + +See also :variable:`CMAKE_CURRENT_FUNCTION`, +:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR` and +:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`. diff --git a/Help/variable/CMAKE_CURRENT_LIST_DIR.rst b/Help/variable/CMAKE_CURRENT_LIST_DIR.rst new file mode 100644 index 0000000..ebc3ab9 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_LIST_DIR.rst @@ -0,0 +1,17 @@ +CMAKE_CURRENT_LIST_DIR +---------------------- + +Full directory of the listfile currently being processed. + +As CMake processes the listfiles in your project this variable will +always be set to the directory where the listfile which is currently +being processed (:variable:`CMAKE_CURRENT_LIST_FILE`) is located. The value +has dynamic scope. When CMake starts processing commands in a source file +it sets this variable to the directory where this file is located. +When CMake finishes processing commands from the file it restores the +previous value. Therefore the value of the variable inside a macro or +function is the directory of the file invoking the bottom-most entry +on the call stack, not the directory of the file containing the macro +or function definition. + +See also :variable:`CMAKE_CURRENT_LIST_FILE`. diff --git a/Help/variable/CMAKE_CURRENT_LIST_FILE.rst b/Help/variable/CMAKE_CURRENT_LIST_FILE.rst new file mode 100644 index 0000000..84b0eee --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_LIST_FILE.rst @@ -0,0 +1,15 @@ +CMAKE_CURRENT_LIST_FILE +----------------------- + +Full path to the listfile currently being processed. + +As CMake processes the listfiles in your project this variable will +always be set to the one currently being processed. The value has +dynamic scope. When CMake starts processing commands in a source file +it sets this variable to the location of the file. When CMake +finishes processing commands from the file it restores the previous +value. Therefore the value of the variable inside a macro or function +is the file invoking the bottom-most entry on the call stack, not the +file containing the macro or function definition. + +See also :variable:`CMAKE_PARENT_LIST_FILE`. diff --git a/Help/variable/CMAKE_CURRENT_LIST_LINE.rst b/Help/variable/CMAKE_CURRENT_LIST_LINE.rst new file mode 100644 index 0000000..7f839c2 --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_LIST_LINE.rst @@ -0,0 +1,11 @@ +CMAKE_CURRENT_LIST_LINE +----------------------- + +The line number of the current file being processed. + +This is the line number of the file currently being processed by +cmake. + +If CMake is currently processing deferred calls scheduled by +the :command:`cmake_language(DEFER)` command, this variable +evaluates to ``DEFERRED`` instead of a specific line number. diff --git a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst new file mode 100644 index 0000000..4205efb --- /dev/null +++ b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst @@ -0,0 +1,12 @@ +CMAKE_CURRENT_SOURCE_DIR +------------------------ + +The path to the source directory currently being processed. + +This is the full path to the source directory that is currently being +processed by cmake. + +When run in :option:`cmake -P` script mode, CMake sets the variables +:variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, +:variable:`CMAKE_CURRENT_BINARY_DIR` and +``CMAKE_CURRENT_SOURCE_DIR`` to the current working directory. diff --git a/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst b/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst new file mode 100644 index 0000000..8fcfbae --- /dev/null +++ b/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst @@ -0,0 +1,13 @@ +CMAKE_CXX_COMPILE_FEATURES +-------------------------- + +.. versionadded:: 3.1 + +List of features known to the C++ compiler + +These features are known to be available for use with the C++ compiler. This +list is a subset of the features listed in the +:prop_gbl:`CMAKE_CXX_KNOWN_FEATURES` global property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CXX_EXTENSIONS.rst b/Help/variable/CMAKE_CXX_EXTENSIONS.rst new file mode 100644 index 0000000..017f503 --- /dev/null +++ b/Help/variable/CMAKE_CXX_EXTENSIONS.rst @@ -0,0 +1,10 @@ +CMAKE_CXX_EXTENSIONS +-------------------- + +.. versionadded:: 3.1 + +Default value for :prop_tgt:`CXX_EXTENSIONS` target property if set when a +target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CXX_SCAN_FOR_MODULES.rst b/Help/variable/CMAKE_CXX_SCAN_FOR_MODULES.rst new file mode 100644 index 0000000..a40bf75 --- /dev/null +++ b/Help/variable/CMAKE_CXX_SCAN_FOR_MODULES.rst @@ -0,0 +1,15 @@ +CMAKE_CXX_SCAN_FOR_MODULES +-------------------------- + +.. versionadded:: 3.26 + +Whether to scan C++ source files for module dependencies. + +This variable is used to initialize the :prop_tgt:`CXX_SCAN_FOR_MODULES` +property on all the targets. See that target property for additional +information. + +.. note :: + + This setting is meaningful only when experimental support for C++ modules + has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` gate. diff --git a/Help/variable/CMAKE_CXX_STANDARD.rst b/Help/variable/CMAKE_CXX_STANDARD.rst new file mode 100644 index 0000000..33eb89e --- /dev/null +++ b/Help/variable/CMAKE_CXX_STANDARD.rst @@ -0,0 +1,10 @@ +CMAKE_CXX_STANDARD +------------------ + +.. versionadded:: 3.1 + +Default value for :prop_tgt:`CXX_STANDARD` target property if set when a target +is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..1c6c0cc --- /dev/null +++ b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst @@ -0,0 +1,10 @@ +CMAKE_CXX_STANDARD_REQUIRED +--------------------------- + +.. versionadded:: 3.1 + +Default value for :prop_tgt:`CXX_STANDARD_REQUIRED` target property if set when +a target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_COMPILE_FEATURES.rst b/Help/variable/CMAKE_C_COMPILE_FEATURES.rst new file mode 100644 index 0000000..2b306a3 --- /dev/null +++ b/Help/variable/CMAKE_C_COMPILE_FEATURES.rst @@ -0,0 +1,13 @@ +CMAKE_C_COMPILE_FEATURES +------------------------ + +.. versionadded:: 3.1 + +List of features known to the C compiler + +These features are known to be available for use with the C compiler. This +list is a subset of the features listed in the +:prop_gbl:`CMAKE_C_KNOWN_FEATURES` global property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_EXTENSIONS.rst b/Help/variable/CMAKE_C_EXTENSIONS.rst new file mode 100644 index 0000000..6680521 --- /dev/null +++ b/Help/variable/CMAKE_C_EXTENSIONS.rst @@ -0,0 +1,10 @@ +CMAKE_C_EXTENSIONS +------------------ + +.. versionadded:: 3.1 + +Default value for :prop_tgt:`C_EXTENSIONS` target property if set when a target +is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_STANDARD.rst b/Help/variable/CMAKE_C_STANDARD.rst new file mode 100644 index 0000000..ec1e513 --- /dev/null +++ b/Help/variable/CMAKE_C_STANDARD.rst @@ -0,0 +1,10 @@ +CMAKE_C_STANDARD +---------------- + +.. versionadded:: 3.1 + +Default value for :prop_tgt:`C_STANDARD` target property if set when a target +is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..2bd9d51 --- /dev/null +++ b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst @@ -0,0 +1,10 @@ +CMAKE_C_STANDARD_REQUIRED +------------------------- + +.. versionadded:: 3.1 + +Default value for :prop_tgt:`C_STANDARD_REQUIRED` target property if set when +a target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_DEBUG_POSTFIX.rst b/Help/variable/CMAKE_DEBUG_POSTFIX.rst new file mode 100644 index 0000000..08577a5 --- /dev/null +++ b/Help/variable/CMAKE_DEBUG_POSTFIX.rst @@ -0,0 +1,7 @@ +CMAKE_DEBUG_POSTFIX +------------------- + +See variable :variable:`CMAKE_<CONFIG>_POSTFIX`. + +This variable is a special case of the more-general +:variable:`CMAKE_<CONFIG>_POSTFIX` variable for the `DEBUG` configuration. diff --git a/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst new file mode 100644 index 0000000..a1fa1ff --- /dev/null +++ b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst @@ -0,0 +1,23 @@ +CMAKE_DEBUG_TARGET_PROPERTIES +----------------------------- + +Enables tracing output for target properties. + +This variable can be populated with a list of properties to generate +debug output for when evaluating target properties. Currently it can +only be used when evaluating: + +* :prop_tgt:`AUTOUIC_OPTIONS` +* :prop_tgt:`COMPILE_DEFINITIONS` +* :prop_tgt:`COMPILE_FEATURES` +* :prop_tgt:`COMPILE_OPTIONS` +* :prop_tgt:`INCLUDE_DIRECTORIES` +* :prop_tgt:`LINK_DIRECTORIES` +* :prop_tgt:`LINK_OPTIONS` +* :prop_tgt:`POSITION_INDEPENDENT_CODE` +* :prop_tgt:`SOURCES` + +target properties and any other property listed in +:prop_tgt:`COMPATIBLE_INTERFACE_STRING` and other +``COMPATIBLE_INTERFACE_`` properties. It outputs an origin for each entry +in the target property. Default is unset. diff --git a/Help/variable/CMAKE_DEFAULT_BUILD_TYPE.rst b/Help/variable/CMAKE_DEFAULT_BUILD_TYPE.rst new file mode 100644 index 0000000..cadbf3a --- /dev/null +++ b/Help/variable/CMAKE_DEFAULT_BUILD_TYPE.rst @@ -0,0 +1,14 @@ +CMAKE_DEFAULT_BUILD_TYPE +------------------------ + +.. versionadded:: 3.17 + +Specifies the configuration to use by default in a ``build.ninja`` file in the +:generator:`Ninja Multi-Config` generator. If this variable is specified, +``build.ninja`` uses build rules from ``build-<Config>.ninja`` by default. All +custom commands are executed with this configuration. If the variable is not +specified, the first item from :variable:`CMAKE_CONFIGURATION_TYPES` is used +instead. + +The value of this variable must be one of the items from +:variable:`CMAKE_CONFIGURATION_TYPES`. diff --git a/Help/variable/CMAKE_DEFAULT_CONFIGS.rst b/Help/variable/CMAKE_DEFAULT_CONFIGS.rst new file mode 100644 index 0000000..2f42b23 --- /dev/null +++ b/Help/variable/CMAKE_DEFAULT_CONFIGS.rst @@ -0,0 +1,21 @@ +CMAKE_DEFAULT_CONFIGS +--------------------- + +.. versionadded:: 3.17 + +Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of configurations +to build for a target in ``build.ninja`` if no ``:<Config>`` suffix is specified in +the :generator:`Ninja Multi-Config` generator. If it is set to ``all``, all +configurations from :variable:`CMAKE_CROSS_CONFIGS` are used. If it is not +specified, it defaults to :variable:`CMAKE_DEFAULT_BUILD_TYPE`. + +For example, if you set :variable:`CMAKE_DEFAULT_BUILD_TYPE` to ``Release``, +but set ``CMAKE_DEFAULT_CONFIGS`` to ``Debug`` or ``all``, all +``<target>`` aliases in ``build.ninja`` will resolve to ``<target>:Debug`` or +``<target>:all``, but custom commands will still use the ``Release`` +configuration. + +The value of this variable must be a subset of :variable:`CMAKE_CROSS_CONFIGS` +or be the same as :variable:`CMAKE_DEFAULT_BUILD_TYPE`. It must not be +specified if :variable:`CMAKE_DEFAULT_BUILD_TYPE` or +:variable:`CMAKE_CROSS_CONFIGS` is not used. diff --git a/Help/variable/CMAKE_DEPENDS_IN_PROJECT_ONLY.rst b/Help/variable/CMAKE_DEPENDS_IN_PROJECT_ONLY.rst new file mode 100644 index 0000000..bfe9402 --- /dev/null +++ b/Help/variable/CMAKE_DEPENDS_IN_PROJECT_ONLY.rst @@ -0,0 +1,12 @@ +CMAKE_DEPENDS_IN_PROJECT_ONLY +----------------------------- + +.. versionadded:: 3.6 + +When set to ``TRUE`` in a directory, the build system produced by the +:ref:`Makefile Generators` is set up to only consider dependencies on source +files that appear either in the source or in the binary directories. Changes +to source files outside of these directories will not cause rebuilds. + +This should be used carefully in cases where some source files are picked up +through external headers during the build. diff --git a/Help/variable/CMAKE_DEPENDS_USE_COMPILER.rst b/Help/variable/CMAKE_DEPENDS_USE_COMPILER.rst new file mode 100644 index 0000000..ada4ba6 --- /dev/null +++ b/Help/variable/CMAKE_DEPENDS_USE_COMPILER.rst @@ -0,0 +1,9 @@ +CMAKE_DEPENDS_USE_COMPILER +-------------------------- + +.. versionadded:: 3.20 + +For the :ref:`Makefile Generators`, source dependencies are now, for a +selection of compilers, generated by the compiler itself. By defining this +variable with value ``FALSE``, you can restore the legacy behavior (i.e. using +CMake for dependencies discovery). diff --git a/Help/variable/CMAKE_DIRECTORY_LABELS.rst b/Help/variable/CMAKE_DIRECTORY_LABELS.rst new file mode 100644 index 0000000..81d6dd1 --- /dev/null +++ b/Help/variable/CMAKE_DIRECTORY_LABELS.rst @@ -0,0 +1,8 @@ +CMAKE_DIRECTORY_LABELS +----------------------- + +.. versionadded:: 3.10 + +Specify labels for the current directory. + +This is used to initialize the :prop_dir:`LABELS` directory property. diff --git a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst new file mode 100644 index 0000000..58818f4 --- /dev/null +++ b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst @@ -0,0 +1,18 @@ +CMAKE_DISABLE_FIND_PACKAGE_<PackageName> +---------------------------------------- + +Variable for disabling :command:`find_package` calls. + +Every non-``REQUIRED`` :command:`find_package` call in a project can be +disabled by setting the variable +``CMAKE_DISABLE_FIND_PACKAGE_<PackageName>`` to ``TRUE``. +This can be used to build a project without an optional package, +although that package is installed. + +This switch should be used during the initial CMake run. Otherwise if +the package has already been found in a previous CMake run, the +variables which have been stored in the cache will still be there. In +that case it is recommended to remove the cache variables for this +package from the cache using the cache editor or :option:`cmake -U`. + +See also the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable. diff --git a/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst b/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000..cf52776 --- /dev/null +++ b/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,8 @@ +CMAKE_DISABLE_PRECOMPILE_HEADERS +-------------------------------- + +.. versionadded:: 3.16 + +Default value for :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` of targets. + +By default ``CMAKE_DISABLE_PRECOMPILE_HEADERS`` is ``OFF``. diff --git a/Help/variable/CMAKE_DL_LIBS.rst b/Help/variable/CMAKE_DL_LIBS.rst new file mode 100644 index 0000000..50d313d --- /dev/null +++ b/Help/variable/CMAKE_DL_LIBS.rst @@ -0,0 +1,7 @@ +CMAKE_DL_LIBS +------------- + +Name of library containing ``dlopen`` and ``dlclose``. + +The name of the library that has ``dlopen`` and ``dlclose`` in it, usually +``-ldl`` on most UNIX machines. diff --git a/Help/variable/CMAKE_DOTNET_SDK.rst b/Help/variable/CMAKE_DOTNET_SDK.rst new file mode 100644 index 0000000..dc8806a --- /dev/null +++ b/Help/variable/CMAKE_DOTNET_SDK.rst @@ -0,0 +1,9 @@ +CMAKE_DOTNET_SDK +---------------- + +.. versionadded:: 3.23 + +Default value for :prop_tgt:`DOTNET_SDK` property of targets. + +This variable is used to initialize the :prop_tgt:`DOTNET_SDK` +property on all targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK.rst b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK.rst new file mode 100644 index 0000000..29249d6 --- /dev/null +++ b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK.rst @@ -0,0 +1,18 @@ +CMAKE_DOTNET_TARGET_FRAMEWORK +----------------------------- + +.. versionadded:: 3.17 + +Default value for :prop_tgt:`DOTNET_TARGET_FRAMEWORK` property of +targets. + +This variable is used to initialize the +:prop_tgt:`DOTNET_TARGET_FRAMEWORK` property on all targets. See that +target property for additional information. + +Setting ``CMAKE_DOTNET_TARGET_FRAMEWORK`` may be necessary +when working with ``C#`` and newer .NET framework versions to +avoid referencing errors with the ``ALL_BUILD`` CMake target. + +This variable is only evaluated for :ref:`Visual Studio Generators` +VS 2010 and above. diff --git a/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst new file mode 100644 index 0000000..fc3c360 --- /dev/null +++ b/Help/variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,22 @@ +CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION +------------------------------------- + +.. versionadded:: 3.12 + +Default value for :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` +property of targets. + +This variable is used to initialize the +:prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` property on all +targets. See that target property for additional information. When set, +:variable:`CMAKE_DOTNET_TARGET_FRAMEWORK` takes precednece over this +variable. See that variable or the associated target property +:prop_tgt:`DOTNET_TARGET_FRAMEWORK` for additional information. + + +Setting ``CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION`` may be necessary +when working with ``C#`` and newer .NET framework versions to +avoid referencing errors with the ``ALL_BUILD`` CMake target. + +This variable is only evaluated for :ref:`Visual Studio Generators` +VS 2010 and above. diff --git a/Help/variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES.rst b/Help/variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES.rst new file mode 100644 index 0000000..548c563 --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES.rst @@ -0,0 +1,12 @@ +CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES +--------------------------------------- + +.. versionadded:: 3.6 + +This cache variable is used by the Eclipse project generator. See +:manual:`cmake-generators(7)`. + +The Eclipse project generator generates so-called linked resources +e.g. to the subproject root dirs in the source tree or to the source files +of targets. +This can be disabled by setting this variable to FALSE. diff --git a/Help/variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT.rst b/Help/variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT.rst new file mode 100644 index 0000000..612ab8a --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT.rst @@ -0,0 +1,13 @@ +CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT +------------------------------------- + +.. versionadded:: 3.6 + +This cache variable is used by the Eclipse project generator. See +:manual:`cmake-generators(7)`. + +If this variable is set to TRUE, the Eclipse project generator will generate +an Eclipse project in :variable:`CMAKE_SOURCE_DIR` . This project can then +be used in Eclipse e.g. for the version control functionality. +``CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT`` defaults to ``FALSE``; so +nothing is written into the source directory. diff --git a/Help/variable/CMAKE_ECLIPSE_MAKE_ARGUMENTS.rst b/Help/variable/CMAKE_ECLIPSE_MAKE_ARGUMENTS.rst new file mode 100644 index 0000000..90e36f5 --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_MAKE_ARGUMENTS.rst @@ -0,0 +1,11 @@ +CMAKE_ECLIPSE_MAKE_ARGUMENTS +---------------------------- + +.. versionadded:: 3.6 + +This cache variable is used by the Eclipse project generator. See +:manual:`cmake-generators(7)`. + +This variable holds arguments which are used when Eclipse invokes the make +tool. By default it is initialized to hold flags to enable parallel builds +(using -j typically). diff --git a/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst b/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst new file mode 100644 index 0000000..492acd8 --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_RESOURCE_ENCODING.rst @@ -0,0 +1,8 @@ +CMAKE_ECLIPSE_RESOURCE_ENCODING +------------------------------- + +.. versionadded:: 3.16 + +This cache variable tells the :generator:`Eclipse CDT4` project generator +to set the resource encoding to the given value in generated project files. +If no value is given, no encoding will be set. diff --git a/Help/variable/CMAKE_ECLIPSE_VERSION.rst b/Help/variable/CMAKE_ECLIPSE_VERSION.rst new file mode 100644 index 0000000..db65d89 --- /dev/null +++ b/Help/variable/CMAKE_ECLIPSE_VERSION.rst @@ -0,0 +1,12 @@ +CMAKE_ECLIPSE_VERSION +--------------------- + +.. versionadded:: 3.6 + +This cache variable is used by the Eclipse project generator. See +:manual:`cmake-generators(7)`. + +When using the Eclipse project generator, CMake tries to find the Eclipse +executable and detect the version of it. Depending on the version it finds, +some features are enabled or disabled. If CMake doesn't find +Eclipse, it assumes the oldest supported version, Eclipse Callisto (3.2). diff --git a/Help/variable/CMAKE_EDIT_COMMAND.rst b/Help/variable/CMAKE_EDIT_COMMAND.rst new file mode 100644 index 0000000..2f4ab1f --- /dev/null +++ b/Help/variable/CMAKE_EDIT_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_EDIT_COMMAND +------------------ + +Full path to :manual:`cmake-gui(1)` or :manual:`ccmake(1)`. Defined only for +:ref:`Makefile Generators` when not using an "extra" generator for an IDE. + +This is the full path to the CMake executable that can graphically +edit the cache. For example, :manual:`cmake-gui(1)` or :manual:`ccmake(1)`. diff --git a/Help/variable/CMAKE_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_ENABLE_EXPORTS.rst new file mode 100644 index 0000000..9f43de3 --- /dev/null +++ b/Help/variable/CMAKE_ENABLE_EXPORTS.rst @@ -0,0 +1,10 @@ +CMAKE_ENABLE_EXPORTS +-------------------- + +.. versionadded:: 3.4 + +Specify whether executables export symbols for loadable modules. + +This variable is used to initialize the :prop_tgt:`ENABLE_EXPORTS` target +property for executable targets when they are created by calls to the +:command:`add_executable` command. See the property documentation for details. diff --git a/Help/variable/CMAKE_ERROR_DEPRECATED.rst b/Help/variable/CMAKE_ERROR_DEPRECATED.rst new file mode 100644 index 0000000..f3a6738 --- /dev/null +++ b/Help/variable/CMAKE_ERROR_DEPRECATED.rst @@ -0,0 +1,7 @@ +CMAKE_ERROR_DEPRECATED +---------------------- + +Whether to issue errors for deprecated functionality. + +If ``TRUE``, use of deprecated functionality will issue fatal errors. +If this variable is not set, CMake behaves as if it were set to ``FALSE``. diff --git a/Help/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst b/Help/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst new file mode 100644 index 0000000..38e9b7b --- /dev/null +++ b/Help/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst @@ -0,0 +1,10 @@ +CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION +------------------------------------------- + +Ask ``cmake_install.cmake`` script to error out as soon as a file with +absolute ``INSTALL DESTINATION`` is encountered. + +The fatal error is emitted before the installation of the offending +file takes place. This variable is used by CMake-generated +``cmake_install.cmake`` scripts. If one sets this variable to ``ON`` while +running the script, it may get fatal error messages from the script. diff --git a/Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst b/Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst new file mode 100644 index 0000000..bc4b9df --- /dev/null +++ b/Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst @@ -0,0 +1,10 @@ +CMAKE_EXECUTABLE_SUFFIX +----------------------- + +The suffix for executables on this platform. + +The suffix to use for the end of an executable filename if any, ``.exe`` +on Windows. + +:variable:`CMAKE_EXECUTABLE_SUFFIX_<LANG>` overrides this for +language ``<LANG>``. diff --git a/Help/variable/CMAKE_EXECUTABLE_SUFFIX_LANG.rst b/Help/variable/CMAKE_EXECUTABLE_SUFFIX_LANG.rst new file mode 100644 index 0000000..a68150e --- /dev/null +++ b/Help/variable/CMAKE_EXECUTABLE_SUFFIX_LANG.rst @@ -0,0 +1,7 @@ +CMAKE_EXECUTABLE_SUFFIX_<LANG> +------------------------------ + +The suffix to use for the end of an executable filename of ``<LANG>`` +compiler target architecture, if any. + +It overrides :variable:`CMAKE_EXECUTABLE_SUFFIX` for language ``<LANG>``. diff --git a/Help/variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO.rst b/Help/variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO.rst new file mode 100644 index 0000000..90a16c3 --- /dev/null +++ b/Help/variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO.rst @@ -0,0 +1,8 @@ +CMAKE_EXECUTE_PROCESS_COMMAND_ECHO +---------------------------------- + +.. versionadded:: 3.15 + +If this variable is set to ``STDERR``, ``STDOUT`` or ``NONE`` then commands +in :command:`execute_process` calls will be printed to either stderr or +stdout or not at all. diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS.rst new file mode 100644 index 0000000..9e108f8 --- /dev/null +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS.rst @@ -0,0 +1,6 @@ +CMAKE_EXE_LINKER_FLAGS +---------------------- + +Linker flags to be used to create executables. + +These flags will be used by the linker when creating an executable. diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG.rst new file mode 100644 index 0000000..0cd8113 --- /dev/null +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG.rst @@ -0,0 +1,7 @@ +CMAKE_EXE_LINKER_FLAGS_<CONFIG> +------------------------------- + +Flags to be used when linking an executable. + +Same as ``CMAKE_C_FLAGS_*`` but used by the linker when creating +executables. diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..4d2718a --- /dev/null +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,12 @@ +CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT +------------------------------------ + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_EXE_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_EXE_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..6e3927c --- /dev/null +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst @@ -0,0 +1,13 @@ +CMAKE_EXE_LINKER_FLAGS_INIT +--------------------------- + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_EXE_LINKER_FLAGS` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also the configuration-specific variable +:variable:`CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst new file mode 100644 index 0000000..a7e9029 --- /dev/null +++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -0,0 +1,40 @@ +CMAKE_EXPORT_COMPILE_COMMANDS +----------------------------- + +.. versionadded:: 3.5 + +Enable/Disable output of compile commands during generation. + +If enabled, generates a ``compile_commands.json`` file containing the exact +compiler calls for all translation units of the project in machine-readable +form. The format of the JSON file looks like: + +.. code-block:: javascript + + [ + { + "directory": "/home/user/development/project", + "command": "/usr/bin/c++ ... -c ../foo/foo.cc", + "file": "../foo/foo.cc" + }, + + ... + + { + "directory": "/home/user/development/project", + "command": "/usr/bin/c++ ... -c ../foo/bar.cc", + "file": "../foo/bar.cc" + } + ] + +This is initialized by the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment +variable, and initializes the :prop_tgt:`EXPORT_COMPILE_COMMANDS` target +property for all targets. + +.. note:: + This option is implemented only by :ref:`Makefile Generators` + and :ref:`Ninja Generators`. It is ignored on other generators. + + This option currently does not work well in combination with + the :prop_tgt:`UNITY_BUILD` target property or the + :variable:`CMAKE_UNITY_BUILD` variable. diff --git a/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..5772490 --- /dev/null +++ b/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst @@ -0,0 +1,18 @@ +CMAKE_EXPORT_NO_PACKAGE_REGISTRY +-------------------------------- + +.. versionadded:: 3.1 + +Disable the :command:`export(PACKAGE)` command when :policy:`CMP0090` +is not set to ``NEW``. + +In some cases, for example for packaging and for system wide +installations, it is not desirable to write the user package registry. +If the ``CMAKE_EXPORT_NO_PACKAGE_REGISTRY`` variable is enabled, +the :command:`export(PACKAGE)` command will do nothing. + +If :policy:`CMP0090` is set to ``NEW`` this variable does nothing, and the +:variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable controls the behavior +instead. + +See also :ref:`Disabling the Package Registry`. diff --git a/Help/variable/CMAKE_EXPORT_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_EXPORT_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..663639b --- /dev/null +++ b/Help/variable/CMAKE_EXPORT_PACKAGE_REGISTRY.rst @@ -0,0 +1,17 @@ +CMAKE_EXPORT_PACKAGE_REGISTRY +----------------------------- + +.. versionadded:: 3.15 + +Enables the :command:`export(PACKAGE)` command when :policy:`CMP0090` +is set to ``NEW``. + +The :command:`export(PACKAGE)` command does nothing by default. In some cases +it is desirable to write to the user package registry, so the +``CMAKE_EXPORT_PACKAGE_REGISTRY`` variable may be set to enable it. + +If :policy:`CMP0090` is *not* set to ``NEW`` this variable does nothing, and +the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable controls the behavior +instead. + +See also :ref:`Disabling the Package Registry`. diff --git a/Help/variable/CMAKE_EXTRA_GENERATOR.rst b/Help/variable/CMAKE_EXTRA_GENERATOR.rst new file mode 100644 index 0000000..2c92323 --- /dev/null +++ b/Help/variable/CMAKE_EXTRA_GENERATOR.rst @@ -0,0 +1,10 @@ +CMAKE_EXTRA_GENERATOR +--------------------- + +The extra generator used to build the project. See +:manual:`cmake-generators(7)`. + +When using the Eclipse, CodeBlocks, CodeLite, Kate or Sublime generators, CMake +generates Makefiles (:variable:`CMAKE_GENERATOR`) and additionally project +files for the respective IDE. This IDE project file generator is stored in +``CMAKE_EXTRA_GENERATOR`` (e.g. ``Eclipse CDT4``). diff --git a/Help/variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES.rst b/Help/variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES.rst new file mode 100644 index 0000000..a130adb --- /dev/null +++ b/Help/variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES.rst @@ -0,0 +1,9 @@ +CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES +----------------------------------- + +Additional suffixes for shared libraries. + +Extensions for shared libraries other than that specified by +:variable:`CMAKE_SHARED_LIBRARY_SUFFIX`, if any. CMake uses this to recognize +external shared library files during analysis of libraries linked by a +target. diff --git a/Help/variable/CMAKE_FIND_APPBUNDLE.rst b/Help/variable/CMAKE_FIND_APPBUNDLE.rst new file mode 100644 index 0000000..17563f3 --- /dev/null +++ b/Help/variable/CMAKE_FIND_APPBUNDLE.rst @@ -0,0 +1,24 @@ +CMAKE_FIND_APPBUNDLE +-------------------- + +.. versionadded:: 3.4 + +This variable affects how ``find_*`` commands choose between +macOS Application Bundles and unix-style package components. + +On Darwin or systems supporting macOS Application Bundles, the +``CMAKE_FIND_APPBUNDLE`` variable can be set to empty or +one of the following: + +``FIRST`` + Try to find application bundles before standard programs. + This is the default on Darwin. + +``LAST`` + Try to find application bundles after standard programs. + +``ONLY`` + Only try to find application bundles. + +``NEVER`` + Never try to find application bundles. diff --git a/Help/variable/CMAKE_FIND_DEBUG_MODE.rst b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst new file mode 100644 index 0000000..48b0dce --- /dev/null +++ b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst @@ -0,0 +1,25 @@ +CMAKE_FIND_DEBUG_MODE +--------------------- + +.. versionadded:: 3.17 + +Print extra find call information for the following commands to standard +error: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +Output is designed for human consumption and not for parsing. +Enabling this variable is equivalent to using :option:`cmake --debug-find` +with the added ability to enable debugging for a subset of find calls. + +.. code-block:: cmake + + set(CMAKE_FIND_DEBUG_MODE TRUE) + find_program(...) + set(CMAKE_FIND_DEBUG_MODE FALSE) + +Default is unset. diff --git a/Help/variable/CMAKE_FIND_FRAMEWORK.rst b/Help/variable/CMAKE_FIND_FRAMEWORK.rst new file mode 100644 index 0000000..3b62cda --- /dev/null +++ b/Help/variable/CMAKE_FIND_FRAMEWORK.rst @@ -0,0 +1,24 @@ +CMAKE_FIND_FRAMEWORK +-------------------- + +.. versionadded:: 3.4 + +This variable affects how ``find_*`` commands choose between +macOS Frameworks and unix-style package components. + +On Darwin or systems supporting macOS Frameworks, the +``CMAKE_FIND_FRAMEWORK`` variable can be set to empty or +one of the following: + +``FIRST`` + Try to find frameworks before standard libraries or headers. + This is the default on Darwin. + +``LAST`` + Try to find frameworks after standard libraries or headers. + +``ONLY`` + Only try to find frameworks. + +``NEVER`` + Never try to find frameworks. diff --git a/Help/variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX.rst b/Help/variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX.rst new file mode 100644 index 0000000..ca2ad7f --- /dev/null +++ b/Help/variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX.rst @@ -0,0 +1,14 @@ +CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX +------------------------------------ + +.. versionadded:: 3.9 + +Specify a ``<suffix>`` to tell the :command:`find_library` command to +search in a ``lib<suffix>`` directory before each ``lib`` directory that +would normally be searched. + +This overrides the behavior of related global properties: + +* :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` +* :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` +* :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` diff --git a/Help/variable/CMAKE_FIND_LIBRARY_PREFIXES.rst b/Help/variable/CMAKE_FIND_LIBRARY_PREFIXES.rst new file mode 100644 index 0000000..58354b2 --- /dev/null +++ b/Help/variable/CMAKE_FIND_LIBRARY_PREFIXES.rst @@ -0,0 +1,9 @@ +CMAKE_FIND_LIBRARY_PREFIXES +--------------------------- + +Prefixes to prepend when looking for libraries. + +This specifies what prefixes to add to library names when the +:command:`find_library` command looks for libraries. On UNIX systems this is +typically ``lib``, meaning that when trying to find the ``foo`` library it +will look for ``libfoo``. diff --git a/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst b/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst new file mode 100644 index 0000000..c2c2609 --- /dev/null +++ b/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst @@ -0,0 +1,12 @@ +CMAKE_FIND_LIBRARY_SUFFIXES +--------------------------- + +Suffixes to append when looking for libraries. + +This specifies what suffixes to add to library names when the +:command:`find_library` command looks for libraries. On Windows systems this +is typically ``.lib`` and, depending on the compiler, ``.dll.a``, ``.a`` +(e.g. GCC and Clang), so when it tries to find the ``foo`` library, it will +look for ``[<prefix>]foo.lib`` and/or ``[<prefix>]foo[.dll].a``, depending on +the compiler used and the ``<prefix>`` specified in the +:variable:`CMAKE_FIND_LIBRARY_PREFIXES`. diff --git a/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst b/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst new file mode 100644 index 0000000..789dc99 --- /dev/null +++ b/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst @@ -0,0 +1,19 @@ +CMAKE_FIND_NO_INSTALL_PREFIX +---------------------------- + +Exclude the values of the :variable:`CMAKE_INSTALL_PREFIX` and +:variable:`CMAKE_STAGING_PREFIX` variables from +:variable:`CMAKE_SYSTEM_PREFIX_PATH`. CMake adds these project-destination +prefixes to :variable:`CMAKE_SYSTEM_PREFIX_PATH` by default in order to +support building a series of dependent packages and installing them into +a common prefix. Set ``CMAKE_FIND_NO_INSTALL_PREFIX`` to ``TRUE`` +to suppress this behavior. + +The :variable:`CMAKE_SYSTEM_PREFIX_PATH` is initialized on the first call to a +:command:`project` or :command:`enable_language` command. Therefore one must +set ``CMAKE_FIND_NO_INSTALL_PREFIX`` before this in order to take effect. A +user may set the variable as a cache entry on the command line to achieve this. + +Note that the prefix(es) may still be searched for other reasons, such as being +the same prefix as the CMake installation, or for being a built-in system +prefix. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NAME.rst b/Help/variable/CMAKE_FIND_PACKAGE_NAME.rst new file mode 100644 index 0000000..fc1fd43 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_NAME.rst @@ -0,0 +1,8 @@ +CMAKE_FIND_PACKAGE_NAME +----------------------- + +.. versionadded:: 3.1.1 + +Defined by the :command:`find_package` command while loading +a find module to record the caller-specified package name. +See command documentation for details. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..5392ad1 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst @@ -0,0 +1,26 @@ +CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY +-------------------------------------- + +.. versionadded:: 3.1 + +.. deprecated:: 3.16 + + Use the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable instead. + +By default this variable is not set. If neither +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` nor +``CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`` is set, then +:command:`find_package()` will use the :ref:`User Package Registry` +unless the ``NO_CMAKE_PACKAGE_REGISTRY`` option is provided. + +``CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`` is ignored if +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` is set. + +In some cases, for example to locate only system wide installations, it +is not desirable to use the :ref:`User Package Registry` when searching +for packages. If the ``CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`` +variable is ``TRUE``, all the :command:`find_package` commands will skip +the :ref:`User Package Registry` as if they were called with the +``NO_CMAKE_PACKAGE_REGISTRY`` argument. + +See also :ref:`Disabling the Package Registry`. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..21b0230 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst @@ -0,0 +1,26 @@ +CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY +--------------------------------------------- + +.. versionadded:: 3.1 + +.. deprecated:: 3.16 + + Use the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variable instead. + +By default this variable is not set. If neither +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` nor +``CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`` is set, then +:command:`find_package()` will use the :ref:`System Package Registry` +unless the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` option is provided. + +``CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`` is ignored if +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` is set. + +In some cases, it is not desirable to use the +:ref:`System Package Registry` when searching for packages. If the +``CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`` variable is +``TRUE``, all the :command:`find_package` commands will skip +the :ref:`System Package Registry` as if they were called with the +``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` argument. + +See also :ref:`Disabling the Package Registry`. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG.rst b/Help/variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG.rst new file mode 100644 index 0000000..ba81529 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG.rst @@ -0,0 +1,29 @@ +CMAKE_FIND_PACKAGE_PREFER_CONFIG +--------------------------------- + +.. versionadded:: 3.15 + +Tell :command:`find_package` to try "Config" mode before "Module" mode if no +mode was specified. + +The command :command:`find_package` operates without an explicit mode when +the reduced signature is used without the ``MODULE`` option. In this case, +by default, CMake first tries Module mode by searching for a +``Find<pkg>.cmake`` module. If it fails, CMake then searches for the package +using Config mode. + +Set ``CMAKE_FIND_PACKAGE_PREFER_CONFIG`` to ``TRUE`` to tell +:command:`find_package` to first search using Config mode before falling back +to Module mode. + +This variable may be useful when a developer has compiled a custom version of +a common library and wishes to link it to a dependent project. If this +variable is set to ``TRUE``, it would prevent a dependent project's call +to :command:`find_package` from selecting the default library located by the +system's ``Find<pkg>.cmake`` module before finding the developer's custom +built library. + +Once this variable is set, it is the responsibility of the exported +``<pkg>Config.cmake`` files to provide the same result variables as the +``Find<pkg>.cmake`` modules so that dependent projects can use them +interchangeably. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst new file mode 100644 index 0000000..b27a3d9 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR.rst @@ -0,0 +1,28 @@ +CMAKE_FIND_PACKAGE_REDIRECTS_DIR +-------------------------------- + +.. versionadded:: 3.24 + +This read-only variable specifies a directory that the :command:`find_package` +command will check first before searching anywhere else for a module or config +package file. A config package file in this directory will always be found in +preference to any other Find module file or config package file. + +The primary purpose of this variable is to facilitate integration between +:command:`find_package` and :command:`FetchContent_MakeAvailable`. The latter +command may create files in the ``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` directory +when it populates a dependency. This allows subsequent calls to +:command:`find_package` for the same dependency to re-use the populated +contents instead of trying to satisfy the dependency from somewhere external +to the build. Projects may also want to write files into this directory in +some situations (see :ref:`FetchContent-find_package-integration-examples` +for examples). + +The directory that ``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` points to will always +be erased and recreated empty at the start of every CMake run. Any files +written into this directory during the CMake run will be lost the next time +CMake configures the project. + +``CMAKE_FIND_PACKAGE_REDIRECTS_DIR`` is only set in CMake project mode. +It is not set when CMake is run in script mode +(i.e. :option:`cmake -P`). diff --git a/Help/variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS.rst b/Help/variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS.rst new file mode 100644 index 0000000..86d75e7 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS.rst @@ -0,0 +1,12 @@ +CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS +----------------------------------- + +.. versionadded:: 3.14 + +Set to ``TRUE`` to tell :command:`find_package` calls to resolve symbolic +links in the value of ``<PackageName>_DIR``. + +This is helpful in use cases where the package search path points at a +proxy directory in which symlinks to the real package locations appear. +This is not enabled by default because there are also common use cases +in which the symlinks should be preserved. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION.rst b/Help/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION.rst new file mode 100644 index 0000000..98c2a8f --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION.rst @@ -0,0 +1,18 @@ +CMAKE_FIND_PACKAGE_SORT_DIRECTION +--------------------------------- + +.. versionadded:: 3.7 + +The sorting direction used by :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`. +It can assume one of the following values: + +``DEC`` + Default. Ordering is done in descending mode. + The highest folder found will be tested first. + +``ASC`` + Ordering is done in ascending mode. + The lowest folder found will be tested first. + +If :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` is not set or is set to ``NONE`` +this variable has no effect. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst b/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst new file mode 100644 index 0000000..1725ba1 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst @@ -0,0 +1,38 @@ +CMAKE_FIND_PACKAGE_SORT_ORDER +----------------------------- + +.. versionadded:: 3.7 + +The default order for sorting packages found using :command:`find_package`. +It can assume one of the following values: + +``NONE`` + Default. No attempt is done to sort packages. + The first valid package found will be selected. + +``NAME`` + Sort packages lexicographically before selecting one. + +``NATURAL`` + Sort packages using natural order (see ``strverscmp(3)`` manual), + i.e. such that contiguous digits are compared as whole numbers. + +Natural sorting can be employed to return the highest version when multiple +versions of the same library are found by :command:`find_package`. For +example suppose that the following libraries have been found: + +* libX-1.1.0 +* libX-1.2.9 +* libX-1.2.10 + +By setting ``NATURAL`` order we can select the one with the highest +version number ``libX-1.2.10``. + +.. code-block:: cmake + + set(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) + find_package(libX CONFIG) + +The sort direction can be controlled using the +:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` variable +(by default decrescent, e.g. lib-B will be tested before lib-A). diff --git a/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst b/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst new file mode 100644 index 0000000..fc9b315 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst @@ -0,0 +1,12 @@ +CMAKE_FIND_PACKAGE_TARGETS_GLOBAL +--------------------------------- + +.. versionadded:: 3.24 + +Setting to ``TRUE`` promotes all :prop_tgt:`IMPORTED` targets discoverd +by :command:`find_package` to a ``GLOBAL`` scope. + + +Setting this to ``TRUE`` is akin to specifying ``GLOBAL`` +as an argument to :command:`find_package`. +Default value is ``OFF``. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE.rst b/Help/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE.rst new file mode 100644 index 0000000..5c4f23a --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE.rst @@ -0,0 +1,22 @@ +CMAKE_FIND_PACKAGE_WARN_NO_MODULE +--------------------------------- + +Tell :command:`find_package` to warn if called without an explicit mode. + +If :command:`find_package` is called without an explicit mode option +(``MODULE``, ``CONFIG``, or ``NO_MODULE``) and no ``Find<pkg>.cmake`` module +is in :variable:`CMAKE_MODULE_PATH` then CMake implicitly assumes that the +caller intends to search for a package configuration file. If no package +configuration file is found then the wording of the failure message +must account for both the case that the package is really missing and +the case that the project has a bug and failed to provide the intended +Find module. If instead the caller specifies an explicit mode option +then the failure message can be more specific. + +Set ``CMAKE_FIND_PACKAGE_WARN_NO_MODULE`` to ``TRUE`` to tell +:command:`find_package` to warn when it implicitly assumes Config mode. This +helps developers enforce use of an explicit mode in all calls to +:command:`find_package` within a project. + +This variable has no effect if :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` is +set to ``TRUE``. diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_ROOT_PATH.rst new file mode 100644 index 0000000..6172c56 --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_FIND_ROOT_PATH +-------------------- + +:ref:`Semicolon-separated list <CMake Language Lists>` of root paths to search on the filesystem. + +This variable is most useful when cross-compiling. CMake uses the paths in +this list as alternative roots to find filesystem items with +:command:`find_package`, :command:`find_library` etc. diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst new file mode 100644 index 0000000..df1af5a --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_INCLUDE +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_file` and :command:`find_path` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst new file mode 100644 index 0000000..52ab89d --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_LIBRARY +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_library` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst new file mode 100644 index 0000000..3872947 --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_PACKAGE +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_package` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst new file mode 100644 index 0000000..d24a78a --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_PROGRAM +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_program` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt new file mode 100644 index 0000000..ab65e09 --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt @@ -0,0 +1,8 @@ +This variable controls whether the :variable:`CMAKE_FIND_ROOT_PATH` and +:variable:`CMAKE_SYSROOT` are used by |FIND_XXX|. + +If set to ``ONLY``, then only the roots in :variable:`CMAKE_FIND_ROOT_PATH` +will be searched. If set to ``NEVER``, then the roots in +:variable:`CMAKE_FIND_ROOT_PATH` will be ignored and only the host system +root will be used. If set to ``BOTH``, then the host system paths and the +paths in :variable:`CMAKE_FIND_ROOT_PATH` will be searched. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst new file mode 100644 index 0000000..f72fd65 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst @@ -0,0 +1,27 @@ +CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH +------------------------------------- + +.. versionadded:: 3.16 + +Controls the default behavior of the following commands for whether or not to +search paths provided by cmake-specific environment variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst new file mode 100644 index 0000000..47ce3a3 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst @@ -0,0 +1,26 @@ +CMAKE_FIND_USE_CMAKE_PATH +------------------------- + +.. versionadded:: 3.16 + +Controls the default behavior of the following commands for whether or not to +search paths provided by cmake-specific cache variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst new file mode 100644 index 0000000..2c1d237 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst @@ -0,0 +1,27 @@ +CMAKE_FIND_USE_CMAKE_SYSTEM_PATH +-------------------------------- + +.. versionadded:: 3.16 + +Controls the default behavior of the following commands for whether or not to +search paths provided by platform-specific cmake variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst new file mode 100644 index 0000000..d577a8a --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst @@ -0,0 +1,40 @@ +CMAKE_FIND_USE_INSTALL_PREFIX +----------------------------------- + +.. versionadded:: 3.24 + +Controls the default behavior of the following commands for whether or not to +search the locations in the :variable:`CMAKE_INSTALL_PREFIX` and +:variable:`CMAKE_STAGING_PREFIX` variables. + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +Due to backwards compatibility with :variable:`CMAKE_FIND_NO_INSTALL_PREFIX`, +the behavior of the find command change based on if this variable exists. + +============================== ============================ =========== + CMAKE_FIND_USE_INSTALL_PREFIX CMAKE_FIND_NO_INSTALL_PREFIX Search +============================== ============================ =========== + Not Defined On NO + Not Defined Off || Not Defined YES + Off On NO + Off Off || Not Defined NO + On On YES + On Off || Not Defined YES +============================== ============================ =========== + +By default this variable is not defined. Explicit options given to the above +commands take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..b058ba0 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst @@ -0,0 +1,33 @@ +CMAKE_FIND_USE_PACKAGE_REGISTRY +------------------------------- + +.. versionadded:: 3.16 + +Controls the default behavior of the :command:`find_package` command for +whether or not to search paths provided by the :ref:`User Package Registry`. + +By default this variable is not set and the behavior will fall back +to that determined by the deprecated +:variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` variable. If that is +also not set, then :command:`find_package` will use the +:ref:`User Package Registry` unless the ``NO_CMAKE_PACKAGE_REGISTRY`` option +is provided. + +This variable takes precedence over +:variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` when both are set. + +In some cases, for example to locate only system wide installations, it +is not desirable to use the :ref:`User Package Registry` when searching +for packages. If the ``CMAKE_FIND_USE_PACKAGE_REGISTRY`` +variable is ``FALSE``, all the :command:`find_package` commands will skip +the :ref:`User Package Registry` as if they were called with the +``NO_CMAKE_PACKAGE_REGISTRY`` argument. + +See also :ref:`Disabling the Package Registry` and the +:variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst new file mode 100644 index 0000000..1f876a9 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst @@ -0,0 +1,25 @@ +CMAKE_FIND_USE_PACKAGE_ROOT_PATH +-------------------------------- + +.. versionadded:: 3.16 + +Controls the default behavior of the following commands for whether or not to +search paths provided by :variable:`<PackageName>_ROOT` variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variables. diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst new file mode 100644 index 0000000..65edd10 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst @@ -0,0 +1,27 @@ +CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH +-------------------------------------- + +.. versionadded:: 3.16 + +Controls the default behavior of the following commands for whether or not to +search paths provided by standard system environment variables: + +* :command:`find_program` +* :command:`find_library` +* :command:`find_file` +* :command:`find_path` +* :command:`find_package` + +This is useful in cross-compiling environments. + +By default this variable is not set, which is equivalent to it having +a value of ``TRUE``. Explicit options given to the above commands +take precedence over this variable. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +:variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH`, +and :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variables. diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..2527904 --- /dev/null +++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst @@ -0,0 +1,34 @@ +CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY +-------------------------------------- + +.. versionadded:: 3.16 + +Controls searching the :ref:`System Package Registry` by the +:command:`find_package` command. + +By default this variable is not set and the behavior will fall back +to that determined by the deprecated +:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` variable. +If that is also not set, then :command:`find_package()` will use the +:ref:`System Package Registry` unless the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` +option is provided. + +This variable takes precedence over +:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` when both are set. + +In some cases, for example to locate only user specific installations, it +is not desirable to use the :ref:`System Package Registry` when searching +for packages. If the ``CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`` +variable is ``FALSE``, all the :command:`find_package` commands will skip +the :ref:`System Package Registry` as if they were called with the +``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` argument. + +See also :ref:`Disabling the Package Registry`. + +See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, +:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`, +:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, +:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, +:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`, +and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables. diff --git a/Help/variable/CMAKE_FOLDER.rst b/Help/variable/CMAKE_FOLDER.rst new file mode 100644 index 0000000..37f137c --- /dev/null +++ b/Help/variable/CMAKE_FOLDER.rst @@ -0,0 +1,9 @@ +CMAKE_FOLDER +------------ + +.. versionadded:: 3.12 + +Set the folder name. Use to organize targets in an IDE. + +This variable is used to initialize the :prop_tgt:`FOLDER` property on all the +targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_FRAMEWORK.rst b/Help/variable/CMAKE_FRAMEWORK.rst new file mode 100644 index 0000000..37385bf --- /dev/null +++ b/Help/variable/CMAKE_FRAMEWORK.rst @@ -0,0 +1,9 @@ +CMAKE_FRAMEWORK +--------------- + +.. versionadded:: 3.15 + +Default value for :prop_tgt:`FRAMEWORK` of targets. + +This variable is used to initialize the :prop_tgt:`FRAMEWORK` property on +all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst b/Help/variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst new file mode 100644 index 0000000..47fb66e --- /dev/null +++ b/Help/variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst @@ -0,0 +1,10 @@ +CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> +--------------------------------------------- + +.. versionadded:: 3.18 + +Default framework filename postfix under configuration ``<CONFIG>`` when +using a multi-config generator. + +When a framework target is created its :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` +target property is initialized with the value of this variable if it is set. diff --git a/Help/variable/CMAKE_FRAMEWORK_PATH.rst b/Help/variable/CMAKE_FRAMEWORK_PATH.rst new file mode 100644 index 0000000..13ade4e --- /dev/null +++ b/Help/variable/CMAKE_FRAMEWORK_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_FRAMEWORK_PATH +-------------------- + +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path +for macOS frameworks used by the :command:`find_library`, +:command:`find_package`, :command:`find_path`, and :command:`find_file` +commands. diff --git a/Help/variable/CMAKE_Fortran_FORMAT.rst b/Help/variable/CMAKE_Fortran_FORMAT.rst new file mode 100644 index 0000000..1406e59 --- /dev/null +++ b/Help/variable/CMAKE_Fortran_FORMAT.rst @@ -0,0 +1,7 @@ +CMAKE_Fortran_FORMAT +-------------------- + +Set to ``FIXED`` or ``FREE`` to indicate the Fortran source layout. + +This variable is used to initialize the :prop_tgt:`Fortran_FORMAT` property on +all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_Fortran_MODDIR_DEFAULT.rst b/Help/variable/CMAKE_Fortran_MODDIR_DEFAULT.rst new file mode 100644 index 0000000..5aeab07 --- /dev/null +++ b/Help/variable/CMAKE_Fortran_MODDIR_DEFAULT.rst @@ -0,0 +1,8 @@ +CMAKE_Fortran_MODDIR_DEFAULT +---------------------------- + +Fortran default module output directory. + +Most Fortran compilers write ``.mod`` files to the current working +directory. For those that do not, this is set to ``.`` and used when +the :prop_tgt:`Fortran_MODULE_DIRECTORY` target property is not set. diff --git a/Help/variable/CMAKE_Fortran_MODDIR_FLAG.rst b/Help/variable/CMAKE_Fortran_MODDIR_FLAG.rst new file mode 100644 index 0000000..1da55ca --- /dev/null +++ b/Help/variable/CMAKE_Fortran_MODDIR_FLAG.rst @@ -0,0 +1,7 @@ +CMAKE_Fortran_MODDIR_FLAG +------------------------- + +Fortran flag for module output directory. + +This stores the flag needed to pass the value of the +:prop_tgt:`Fortran_MODULE_DIRECTORY` target property to the compiler. diff --git a/Help/variable/CMAKE_Fortran_MODOUT_FLAG.rst b/Help/variable/CMAKE_Fortran_MODOUT_FLAG.rst new file mode 100644 index 0000000..2f83880 --- /dev/null +++ b/Help/variable/CMAKE_Fortran_MODOUT_FLAG.rst @@ -0,0 +1,7 @@ +CMAKE_Fortran_MODOUT_FLAG +------------------------- + +Fortran flag to enable module output. + +Most Fortran compilers write ``.mod`` files out by default. For others, +this stores the flag needed to enable module output. diff --git a/Help/variable/CMAKE_Fortran_MODULE_DIRECTORY.rst b/Help/variable/CMAKE_Fortran_MODULE_DIRECTORY.rst new file mode 100644 index 0000000..3c7edc1 --- /dev/null +++ b/Help/variable/CMAKE_Fortran_MODULE_DIRECTORY.rst @@ -0,0 +1,8 @@ +CMAKE_Fortran_MODULE_DIRECTORY +------------------------------ + +Fortran module output directory. + +This variable is used to initialize the :prop_tgt:`Fortran_MODULE_DIRECTORY` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_Fortran_PREPROCESS.rst b/Help/variable/CMAKE_Fortran_PREPROCESS.rst new file mode 100644 index 0000000..7d405f3 --- /dev/null +++ b/Help/variable/CMAKE_Fortran_PREPROCESS.rst @@ -0,0 +1,10 @@ +CMAKE_Fortran_PREPROCESS +------------------------ + +.. versionadded:: 3.18 + +Default value for :prop_tgt:`Fortran_PREPROCESS` of targets. + +This variable is used to initialize the :prop_tgt:`Fortran_PREPROCESS` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_GENERATOR.rst b/Help/variable/CMAKE_GENERATOR.rst new file mode 100644 index 0000000..0e249eb --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR.rst @@ -0,0 +1,12 @@ +CMAKE_GENERATOR +--------------- + +The generator used to build the project. See :manual:`cmake-generators(7)`. + +The name of the generator that is being used to generate the build +files. (e.g. ``Unix Makefiles``, ``Ninja``, etc.) + +The value of this variable should never be modified by project code. +A generator may be selected via the :option:`cmake -G` option, +interactively in :manual:`cmake-gui(1)`, or via the :envvar:`CMAKE_GENERATOR` +environment variable. diff --git a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst new file mode 100644 index 0000000..4317622 --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst @@ -0,0 +1,64 @@ +CMAKE_GENERATOR_INSTANCE +------------------------ + +.. versionadded:: 3.11 + +Generator-specific instance specification provided by user. + +Some CMake generators support selection of an instance of the native build +system when multiple instances are available. If the user specifies an +instance (e.g. by setting this cache entry or via the +:envvar:`CMAKE_GENERATOR_INSTANCE` environment variable), or after a default +instance is chosen when a build tree is first configured, the value will be +available in this variable. + +The value of this variable should never be modified by project code. +A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE` +variable may initialize ``CMAKE_GENERATOR_INSTANCE`` as a cache entry. +Once a given build tree has been initialized with a particular value +for this variable, changing the value has undefined behavior. + +Instance specification is supported only on specific generators. + +Visual Studio Instance Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:ref:`Visual Studio Generators` support instance specification for +Visual Studio 2017 and above. The ``CMAKE_GENERATOR_INSTANCE`` variable +may be set as a cache entry selecting an instance of Visual Studio +via one of the following forms: + +* ``location`` +* ``location[,key=value]*`` +* ``key=value[,key=value]*`` + +The ``location`` specifies the absolute path to the top-level directory +of the VS installation. + +The ``key=value`` pairs form a comma-separated list of options to +specify details of the instance selection. +Supported pairs are: + +``version=<major>.<minor>.<date>.<build>`` + .. versionadded:: 3.23 + + Specify the 4-component VS Build Version, a.k.a. Build Number. + + .. include:: CMAKE_VS_VERSION_BUILD_NUMBER_COMPONENTS.txt + +.. versionadded:: 3.23 + + A portable VS instance, which is not known to the Visual Studio Installer, + may be specified by providing both ``location`` and ``version=``. + +If the value of ``CMAKE_GENERATOR_INSTANCE`` is not specified explicitly +by the user or a toolchain file, CMake queries the Visual Studio Installer +to locate VS instances, chooses one, and sets the variable as a cache entry +to hold the value persistently. If an environment variable of the form +``VS##0COMNTOOLS``, where ``##`` the Visual Studio major version number, +is set and points to the ``Common7/Tools`` directory within one of the +VS instances, that instance will be used. Otherwise, if more than one +VS instance is installed we do not define which one is chosen by default. + +The VS version build number of the selected VS instance is provided in +the :variable:`CMAKE_VS_VERSION_BUILD_NUMBER` variable. diff --git a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst new file mode 100644 index 0000000..acb7b2e --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst @@ -0,0 +1,33 @@ +CMAKE_GENERATOR_PLATFORM +------------------------ + +.. versionadded:: 3.1 + +Generator-specific target platform specification provided by user. + +Some CMake generators support a target platform name to be given +to the native build system to choose a compiler toolchain. +If the user specifies a platform name (e.g. via the :option:`cmake -A` +option or via the :envvar:`CMAKE_GENERATOR_PLATFORM` environment variable) +the value will be available in this variable. + +The value of this variable should never be modified by project code. +A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE` +variable may initialize ``CMAKE_GENERATOR_PLATFORM``. Once a given +build tree has been initialized with a particular value for this +variable, changing the value has undefined behavior. + +Platform specification is supported only on specific generators: + +* For :ref:`Visual Studio Generators` with VS 2005 and above this + specifies the target architecture. + +* For :generator:`Green Hills MULTI` this specifies the target architecture. + +See native build system documentation for allowed platform names. + +Visual Studio Platform Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On :ref:`Visual Studio Generators` the selected platform name +is provided in the :variable:`CMAKE_VS_PLATFORM_NAME` variable. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst new file mode 100644 index 0000000..4855477 --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -0,0 +1,89 @@ +CMAKE_GENERATOR_TOOLSET +----------------------- + +Native build system toolset specification provided by user. + +Some CMake generators support a toolset specification to tell the +native build system how to choose a compiler. If the user specifies +a toolset (e.g. via the :option:`cmake -T` option or via +the :envvar:`CMAKE_GENERATOR_TOOLSET` environment variable) the value +will be available in this variable. + +The value of this variable should never be modified by project code. +A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE` +variable may initialize ``CMAKE_GENERATOR_TOOLSET``. Once a given +build tree has been initialized with a particular value for this +variable, changing the value has undefined behavior. + +Toolset specification is supported only on specific generators: + +* :ref:`Visual Studio Generators` for VS 2010 and above +* The :generator:`Xcode` generator for Xcode 3.0 and above +* The :generator:`Green Hills MULTI` generator + +See native build system documentation for allowed toolset names. + +Visual Studio Toolset Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The :ref:`Visual Studio Generators` support toolset specification +using one of these forms: + +* ``toolset`` +* ``toolset[,key=value]*`` +* ``key=value[,key=value]*`` + +The ``toolset`` specifies the toolset name. The selected toolset name +is provided in the :variable:`CMAKE_VS_PLATFORM_TOOLSET` variable. + +The ``key=value`` pairs form a comma-separated list of options to +specify generator-specific details of the toolset selection. +Supported pairs are: + +``cuda=<version>|<path>`` + Specify the CUDA toolkit version to use or the path to a + standalone CUDA toolkit directory. Supported by VS 2010 + and above. The version can only be used with the CUDA + toolkit VS integration globally installed. + See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA` and + :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR` variables. + +``host=<arch>`` + Specify the host tools architecture as ``x64`` or ``x86``. + Supported by VS 2013 and above. + See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE` + variable. + +``version=<version>`` + Specify the toolset version to use. Supported by VS 2017 + and above with the specified toolset installed. + See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_VERSION` variable. + +``VCTargetsPath=<path>`` + Specify an alternative ``VCTargetsPath`` value for Visual Studio + project files. This allows use of VS platform extension configuration + files (``.props`` and ``.targets``) that are not installed with VS. + +Visual Studio Toolset Customization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**These are unstable interfaces with no compatibility guarantees** +because they hook into undocumented internal CMake implementation details. +Institutions may use these to internally maintain support for non-public +Visual Studio platforms and toolsets, but must accept responsibility to +make updates as changes are made to CMake. + +Additional ``key=value`` pairs are available: + +``customFlagTableDir=<path>`` + .. versionadded:: 3.21 + + Specify the absolute path to a directory from which to load custom + flag tables stored as JSON documents with file names of the form + ``<platform>_<toolset>_<tool>.json`` or ``<platform>_<tool>.json``, + where ``<platform>`` is the :variable:`CMAKE_VS_PLATFORM_NAME`, + ``<toolset>`` is the :variable:`CMAKE_VS_PLATFORM_TOOLSET`, + and ``<tool>`` is the tool for which the flag table is meant. + **This naming pattern is an internal CMake implementation detail.** + The ``<tool>`` names are undocumented. The format of the ``.json`` + flag table files is undocumented. diff --git a/Help/variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE.rst b/Help/variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE.rst new file mode 100644 index 0000000..0e8ae5e --- /dev/null +++ b/Help/variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE.rst @@ -0,0 +1,8 @@ +CMAKE_GHS_NO_SOURCE_GROUP_FILE +------------------------------ + +.. versionadded:: 3.14 + +``ON`` / ``OFF`` boolean to control if the project file for a target should +be one single file or multiple files. Refer to +:prop_tgt:`GHS_NO_SOURCE_GROUP_FILE` for further details. diff --git a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst new file mode 100644 index 0000000..7d3f9c3 --- /dev/null +++ b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst @@ -0,0 +1,28 @@ +CMAKE_GLOBAL_AUTOGEN_TARGET +--------------------------- + +.. versionadded:: 3.14 + +Switch to enable generation of a global ``autogen`` target. + +When ``CMAKE_GLOBAL_AUTOGEN_TARGET`` is enabled, a custom target +``autogen`` is generated. This target depends on all :prop_tgt:`AUTOMOC` and +:prop_tgt:`AUTOUIC` generated ``<ORIGIN>_autogen`` targets in the project. +By building the global ``autogen`` target, all :prop_tgt:`AUTOMOC` and +:prop_tgt:`AUTOUIC` files in the project will be generated. + +The name of the global ``autogen`` target can be changed by setting +:variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME`. + +By default ``CMAKE_GLOBAL_AUTOGEN_TARGET`` is unset. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. + +Note +^^^^ + +``<ORIGIN>_autogen`` targets by default inherit their origin target's +dependencies. This might result in unintended dependency target +builds when only ``<ORIGIN>_autogen`` targets are built. A solution is to +disable :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` on the respective origin targets. diff --git a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.rst b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.rst new file mode 100644 index 0000000..d970d56 --- /dev/null +++ b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME.rst @@ -0,0 +1,15 @@ +CMAKE_GLOBAL_AUTOGEN_TARGET_NAME +-------------------------------- + +.. versionadded:: 3.14 + +Change the name of the global ``autogen`` target. + +When :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET` is enabled, a global custom target +named ``autogen`` is created. ``CMAKE_GLOBAL_AUTOGEN_TARGET_NAME`` +allows to set a different name for that target. + +By default ``CMAKE_GLOBAL_AUTOGEN_TARGET_NAME`` is unset. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET.rst b/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET.rst new file mode 100644 index 0000000..0b8c309 --- /dev/null +++ b/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET.rst @@ -0,0 +1,20 @@ +CMAKE_GLOBAL_AUTORCC_TARGET +--------------------------- + +.. versionadded:: 3.14 + +Switch to enable generation of a global ``autorcc`` target. + +When ``CMAKE_GLOBAL_AUTORCC_TARGET`` is enabled, a custom target +``autorcc`` is generated. This target depends on all :prop_tgt:`AUTORCC` +generated ``<ORIGIN>_arcc_<QRC>`` targets in the project. +By building the global ``autorcc`` target, all :prop_tgt:`AUTORCC` +files in the project will be generated. + +The name of the global ``autorcc`` target can be changed by setting +:variable:`CMAKE_GLOBAL_AUTORCC_TARGET_NAME`. + +By default ``CMAKE_GLOBAL_AUTORCC_TARGET`` is unset. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME.rst b/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME.rst new file mode 100644 index 0000000..742425f --- /dev/null +++ b/Help/variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME.rst @@ -0,0 +1,15 @@ +CMAKE_GLOBAL_AUTORCC_TARGET_NAME +-------------------------------- + +.. versionadded:: 3.14 + +Change the name of the global ``autorcc`` target. + +When :variable:`CMAKE_GLOBAL_AUTORCC_TARGET` is enabled, a global custom target +named ``autorcc`` is created. ``CMAKE_GLOBAL_AUTORCC_TARGET_NAME`` +allows to set a different name for that target. + +By default ``CMAKE_GLOBAL_AUTORCC_TARGET_NAME`` is unset. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/variable/CMAKE_GNUtoMS.rst b/Help/variable/CMAKE_GNUtoMS.rst new file mode 100644 index 0000000..9c0f59e --- /dev/null +++ b/Help/variable/CMAKE_GNUtoMS.rst @@ -0,0 +1,8 @@ +CMAKE_GNUtoMS +------------- + +Convert GNU import libraries (``.dll.a``) to MS format (``.lib``). + +This variable is used to initialize the :prop_tgt:`GNUtoMS` property on +targets when they are created. See that target property for additional +information. diff --git a/Help/variable/CMAKE_HIP_ARCHITECTURES.rst b/Help/variable/CMAKE_HIP_ARCHITECTURES.rst new file mode 100644 index 0000000..bcc6b35 --- /dev/null +++ b/Help/variable/CMAKE_HIP_ARCHITECTURES.rst @@ -0,0 +1,12 @@ +CMAKE_HIP_ARCHITECTURES +----------------------- + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_ARCHITECTURES` property of targets. + +This is initialized to the architectures reported by ``rocm_agent_enumerator``, +if available, and otherwise to the default chosen by the compiler. + +This variable is used to initialize the :prop_tgt:`HIP_ARCHITECTURES` property +on all targets. See the target property for additional information. diff --git a/Help/variable/CMAKE_HIP_EXTENSIONS.rst b/Help/variable/CMAKE_HIP_EXTENSIONS.rst new file mode 100644 index 0000000..13987dc --- /dev/null +++ b/Help/variable/CMAKE_HIP_EXTENSIONS.rst @@ -0,0 +1,10 @@ +CMAKE_HIP_EXTENSIONS +-------------------- + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_EXTENSIONS` target property if set when a +target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_HIP_STANDARD.rst b/Help/variable/CMAKE_HIP_STANDARD.rst new file mode 100644 index 0000000..5f15145 --- /dev/null +++ b/Help/variable/CMAKE_HIP_STANDARD.rst @@ -0,0 +1,10 @@ +CMAKE_HIP_STANDARD +------------------ + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_STANDARD` target property if set when a target +is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_HIP_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_HIP_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..5d35e4e --- /dev/null +++ b/Help/variable/CMAKE_HIP_STANDARD_REQUIRED.rst @@ -0,0 +1,10 @@ +CMAKE_HIP_STANDARD_REQUIRED +--------------------------- + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_STANDARD_REQUIRED` target property if set when +a target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_HOME_DIRECTORY.rst b/Help/variable/CMAKE_HOME_DIRECTORY.rst new file mode 100644 index 0000000..b03d956 --- /dev/null +++ b/Help/variable/CMAKE_HOME_DIRECTORY.rst @@ -0,0 +1,9 @@ +CMAKE_HOME_DIRECTORY +-------------------- + +Path to top of source tree. Same as :variable:`CMAKE_SOURCE_DIR`. + +This is an internal cache entry used to locate the source directory +when loading a ``CMakeCache.txt`` from a build tree. It should not +be used in project code. The variable :variable:`CMAKE_SOURCE_DIR` +has the same value and should be preferred. diff --git a/Help/variable/CMAKE_HOST_APPLE.rst b/Help/variable/CMAKE_HOST_APPLE.rst new file mode 100644 index 0000000..9c205ec --- /dev/null +++ b/Help/variable/CMAKE_HOST_APPLE.rst @@ -0,0 +1,6 @@ +CMAKE_HOST_APPLE +---------------- + +``True`` for Apple macOS operating systems. + +Set to ``true`` when the host system is Apple macOS. diff --git a/Help/variable/CMAKE_HOST_BSD.rst b/Help/variable/CMAKE_HOST_BSD.rst new file mode 100644 index 0000000..d3554f9 --- /dev/null +++ b/Help/variable/CMAKE_HOST_BSD.rst @@ -0,0 +1,7 @@ +CMAKE_HOST_BSD +-------------- + +.. versionadded:: 3.25 + +Set to a string value when the host system is BSD. This value can be one of +the following: DragonFlyBSD, FreeBSD, OpenBSD, or NetBSD. diff --git a/Help/variable/CMAKE_HOST_LINUX.rst b/Help/variable/CMAKE_HOST_LINUX.rst new file mode 100644 index 0000000..e2361bd --- /dev/null +++ b/Help/variable/CMAKE_HOST_LINUX.rst @@ -0,0 +1,6 @@ +CMAKE_HOST_LINUX +---------------- + +.. versionadded:: 3.25 + +Set to true when the host system is Linux. diff --git a/Help/variable/CMAKE_HOST_SOLARIS.rst b/Help/variable/CMAKE_HOST_SOLARIS.rst new file mode 100644 index 0000000..7054acd --- /dev/null +++ b/Help/variable/CMAKE_HOST_SOLARIS.rst @@ -0,0 +1,8 @@ +CMAKE_HOST_SOLARIS +------------------ + +.. versionadded:: 3.6 + +``True`` for Oracle Solaris operating systems. + +Set to ``true`` when the host system is Oracle Solaris. diff --git a/Help/variable/CMAKE_HOST_SYSTEM.rst b/Help/variable/CMAKE_HOST_SYSTEM.rst new file mode 100644 index 0000000..12d11d1 --- /dev/null +++ b/Help/variable/CMAKE_HOST_SYSTEM.rst @@ -0,0 +1,10 @@ +CMAKE_HOST_SYSTEM +----------------- + +Composite Name of OS CMake is being run on. + +This variable is the composite of :variable:`CMAKE_HOST_SYSTEM_NAME` and +:variable:`CMAKE_HOST_SYSTEM_VERSION`, e.g. +``${CMAKE_HOST_SYSTEM_NAME}-${CMAKE_HOST_SYSTEM_VERSION}``. If +:variable:`CMAKE_HOST_SYSTEM_VERSION` is not set, then this variable is +the same as :variable:`CMAKE_HOST_SYSTEM_NAME`. diff --git a/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst b/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst new file mode 100644 index 0000000..e892677 --- /dev/null +++ b/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst @@ -0,0 +1,8 @@ +CMAKE_HOST_SYSTEM_NAME +---------------------- + +Name of the OS CMake is running on. + +On systems that have the uname command, this variable is set to the +output of ``uname -s``. ``Linux``, ``Windows``, and ``Darwin`` for macOS +are the values found on the big three operating systems. diff --git a/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst b/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst new file mode 100644 index 0000000..c305779 --- /dev/null +++ b/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst @@ -0,0 +1,42 @@ +CMAKE_HOST_SYSTEM_PROCESSOR +--------------------------- + +The name of the CPU CMake is running on. + +Windows Platforms +^^^^^^^^^^^^^^^^^ + +On Windows, this variable is set to the value of the environment variable +``PROCESSOR_ARCHITECTURE``. + +Unix Platforms +^^^^^^^^^^^^^^ + +On systems that support ``uname``, this variable is set to the output of: + +- ``uname -m`` on GNU, Linux, Cygwin, Android, or +- ``arch`` on OpenBSD, or +- on other systems, + + * ``uname -p`` if its exit code is nonzero, or + * ``uname -m`` otherwise. + +macOS Platforms +^^^^^^^^^^^^^^^ + +The value of ``uname -m`` is used by default. + +On Apple Silicon hosts, the architecture printed by ``uname -m`` may vary +based on CMake's own architecture and that of the invoking process tree. + +.. versionadded:: 3.19.2 + + On Apple Silicon hosts: + + * The :variable:`CMAKE_APPLE_SILICON_PROCESSOR` variable or + the :envvar:`CMAKE_APPLE_SILICON_PROCESSOR` environment variable + may be set to specify the host architecture explicitly. + + * If :variable:`CMAKE_OSX_ARCHITECTURES` is not set, CMake adds explicit + flags to tell the compiler to build for the host architecture so the + toolchain does not have to guess based on the process tree's architecture. diff --git a/Help/variable/CMAKE_HOST_SYSTEM_VERSION.rst b/Help/variable/CMAKE_HOST_SYSTEM_VERSION.rst new file mode 100644 index 0000000..ed23070 --- /dev/null +++ b/Help/variable/CMAKE_HOST_SYSTEM_VERSION.rst @@ -0,0 +1,8 @@ +CMAKE_HOST_SYSTEM_VERSION +------------------------- + +The OS version CMake is running on. + +A numeric version string for the system. On systems that support +``uname``, this variable is set to the output of ``uname -r``. On other +systems this is set to major-minor version numbers. diff --git a/Help/variable/CMAKE_HOST_UNIX.rst b/Help/variable/CMAKE_HOST_UNIX.rst new file mode 100644 index 0000000..817a957 --- /dev/null +++ b/Help/variable/CMAKE_HOST_UNIX.rst @@ -0,0 +1,7 @@ +CMAKE_HOST_UNIX +--------------- + +``True`` for UNIX and UNIX like operating systems. + +Set to ``true`` when the host system is UNIX or UNIX like (i.e. APPLE and +CYGWIN). diff --git a/Help/variable/CMAKE_HOST_WIN32.rst b/Help/variable/CMAKE_HOST_WIN32.rst new file mode 100644 index 0000000..876b34c --- /dev/null +++ b/Help/variable/CMAKE_HOST_WIN32.rst @@ -0,0 +1,6 @@ +CMAKE_HOST_WIN32 +---------------- + +``True`` if the host system is running Windows, including Windows 64-bit and MSYS. + +Set to ``false`` on Cygwin. diff --git a/Help/variable/CMAKE_IGNORE_PATH.rst b/Help/variable/CMAKE_IGNORE_PATH.rst new file mode 100644 index 0000000..4b2bd8a --- /dev/null +++ b/Help/variable/CMAKE_IGNORE_PATH.rst @@ -0,0 +1,18 @@ +CMAKE_IGNORE_PATH +----------------- + +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_IGNORE_PATH`` +.. |CMAKE_IGNORE_PREFIX_VAR| replace:: :variable:`CMAKE_IGNORE_PREFIX_PATH` + +.. include:: IGNORE_SEARCH_PATH.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_NONSYSTEM.txt + +See also the following variables: + +- :variable:`CMAKE_IGNORE_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_IGNORE_PATH` +- :variable:`CMAKE_PREFIX_PATH` +- :variable:`CMAKE_LIBRARY_PATH` +- :variable:`CMAKE_INCLUDE_PATH` +- :variable:`CMAKE_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst b/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst new file mode 100644 index 0000000..b81cc57 --- /dev/null +++ b/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst @@ -0,0 +1,20 @@ +CMAKE_IGNORE_PREFIX_PATH +------------------------ + +.. versionadded:: 3.23 + +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_IGNORE_PREFIX_PATH`` +.. |CMAKE_IGNORE_NONPREFIX_VAR| replace:: :variable:`CMAKE_IGNORE_PATH` + +.. include:: IGNORE_SEARCH_PREFIX.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_NONSYSTEM.txt + +See also the following variables: + +- :variable:`CMAKE_IGNORE_PATH` +- :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` +- :variable:`CMAKE_PREFIX_PATH` +- :variable:`CMAKE_LIBRARY_PATH` +- :variable:`CMAKE_INCLUDE_PATH` +- :variable:`CMAKE_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_IMPORT_LIBRARY_PREFIX.rst b/Help/variable/CMAKE_IMPORT_LIBRARY_PREFIX.rst new file mode 100644 index 0000000..1561a1d --- /dev/null +++ b/Help/variable/CMAKE_IMPORT_LIBRARY_PREFIX.rst @@ -0,0 +1,9 @@ +CMAKE_IMPORT_LIBRARY_PREFIX +--------------------------- + +The prefix for import libraries that you link to. + +The prefix to use for the name of an import library if used on this +platform. + +``CMAKE_IMPORT_LIBRARY_PREFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_IMPORT_LIBRARY_SUFFIX.rst b/Help/variable/CMAKE_IMPORT_LIBRARY_SUFFIX.rst new file mode 100644 index 0000000..11aeab7 --- /dev/null +++ b/Help/variable/CMAKE_IMPORT_LIBRARY_SUFFIX.rst @@ -0,0 +1,9 @@ +CMAKE_IMPORT_LIBRARY_SUFFIX +--------------------------- + +The suffix for import libraries that you link to. + +The suffix to use for the end of an import library filename if used on +this platform. + +``CMAKE_IMPORT_LIBRARY_SUFFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst new file mode 100644 index 0000000..98d99eb --- /dev/null +++ b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst @@ -0,0 +1,13 @@ +CMAKE_INCLUDE_CURRENT_DIR +------------------------- + +Automatically add the current source and build directories to the include path. + +If this variable is enabled, CMake automatically adds +:variable:`CMAKE_CURRENT_SOURCE_DIR` and :variable:`CMAKE_CURRENT_BINARY_DIR` +to the include path for each directory. These additional include +directories do not propagate down to subdirectories. This is useful +mainly for out-of-source builds, where files generated into the build +tree are included by files located in the source tree. + +By default ``CMAKE_INCLUDE_CURRENT_DIR`` is ``OFF``. diff --git a/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst new file mode 100644 index 0000000..697682b --- /dev/null +++ b/Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst @@ -0,0 +1,12 @@ +CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE +-------------------------------------- + +Automatically add the current source and build directories to the +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property. + +If this variable is enabled, CMake automatically adds for each shared +library target, static library target, module target and executable +target, :variable:`CMAKE_CURRENT_SOURCE_DIR` and +:variable:`CMAKE_CURRENT_BINARY_DIR` to +the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property. By default +``CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE`` is ``OFF``. diff --git a/Help/variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE.rst b/Help/variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE.rst new file mode 100644 index 0000000..e0f2a2e --- /dev/null +++ b/Help/variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE.rst @@ -0,0 +1,9 @@ +CMAKE_INCLUDE_DIRECTORIES_BEFORE +-------------------------------- + +Whether to append or prepend directories by default in +:command:`include_directories`. + +This variable affects the default behavior of the :command:`include_directories` +command. Setting this variable to ``ON`` is equivalent to using the ``BEFORE`` +option in all uses of that command. diff --git a/Help/variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE.rst b/Help/variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE.rst new file mode 100644 index 0000000..37d0a3d --- /dev/null +++ b/Help/variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE.rst @@ -0,0 +1,8 @@ +CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE +---------------------------------------- + +Whether to force prepending of project include directories. + +This variable affects the order of include directories generated in compiler +command lines. If set to ``ON``, it causes the :variable:`CMAKE_SOURCE_DIR` +and the :variable:`CMAKE_BINARY_DIR` to appear first. diff --git a/Help/variable/CMAKE_INCLUDE_PATH.rst b/Help/variable/CMAKE_INCLUDE_PATH.rst new file mode 100644 index 0000000..4918e99 --- /dev/null +++ b/Help/variable/CMAKE_INCLUDE_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_INCLUDE_PATH +------------------ + +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path +for the :command:`find_file` and :command:`find_path` commands. By default it +is empty, it is intended to be set by the project. See also +:variable:`CMAKE_SYSTEM_INCLUDE_PATH` and :variable:`CMAKE_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME.rst b/Help/variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME.rst new file mode 100644 index 0000000..57160f1 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME.rst @@ -0,0 +1,9 @@ +CMAKE_INSTALL_DEFAULT_COMPONENT_NAME +------------------------------------ + +Default component used in :command:`install` commands. + +If an :command:`install` command is used without the ``COMPONENT`` argument, +these files will be grouped into a default component. The name of this +default install component will be taken from this variable. It +defaults to ``Unspecified``. diff --git a/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst b/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst new file mode 100644 index 0000000..f864c20 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst @@ -0,0 +1,31 @@ +CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS +------------------------------------------- + +.. versionadded:: 3.11 + +Default permissions for directories created implicitly during installation +of files by :command:`install` and :command:`file(INSTALL)`. + +If ``make install`` is invoked and directories are implicitly created they +get permissions set by ``CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`` +variable or platform specific default permissions if the variable is not set. + +Implicitly created directories are created if they are not explicitly installed +by :command:`install` command but are needed to install a file on a certain +path. Example of such locations are directories created due to the setting of +:variable:`CMAKE_INSTALL_PREFIX`. + +Expected content of the ``CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`` +variable is a list of permissions that can be used by :command:`install` command +`PERMISSIONS` section. + +Example usage: + +:: + + set(CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS + OWNER_READ + OWNER_WRITE + OWNER_EXECUTE + GROUP_READ + ) diff --git a/Help/variable/CMAKE_INSTALL_MESSAGE.rst b/Help/variable/CMAKE_INSTALL_MESSAGE.rst new file mode 100644 index 0000000..4f39cfe --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_MESSAGE.rst @@ -0,0 +1,32 @@ +CMAKE_INSTALL_MESSAGE +--------------------- + +.. versionadded:: 3.1 + +Specify verbosity of installation script code generated by the +:command:`install` command (using the :command:`file(INSTALL)` command). +For paths that are newly installed or updated, installation +may print lines like:: + + -- Installing: /some/destination/path + +For paths that are already up to date, installation may print +lines like:: + + -- Up-to-date: /some/destination/path + +The ``CMAKE_INSTALL_MESSAGE`` variable may be set to control +which messages are printed: + +``ALWAYS`` + Print both ``Installing`` and ``Up-to-date`` messages. + +``LAZY`` + Print ``Installing`` but not ``Up-to-date`` messages. + +``NEVER`` + Print neither ``Installing`` nor ``Up-to-date`` messages. + +Other values have undefined behavior and may not be diagnosed. + +If this variable is not set, the default behavior is ``ALWAYS``. diff --git a/Help/variable/CMAKE_INSTALL_NAME_DIR.rst b/Help/variable/CMAKE_INSTALL_NAME_DIR.rst new file mode 100644 index 0000000..b07d44f --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_NAME_DIR.rst @@ -0,0 +1,8 @@ +CMAKE_INSTALL_NAME_DIR +---------------------- + +Directory name for installed targets on Apple platforms. + +``CMAKE_INSTALL_NAME_DIR`` is used to initialize the +:prop_tgt:`INSTALL_NAME_DIR` property on all targets. See that target +property for more information. diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst new file mode 100644 index 0000000..c76727e --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst @@ -0,0 +1,36 @@ +CMAKE_INSTALL_PREFIX +-------------------- + +Install directory used by :command:`install`. + +If ``make install`` is invoked or ``INSTALL`` is built, this directory is +prepended onto all install directories. This variable defaults to +``/usr/local`` on UNIX and ``c:/Program Files/${PROJECT_NAME}`` on Windows. +See :variable:`CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT` for how a +project might choose its own default. + +On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the +whole installation to a staging area. See the :envvar:`DESTDIR` environment +variable for more information. + +The installation prefix is also added to :variable:`CMAKE_SYSTEM_PREFIX_PATH` +so that :command:`find_package`, :command:`find_program`, +:command:`find_library`, :command:`find_path`, and :command:`find_file` +will search the prefix for other software. This behavior can be disabled by +setting the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` to ``TRUE`` before the +first :command:`project` invocation. + +.. note:: + + Use the :module:`GNUInstallDirs` module to provide GNU-style + options for the layout of directories within the installation. + +The ``CMAKE_INSTALL_PREFIX`` may be defined when configuring a build tree +to set its installation prefix. Or, when using the :manual:`cmake(1)` +command-line tool's :option:`--install <cmake --install>` mode, one may specify +a different prefix using the :option:`--prefix <cmake--install --prefix>` +option: + +.. code-block:: shell + + cmake --install . --prefix /my/install/prefix diff --git a/Help/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT.rst b/Help/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT.rst new file mode 100644 index 0000000..93cc319 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT.rst @@ -0,0 +1,16 @@ +CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT +------------------------------------------- + +.. versionadded:: 3.7.1 + +CMake sets this variable to a ``TRUE`` value when the +:variable:`CMAKE_INSTALL_PREFIX` has just been initialized to +its default value, typically on the first run of CMake within +a new build tree. This can be used by project code to change +the default without overriding a user-provided value: + +.. code-block:: cmake + + if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT) + set(CMAKE_INSTALL_PREFIX "/my/default" CACHE PATH "..." FORCE) + endif() diff --git a/Help/variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH.rst b/Help/variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH.rst new file mode 100644 index 0000000..c86e433 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH.rst @@ -0,0 +1,11 @@ +CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH +-------------------------------------- + +.. versionadded:: 3.16 + +Sets the default for whether toolchain-defined rpaths should be removed during +installation. + +``CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH`` is a boolean that provides the +default value for the :prop_tgt:`INSTALL_REMOVE_ENVIRONMENT_RPATH` property +of all subsequently created targets. diff --git a/Help/variable/CMAKE_INSTALL_RPATH.rst b/Help/variable/CMAKE_INSTALL_RPATH.rst new file mode 100644 index 0000000..813d1e0 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_RPATH.rst @@ -0,0 +1,8 @@ +CMAKE_INSTALL_RPATH +------------------- + +The rpath to use for installed targets. + +A semicolon-separated list specifying the rpath to use in installed +targets (for platforms that support it). This is used to initialize +the target property :prop_tgt:`INSTALL_RPATH` for all targets. diff --git a/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst b/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst new file mode 100644 index 0000000..34524d1 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst @@ -0,0 +1,13 @@ +CMAKE_INSTALL_RPATH_USE_LINK_PATH +--------------------------------- + +Add paths to linker search and installed rpath. + +``CMAKE_INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``True`` +will append to the runtime search path (rpath) of installed binaries +any directories outside the project that are in the linker search path or +contain linked library files. The directories are appended after the +value of the :prop_tgt:`INSTALL_RPATH` target property. + +This variable is used to initialize the target property +:prop_tgt:`INSTALL_RPATH_USE_LINK_PATH` for all targets. diff --git a/Help/variable/CMAKE_INTERNAL_PLATFORM_ABI.rst b/Help/variable/CMAKE_INTERNAL_PLATFORM_ABI.rst new file mode 100644 index 0000000..9693bf6 --- /dev/null +++ b/Help/variable/CMAKE_INTERNAL_PLATFORM_ABI.rst @@ -0,0 +1,6 @@ +CMAKE_INTERNAL_PLATFORM_ABI +--------------------------- + +An internal variable subject to change. + +This is used in determining the compiler ABI and is subject to change. diff --git a/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst new file mode 100644 index 0000000..cf7da76 --- /dev/null +++ b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst @@ -0,0 +1,10 @@ +CMAKE_INTERPROCEDURAL_OPTIMIZATION +---------------------------------- + +.. versionadded:: 3.9 + +Default value for :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` of targets. + +This variable is used to initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst new file mode 100644 index 0000000..5b3ee77 --- /dev/null +++ b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst @@ -0,0 +1,10 @@ +CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG> +------------------------------------------- + +.. versionadded:: 3.9 + +Default value for :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_<CONFIG>` of targets. + +This variable is used to initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_<CONFIG>` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_IOS_INSTALL_COMBINED.rst b/Help/variable/CMAKE_IOS_INSTALL_COMBINED.rst new file mode 100644 index 0000000..cd7fd8d --- /dev/null +++ b/Help/variable/CMAKE_IOS_INSTALL_COMBINED.rst @@ -0,0 +1,10 @@ +CMAKE_IOS_INSTALL_COMBINED +-------------------------- + +.. versionadded:: 3.5 + +Default value for :prop_tgt:`IOS_INSTALL_COMBINED` of targets. + +This variable is used to initialize the :prop_tgt:`IOS_INSTALL_COMBINED` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_ISPC_HEADER_DIRECTORY.rst b/Help/variable/CMAKE_ISPC_HEADER_DIRECTORY.rst new file mode 100644 index 0000000..a7c9cf6 --- /dev/null +++ b/Help/variable/CMAKE_ISPC_HEADER_DIRECTORY.rst @@ -0,0 +1,10 @@ +CMAKE_ISPC_HEADER_DIRECTORY +---------------------------- + +.. versionadded:: 3.19 + +ISPC generated header output directory. + +This variable is used to initialize the :prop_tgt:`ISPC_HEADER_DIRECTORY` +property on all the targets. See the target property for additional +information. diff --git a/Help/variable/CMAKE_ISPC_HEADER_SUFFIX.rst b/Help/variable/CMAKE_ISPC_HEADER_SUFFIX.rst new file mode 100644 index 0000000..c9fb709 --- /dev/null +++ b/Help/variable/CMAKE_ISPC_HEADER_SUFFIX.rst @@ -0,0 +1,10 @@ +CMAKE_ISPC_HEADER_SUFFIX +------------------------ + +.. versionadded:: 3.19.2 + +Output suffix to be used for ISPC generated headers. + +This variable is used to initialize the :prop_tgt:`ISPC_HEADER_SUFFIX` +property on all the targets. See the target property for additional +information. diff --git a/Help/variable/CMAKE_ISPC_INSTRUCTION_SETS.rst b/Help/variable/CMAKE_ISPC_INSTRUCTION_SETS.rst new file mode 100644 index 0000000..8a6005e --- /dev/null +++ b/Help/variable/CMAKE_ISPC_INSTRUCTION_SETS.rst @@ -0,0 +1,9 @@ +CMAKE_ISPC_INSTRUCTION_SETS +--------------------------- + +.. versionadded:: 3.19 + +Default value for :prop_tgt:`ISPC_INSTRUCTION_SETS` property of targets. + +This variable is used to initialize the :prop_tgt:`ISPC_INSTRUCTION_SETS` property +on all targets. See the target property for additional information. diff --git a/Help/variable/CMAKE_JOB_POOLS.rst b/Help/variable/CMAKE_JOB_POOLS.rst new file mode 100644 index 0000000..43d3c84 --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOLS.rst @@ -0,0 +1,8 @@ +CMAKE_JOB_POOLS +--------------- + +.. versionadded:: 3.11 + +If the :prop_gbl:`JOB_POOLS` global property is not set, the value +of this variable is used in its place. See :prop_gbl:`JOB_POOLS` +for additional information. diff --git a/Help/variable/CMAKE_JOB_POOL_COMPILE.rst b/Help/variable/CMAKE_JOB_POOL_COMPILE.rst new file mode 100644 index 0000000..e5c2d9a --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOL_COMPILE.rst @@ -0,0 +1,6 @@ +CMAKE_JOB_POOL_COMPILE +---------------------- + +This variable is used to initialize the :prop_tgt:`JOB_POOL_COMPILE` +property on all the targets. See :prop_tgt:`JOB_POOL_COMPILE` +for additional information. diff --git a/Help/variable/CMAKE_JOB_POOL_LINK.rst b/Help/variable/CMAKE_JOB_POOL_LINK.rst new file mode 100644 index 0000000..eeee6e0 --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOL_LINK.rst @@ -0,0 +1,6 @@ +CMAKE_JOB_POOL_LINK +------------------- + +This variable is used to initialize the :prop_tgt:`JOB_POOL_LINK` +property on all the targets. See :prop_tgt:`JOB_POOL_LINK` +for additional information. diff --git a/Help/variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER.rst b/Help/variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER.rst new file mode 100644 index 0000000..1a6f66a --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER.rst @@ -0,0 +1,8 @@ +CMAKE_JOB_POOL_PRECOMPILE_HEADER +-------------------------------- + +.. versionadded:: 3.17 + +This variable is used to initialize the :prop_tgt:`JOB_POOL_PRECOMPILE_HEADER` +property on all the targets. See :prop_tgt:`JOB_POOL_PRECOMPILE_HEADER` +for additional information. diff --git a/Help/variable/CMAKE_KATE_FILES_MODE.rst b/Help/variable/CMAKE_KATE_FILES_MODE.rst new file mode 100644 index 0000000..195c15d --- /dev/null +++ b/Help/variable/CMAKE_KATE_FILES_MODE.rst @@ -0,0 +1,20 @@ +CMAKE_KATE_FILES_MODE +--------------------- + +.. versionadded:: 3.27 + +This cache variable is used by the Kate project generator and controls +to what mode the ``files`` entry in the project file will be set. See +:manual:`cmake-generators(7)`. + +Possible values are ``AUTO``, ``SVN``, ``GIT``, ``HG``, ``FOSSIL`` and ``LIST``. + +When set to ``LIST``, CMake will put the list of source files known to CMake +in the project file. +When set to ``SVN``, ``GIT``, ``HG`` or ``FOSSIL``, CMake will set +the generated project accordingly to Subversion, git, Mercurial +or Fossil, and Kate will then use the respective command line tool to +retrieve the list of files in the project. +When unset or set to ``AUTO``, CMake will try to detect whether the +source directory is part of a git or svn checkout or not, and put the +respective entry into the project file. diff --git a/Help/variable/CMAKE_KATE_MAKE_ARGUMENTS.rst b/Help/variable/CMAKE_KATE_MAKE_ARGUMENTS.rst new file mode 100644 index 0000000..c830332 --- /dev/null +++ b/Help/variable/CMAKE_KATE_MAKE_ARGUMENTS.rst @@ -0,0 +1,11 @@ +CMAKE_KATE_MAKE_ARGUMENTS +------------------------- + +.. versionadded:: 3.0 + +This cache variable is used by the Kate project generator. See +:manual:`cmake-generators(7)`. + +This variable holds arguments which are used when Kate invokes the make +tool. By default it is initialized to hold flags to enable parallel builds +(using -j typically). diff --git a/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE.rst b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE.rst new file mode 100644 index 0000000..f539277 --- /dev/null +++ b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE.rst @@ -0,0 +1,11 @@ +CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE +-------------------------------------- + +.. versionadded:: 3.7.1 + +When :ref:`Cross Compiling for Android` this variable contains the +toolchain binutils machine name (e.g. ``gcc -dumpmachine``). The +binutils typically have a ``<machine>-`` prefix on their name. + +See also :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX` +and :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX`. diff --git a/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX.rst b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX.rst new file mode 100644 index 0000000..ff072ca --- /dev/null +++ b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX.rst @@ -0,0 +1,14 @@ +CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX +------------------------------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android` this variable contains the absolute +path prefixing the toolchain GNU compiler and its binutils. + +See also :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX` +and :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE`. + +For example, the path to the linker is:: + + ${CMAKE_CXX_ANDROID_TOOLCHAIN_PREFIX}ld${CMAKE_CXX_ANDROID_TOOLCHAIN_SUFFIX} diff --git a/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX.rst b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX.rst new file mode 100644 index 0000000..d595280 --- /dev/null +++ b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX +------------------------------------- + +.. versionadded:: 3.7 + +When :ref:`Cross Compiling for Android` this variable contains the +host platform suffix of the toolchain GNU compiler and its binutils. + +See also :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX` +and :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_MACHINE`. diff --git a/Help/variable/CMAKE_LANG_ARCHIVE_APPEND.rst b/Help/variable/CMAKE_LANG_ARCHIVE_APPEND.rst new file mode 100644 index 0000000..ab4ad71 --- /dev/null +++ b/Help/variable/CMAKE_LANG_ARCHIVE_APPEND.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_ARCHIVE_APPEND +--------------------------- + +Rule variable to append to a static archive. + +This is a rule variable that tells CMake how to append to a static +archive. It is used in place of :variable:`CMAKE_<LANG>_CREATE_STATIC_LIBRARY` +on some platforms in order to support large object counts. See also +:variable:`CMAKE_<LANG>_ARCHIVE_CREATE` and +:variable:`CMAKE_<LANG>_ARCHIVE_FINISH`. diff --git a/Help/variable/CMAKE_LANG_ARCHIVE_CREATE.rst b/Help/variable/CMAKE_LANG_ARCHIVE_CREATE.rst new file mode 100644 index 0000000..fc295af --- /dev/null +++ b/Help/variable/CMAKE_LANG_ARCHIVE_CREATE.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_ARCHIVE_CREATE +--------------------------- + +Rule variable to create a new static archive. + +This is a rule variable that tells CMake how to create a static +archive. It is used in place of :variable:`CMAKE_<LANG>_CREATE_STATIC_LIBRARY` +on some platforms in order to support large object counts. See also +:variable:`CMAKE_<LANG>_ARCHIVE_APPEND` and +:variable:`CMAKE_<LANG>_ARCHIVE_FINISH`. diff --git a/Help/variable/CMAKE_LANG_ARCHIVE_FINISH.rst b/Help/variable/CMAKE_LANG_ARCHIVE_FINISH.rst new file mode 100644 index 0000000..1bb5d65 --- /dev/null +++ b/Help/variable/CMAKE_LANG_ARCHIVE_FINISH.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_ARCHIVE_FINISH +--------------------------- + +Rule variable to finish an existing static archive. + +This is a rule variable that tells CMake how to finish a static +archive. It is used in place of :variable:`CMAKE_<LANG>_CREATE_STATIC_LIBRARY` +on some platforms in order to support large object counts. See also +:variable:`CMAKE_<LANG>_ARCHIVE_CREATE` and +:variable:`CMAKE_<LANG>_ARCHIVE_APPEND`. diff --git a/Help/variable/CMAKE_LANG_BYTE_ORDER.rst b/Help/variable/CMAKE_LANG_BYTE_ORDER.rst new file mode 100644 index 0000000..78f0ae6 --- /dev/null +++ b/Help/variable/CMAKE_LANG_BYTE_ORDER.rst @@ -0,0 +1,20 @@ +CMAKE_<LANG>_BYTE_ORDER +----------------------- + +.. versionadded:: 3.20 + +Byte order of ``<LANG>`` compiler target architecture, if known. +If defined and not empty, the value is one of: + +``BIG_ENDIAN`` + The target architecture is Big Endian. + +``LITTLE_ENDIAN`` + The target architecture is Little Endian. + +This is defined for languages ``C``, ``CXX``, ``OBJC``, ``OBJCXX``, +and ``CUDA``. + +If :variable:`CMAKE_OSX_ARCHITECTURES` specifies multiple architectures, the +value of ``CMAKE_<LANG>_BYTE_ORDER`` is non-empty only if all architectures +share the same byte order. diff --git a/Help/variable/CMAKE_LANG_CLANG_TIDY.rst b/Help/variable/CMAKE_LANG_CLANG_TIDY.rst new file mode 100644 index 0000000..32e27b0 --- /dev/null +++ b/Help/variable/CMAKE_LANG_CLANG_TIDY.rst @@ -0,0 +1,15 @@ +CMAKE_<LANG>_CLANG_TIDY +----------------------- + +.. versionadded:: 3.6 + +Default value for :prop_tgt:`<LANG>_CLANG_TIDY` target property +when ``<LANG>`` is ``C``, ``CXX``, ``OBJC`` or ``OBJCXX``. + +This variable is used to initialize the property on each target as it is +created. For example: + +.. code-block:: cmake + + set(CMAKE_CXX_CLANG_TIDY clang-tidy -checks=-*,readability-*) + add_executable(foo foo.cxx) diff --git a/Help/variable/CMAKE_LANG_CLANG_TIDY_EXPORT_FIXES_DIR.rst b/Help/variable/CMAKE_LANG_CLANG_TIDY_EXPORT_FIXES_DIR.rst new file mode 100644 index 0000000..60b7f40 --- /dev/null +++ b/Help/variable/CMAKE_LANG_CLANG_TIDY_EXPORT_FIXES_DIR.rst @@ -0,0 +1,15 @@ +CMAKE_<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR +---------------------------------------- + +.. versionadded:: 3.26 + +Default value for :prop_tgt:`<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR` target +property when ``<LANG>`` is ``C``, ``CXX``, ``OBJC`` or ``OBJCXX``. + +This variable is used to initialize the property on each target as it is +created. For example: + +.. code-block:: cmake + + set(CMAKE_CXX_CLANG_TIDY_EXPORT_FIXES_DIR clang-tidy-fixes) + add_executable(foo foo.cxx) diff --git a/Help/variable/CMAKE_LANG_COMPILER.rst b/Help/variable/CMAKE_LANG_COMPILER.rst new file mode 100644 index 0000000..db8f4e1 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER.rst @@ -0,0 +1,33 @@ +CMAKE_<LANG>_COMPILER +--------------------- + +The full path to the compiler for ``LANG``. + +This is the command that will be used as the ``<LANG>`` compiler. Once +set, you can not change this variable. + +Usage +^^^^^ + +This variable can be set by the user during the first time a build tree is configured. + +If a non-full path value is supplied then CMake will resolve the full path of +the compiler. + +The variable could be set in a user supplied toolchain file or via +:option:`-D <cmake -D>` on the command line. + +.. note:: + Options that are required to make the compiler work correctly can be included + as items in a list; they can not be changed. + +.. code-block:: cmake + + #set within user supplied toolchain file + set(CMAKE_C_COMPILER /full/path/to/qcc --arg1 --arg2) + +or + +.. code-block:: console + + $ cmake ... -DCMAKE_C_COMPILER='qcc;--arg1;--arg2' diff --git a/Help/variable/CMAKE_LANG_COMPILER_ABI.rst b/Help/variable/CMAKE_LANG_COMPILER_ABI.rst new file mode 100644 index 0000000..be946c0 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_ABI.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_COMPILER_ABI +------------------------- + +An internal variable subject to change. + +This is used in determining the compiler ABI and is subject to change. diff --git a/Help/variable/CMAKE_LANG_COMPILER_AR.rst b/Help/variable/CMAKE_LANG_COMPILER_AR.rst new file mode 100644 index 0000000..74f2758 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_AR.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_COMPILER_AR +------------------------ + +.. versionadded:: 3.9 + +A wrapper around ``ar`` adding the appropriate ``--plugin`` option for the +compiler. + +See also :variable:`CMAKE_AR`. diff --git a/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst new file mode 100644 index 0000000..8057566 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID +------------------------------------- + +.. versionadded:: 3.10 + +An internal variable subject to change. + +This is used to identify the variant of a compiler based on its target +architecture. For some compilers this is needed to determine the correct +usage. diff --git a/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst new file mode 100644 index 0000000..cbe3544 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN +---------------------------------------- + +The external toolchain for cross-compiling, if supported. + +Some compiler toolchains do not ship their own auxiliary utilities such as +archivers and linkers. The compiler driver may support a command-line argument +to specify the location of such tools. +``CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN`` may be set to a path to +the external toolchain and will be passed to the compiler driver if supported. + +This variable may only be set in a toolchain file specified by +the :variable:`CMAKE_TOOLCHAIN_FILE` variable. diff --git a/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst b/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst new file mode 100644 index 0000000..a414463 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst @@ -0,0 +1,22 @@ +CMAKE_<LANG>_COMPILER_FRONTEND_VARIANT +-------------------------------------- + +.. versionadded:: 3.14 + +Identification string of the compiler frontend variant. + +Some compilers have multiple, different frontends for accepting command +line options. (For example ``Clang`` originally only had a frontend +compatible with the ``GNU`` compiler but since its port to Windows +(``Clang-Cl``) it now also supports a frontend compatible with ``MSVC``.) +When CMake detects such a compiler it sets this +variable to what would have been the :variable:`CMAKE_<LANG>_COMPILER_ID` for +the compiler whose frontend it resembles. + +.. note:: + In other words, this variable describes what command line options + and language extensions the compiler frontend expects. + +.. versionchanged:: 3.26 + This variable is set for ``GNU``, ``MSVC``, and ``AppleClang`` + compilers that have only one frontend variant. diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst new file mode 100644 index 0000000..3b27fc3 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -0,0 +1,68 @@ +CMAKE_<LANG>_COMPILER_ID +------------------------ + +Compiler identification string. + +A short string unique to the compiler vendor. Possible values +include: + +=============================== =============================================== +Value Name +=============================== =============================================== +``Absoft`` `Absoft Fortran`_ +``ADSP`` Analog VisualDSP++ +``AppleClang`` Apple Clang +``ARMCC`` ARM Compiler +``ARMClang`` ARM Compiler based on Clang +``Bruce`` Bruce C Compiler +``CCur`` Concurrent Fortran +``Clang`` `LLVM Clang`_ +``Cray`` Cray Compiler +``Embarcadero``, ``Borland`` `Embarcadero`_ +``Flang`` `Classic Flang Fortran Compiler`_ +``LLVMFlang`` `LLVM Flang Fortran Compiler`_ +``Fujitsu`` Fujitsu HPC compiler (Trad mode) +``FujitsuClang`` Fujitsu HPC compiler (Clang mode) +``G95`` `G95 Fortran`_ +``GNU`` `GNU Compiler Collection`_ +``GHS`` `Green Hills Software`_ +``HP`` Hewlett-Packard Compiler +``IAR`` IAR Systems +``Intel`` Intel Classic Compiler +``IntelLLVM`` `Intel LLVM-Based Compiler`_ +``LCC`` MCST Elbrus C/C++/Fortran Compiler +``MSVC`` `Microsoft Visual Studio`_ +``NVHPC`` `NVIDIA HPC Compiler`_ +``NVIDIA`` `NVIDIA CUDA Compiler`_ +``OpenWatcom`` `Open Watcom`_ +``PGI`` The Portland Group +``PathScale`` PathScale +``SDCC`` `Small Device C Compiler`_ +``SunPro`` Oracle Solaris Studio +``Tasking`` `Tasking Compiler Toolsets`_ +``TI`` Texas Instruments +``TinyCC`` `Tiny C Compiler`_ +``XL``, ``VisualAge``, ``zOS`` IBM XL +``XLClang`` IBM Clang-based XL +``IBMClang`` IBM LLVM-based Compiler +=============================== =============================================== + +This variable is not guaranteed to be defined for all compilers or +languages. + +.. _Absoft Fortran: https://www.absoft.com +.. _LLVM Clang: https://clang.llvm.org +.. _Embarcadero: https://www.embarcadero.com +.. _Classic Flang Fortran Compiler: https://github.com/flang-compiler/flang +.. _LLVM Flang Fortran Compiler: https://github.com/llvm/llvm-project/tree/main/flang +.. _G95 Fortran: https://g95.sourceforge.net +.. _GNU Compiler Collection: https://gcc.gnu.org +.. _Green Hills Software: https://www.ghs.com/products/compiler.html +.. _Intel LLVM-Based Compiler: https://www.intel.com/content/www/us/en/developer/tools/oneapi/overview.html +.. _Microsoft Visual Studio: https://visualstudio.microsoft.com +.. _NVIDIA HPC Compiler: https://developer.nvidia.com/hpc-compilers +.. _NVIDIA CUDA Compiler: https://developer.nvidia.com/cuda-llvm-compiler +.. _Open Watcom: https://open-watcom.github.io +.. _Small Device C Compiler: https://sdcc.sourceforge.net +.. _Tiny C Compiler: https://bellard.org/tcc +.. _Tasking Compiler Toolsets: https://www.tasking.com diff --git a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst new file mode 100644 index 0000000..f16e594 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -0,0 +1,12 @@ +CMAKE_<LANG>_COMPILER_LAUNCHER +------------------------------ + +.. versionadded:: 3.4 + +Default value for :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property. +This variable is used to initialize the property on each target as it is +created. This is done only when ``<LANG>`` is ``C``, ``CXX``, ``Fortran``, +``HIP``, ``ISPC``, ``OBJC``, ``OBJCXX``, or ``CUDA``. + +This variable is initialized to the :envvar:`CMAKE_<LANG>_COMPILER_LAUNCHER` +environment variable if it is set. diff --git a/Help/variable/CMAKE_LANG_COMPILER_LOADED.rst b/Help/variable/CMAKE_LANG_COMPILER_LOADED.rst new file mode 100644 index 0000000..9308878 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_LOADED.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_COMPILER_LOADED +---------------------------- + +Defined to true if the language is enabled. + +When language ``<LANG>`` is enabled by :command:`project` or +:command:`enable_language` this variable is defined to ``1``. diff --git a/Help/variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND.rst b/Help/variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND.rst new file mode 100644 index 0000000..935329a --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND +---------------------------------------- + +.. versionadded:: 3.10 + +Command that outputs the compiler pre definitions. + +See :prop_tgt:`AUTOMOC` which uses +:variable:`CMAKE_CXX_COMPILER_PREDEFINES_COMMAND <CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND>` +to generate the :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`. diff --git a/Help/variable/CMAKE_LANG_COMPILER_RANLIB.rst b/Help/variable/CMAKE_LANG_COMPILER_RANLIB.rst new file mode 100644 index 0000000..1d10b55 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_RANLIB.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_COMPILER_RANLIB +---------------------------- + +.. versionadded:: 3.9 + +A wrapper around ``ranlib`` adding the appropriate ``--plugin`` option for the +compiler. + +See also :variable:`CMAKE_RANLIB`. diff --git a/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst b/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst new file mode 100644 index 0000000..656c57d --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_TARGET.rst @@ -0,0 +1,11 @@ +CMAKE_<LANG>_COMPILER_TARGET +---------------------------- + +The target for cross-compiling, if supported. + +Some compiler drivers are inherently cross-compilers, such as clang and +QNX qcc. These compiler drivers support a command-line argument to specify +the target to cross-compile for. + +This variable may only be set in a toolchain file specified by +the :variable:`CMAKE_TOOLCHAIN_FILE` variable. diff --git a/Help/variable/CMAKE_LANG_COMPILER_VERSION.rst b/Help/variable/CMAKE_LANG_COMPILER_VERSION.rst new file mode 100644 index 0000000..27b0cad --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_VERSION.rst @@ -0,0 +1,12 @@ +CMAKE_<LANG>_COMPILER_VERSION +----------------------------- + +Compiler version string. + +Compiler version in major[.minor[.patch[.tweak]]] format. This +variable is not guaranteed to be defined for all compilers or +languages. + +For example ``CMAKE_C_COMPILER_VERSION`` and +``CMAKE_CXX_COMPILER_VERSION`` might indicate the respective C and C++ +compiler version. diff --git a/Help/variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL.rst b/Help/variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL.rst new file mode 100644 index 0000000..596a989 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_COMPILER_VERSION_INTERNAL +-------------------------------------- + +.. versionadded:: 3.10 + +An internal variable subject to change. + +This is used to identify the variant of a compiler based on an internal +version number. For some compilers this is needed to determine the +correct usage. diff --git a/Help/variable/CMAKE_LANG_COMPILE_OBJECT.rst b/Help/variable/CMAKE_LANG_COMPILE_OBJECT.rst new file mode 100644 index 0000000..ba59cad --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILE_OBJECT.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_COMPILE_OBJECT +--------------------------- + +Rule variable to compile a single object file. + +This is a rule variable that tells CMake how to compile a single +object file for the language ``<LANG>``. diff --git a/Help/variable/CMAKE_LANG_CPPCHECK.rst b/Help/variable/CMAKE_LANG_CPPCHECK.rst new file mode 100644 index 0000000..5ae5faf --- /dev/null +++ b/Help/variable/CMAKE_LANG_CPPCHECK.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_CPPCHECK +--------------------- + +.. versionadded:: 3.10 + +Default value for :prop_tgt:`<LANG>_CPPCHECK` target property. This variable +is used to initialize the property on each target as it is created. This +is done only when ``<LANG>`` is ``C`` or ``CXX``. diff --git a/Help/variable/CMAKE_LANG_CPPLINT.rst b/Help/variable/CMAKE_LANG_CPPLINT.rst new file mode 100644 index 0000000..ab7b0fc --- /dev/null +++ b/Help/variable/CMAKE_LANG_CPPLINT.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_CPPLINT +-------------------- + +.. versionadded:: 3.8 + +Default value for :prop_tgt:`<LANG>_CPPLINT` target property. This variable +is used to initialize the property on each target as it is created. This +is done only when ``<LANG>`` is ``C`` or ``CXX``. diff --git a/Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY.rst b/Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY.rst new file mode 100644 index 0000000..16fcc03 --- /dev/null +++ b/Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_CREATE_SHARED_LIBRARY +---------------------------------- + +Rule variable to create a shared library. + +This is a rule variable that tells CMake how to create a shared +library for the language ``<LANG>``. This rule variable is a ``;`` delimited +list of commands to run to perform the linking step. diff --git a/Help/variable/CMAKE_LANG_CREATE_SHARED_MODULE.rst b/Help/variable/CMAKE_LANG_CREATE_SHARED_MODULE.rst new file mode 100644 index 0000000..807229d --- /dev/null +++ b/Help/variable/CMAKE_LANG_CREATE_SHARED_MODULE.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_CREATE_SHARED_MODULE +--------------------------------- + +Rule variable to create a shared module. + +This is a rule variable that tells CMake how to create a shared +library for the language ``<LANG>``. This rule variable is a ``;`` delimited +list of commands to run. diff --git a/Help/variable/CMAKE_LANG_CREATE_STATIC_LIBRARY.rst b/Help/variable/CMAKE_LANG_CREATE_STATIC_LIBRARY.rst new file mode 100644 index 0000000..0cff200 --- /dev/null +++ b/Help/variable/CMAKE_LANG_CREATE_STATIC_LIBRARY.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_CREATE_STATIC_LIBRARY +---------------------------------- + +Rule variable to create a static library. + +This is a rule variable that tells CMake how to create a static +library for the language ``<LANG>``. diff --git a/Help/variable/CMAKE_LANG_EXTENSIONS.rst b/Help/variable/CMAKE_LANG_EXTENSIONS.rst new file mode 100644 index 0000000..3a32002 --- /dev/null +++ b/Help/variable/CMAKE_LANG_EXTENSIONS.rst @@ -0,0 +1,20 @@ +CMAKE_<LANG>_EXTENSIONS +----------------------- + +The variations are: + +* :variable:`CMAKE_C_EXTENSIONS` +* :variable:`CMAKE_CXX_EXTENSIONS` +* :variable:`CMAKE_CUDA_EXTENSIONS` +* :variable:`CMAKE_HIP_EXTENSIONS` +* :variable:`CMAKE_OBJC_EXTENSIONS` +* :variable:`CMAKE_OBJCXX_EXTENSIONS` + +Default values for :prop_tgt:`<LANG>_EXTENSIONS` target properties if set when +a target is created. For the compiler's default setting see +:variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`. + +For supported CMake versions see the respective pages. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LANG_EXTENSIONS_DEFAULT.rst b/Help/variable/CMAKE_LANG_EXTENSIONS_DEFAULT.rst new file mode 100644 index 0000000..a66453a --- /dev/null +++ b/Help/variable/CMAKE_LANG_EXTENSIONS_DEFAULT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_EXTENSIONS_DEFAULT +------------------------------- + +.. versionadded:: 3.22 + +Compiler's default extensions mode. Used as the default for the +:prop_tgt:`<LANG>_EXTENSIONS` target property when +:variable:`CMAKE_<LANG>_EXTENSIONS` is not set (see :policy:`CMP0128`). + +This variable is read-only. Modifying it is undefined behavior. diff --git a/Help/variable/CMAKE_LANG_FLAGS.rst b/Help/variable/CMAKE_LANG_FLAGS.rst new file mode 100644 index 0000000..4b39b1d --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS.rst @@ -0,0 +1,33 @@ +CMAKE_<LANG>_FLAGS +------------------ + +Flags for all build types. + +``<LANG>`` flags used regardless of the value of :variable:`CMAKE_BUILD_TYPE`. + +For each language, if this variable is not defined, it is initialized +and stored in the cache using values from environment variables in +combination with CMake's builtin defaults for the toolchain: + +* ``CMAKE_C_FLAGS``: + Initialized by the :envvar:`CFLAGS` environment variable. +* ``CMAKE_CXX_FLAGS``: + Initialized by the :envvar:`CXXFLAGS` environment variable. +* ``CMAKE_CUDA_FLAGS``: + Initialized by the :envvar:`CUDAFLAGS` environment variable. +* ``CMAKE_Fortran_FLAGS``: + Initialized by the :envvar:`FFLAGS` environment variable. +* ``CMAKE_CSharp_FLAGS``: + Initialized by the :envvar:`CSFLAGS` environment variable. +* ``CMAKE_HIP_FLAGS``: + Initialized by the :envvar:`HIPFLAGS` environment variable. +* ``CMAKE_ISPC_FLAGS``: + Initialized by the :envvar:`ISPCFLAGS` environment variable. + +This value is a command-line string fragment. Therefore, multiple options +should be separated by spaces, and options with spaces should be quoted. + +The flags in this variable will be passed to the compiler before those +in the per-configuration :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variant, +and before flags added by the :command:`add_compile_options` or +:command:`target_compile_options` commands. diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst new file mode 100644 index 0000000..f0900fd --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_FLAGS_<CONFIG> +--------------------------- + +Flags for language ``<LANG>`` when building for the ``<CONFIG>`` configuration. + +The flags in this variable will be passed to the compiler after those +in the :variable:`CMAKE_<LANG>_FLAGS` variable, but before flags added +by the :command:`add_compile_options` or :command:`target_compile_options` +commands. diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..17669a2 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,12 @@ +CMAKE_<LANG>_FLAGS_<CONFIG>_INIT +-------------------------------- + +.. versionadded:: 3.11 + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache +entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst b/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst new file mode 100644 index 0000000..6be424a --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_FLAGS_DEBUG +------------------------ + +This variable is the ``Debug`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst new file mode 100644 index 0000000..49c9e99 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_FLAGS_DEBUG_INIT +----------------------------- + +.. versionadded:: 3.7 + +This variable is the ``Debug`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst new file mode 100644 index 0000000..ca13a29 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst @@ -0,0 +1,19 @@ +CMAKE_<LANG>_FLAGS_INIT +----------------------- + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS` cache entry +the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. For example, +the contents of a ``xxxFLAGS`` environment variable will be prepended, +where ``xxx`` will be language-specific but not necessarily the same as +``<LANG>`` (e.g. :envvar:`CXXFLAGS` for ``CXX``, :envvar:`FFLAGS` for +``Fortran``, and so on). +This value is a command-line string fragment. Therefore, multiple options +should be separated by spaces, and options with spaces should be quoted. + +See also the configuration-specific +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst new file mode 100644 index 0000000..634fab9 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_FLAGS_MINSIZEREL +----------------------------- + +This variable is the ``MinSizeRel`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst new file mode 100644 index 0000000..3600909 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT +---------------------------------- + +.. versionadded:: 3.7 + +This variable is the ``MinSizeRel`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst b/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst new file mode 100644 index 0000000..3baeab0 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_FLAGS_RELEASE +-------------------------- + +This variable is the ``Release`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst new file mode 100644 index 0000000..e889852 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_FLAGS_RELEASE_INIT +------------------------------- + +.. versionadded:: 3.7 + +This variable is the ``Release`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst new file mode 100644 index 0000000..67a5073 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_FLAGS_RELWITHDEBINFO +--------------------------------- + +This variable is the ``RelWithDebInfo`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst new file mode 100644 index 0000000..b42caee --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT +-------------------------------------- + +.. versionadded:: 3.7 + +This variable is the ``RelWithDebInfo`` variant of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_IGNORE_EXTENSIONS.rst b/Help/variable/CMAKE_LANG_IGNORE_EXTENSIONS.rst new file mode 100644 index 0000000..3d07e91 --- /dev/null +++ b/Help/variable/CMAKE_LANG_IGNORE_EXTENSIONS.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_IGNORE_EXTENSIONS +------------------------------ + +File extensions that should be ignored by the build. + +This is a list of file extensions that may be part of a project for a +given language but are not compiled. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..e361fd9 --- /dev/null +++ b/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,14 @@ +CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES +----------------------------------------- + +Directories implicitly searched by the compiler for header files. + +CMake does not explicitly specify these directories on compiler +command lines for language ``<LANG>``. This prevents system include +directories from being treated as user include directories on some +compilers, which is important for ``C``, ``CXX``, and ``CUDA`` to +avoid overriding standard library headers. + +This value is not used for ``Fortran`` because it has no standard +library headers and some compilers do not search their implicit +include directories for module ``.mod`` files. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst new file mode 100644 index 0000000..081c4da --- /dev/null +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst @@ -0,0 +1,34 @@ +CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES +-------------------------------------- + +Implicit linker search path detected for language ``<LANG>``. + +Compilers typically pass directories containing language runtime +libraries and default library search paths when they invoke a linker. +These paths are implicit linker search directories for the compiler's +language. For each language enabled by the :command:`project` or +:command:`enable_language` command, CMake automatically detects these +directories and reports the results in this variable. + +When linking to a static library, CMake adds the implicit link directories +from this variable for each language used in the static library (except +the language whose compiler is used to drive linking). In the case of an +imported static library, the :prop_tgt:`IMPORTED_LINK_INTERFACE_LANGUAGES` +target property lists the languages whose implicit link information is +needed. If any of the languages is not enabled, its value for the +``CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES`` variable may instead be provided +by the project. Or, a :variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` +may set the variable to a value known for the specified toolchain. It will +either be overridden when the language is enabled, or used as a fallback. + +Some toolchains read implicit directories from an environment variable such as +``LIBRARY_PATH``. If using such an environment variable, keep its value +consistent when operating in a given build tree because CMake saves the value +detected when first creating a build tree. + +If policy :policy:`CMP0060` is not set to ``NEW``, then when a library in one +of these directories is given by full path to :command:`target_link_libraries` +CMake will generate the ``-l<name>`` form on link lines for historical +purposes. + +See also the :variable:`CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES` variable. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES.rst new file mode 100644 index 0000000..61ccc5a --- /dev/null +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES +------------------------------------------------ + +Implicit linker framework search path detected for language ``<LANG>``. + +These paths are implicit linker framework search directories for the +compiler's language. CMake automatically detects these directories +for each language and reports the results in this variable. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst new file mode 100644 index 0000000..0c25489 --- /dev/null +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst @@ -0,0 +1,24 @@ +CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES +------------------------------------ + +Implicit link libraries and flags detected for language ``<LANG>``. + +Compilers typically pass language runtime library names and other +flags when they invoke a linker. These flags are implicit link +options for the compiler's language. For each language enabled +by the :command:`project` or :command:`enable_language` command, +CMake automatically detects these libraries and flags and reports +the results in this variable. + +When linking to a static library, CMake adds the implicit link libraries and +flags from this variable for each language used in the static library (except +the language whose compiler is used to drive linking). In the case of an +imported static library, the :prop_tgt:`IMPORTED_LINK_INTERFACE_LANGUAGES` +target property lists the languages whose implicit link information is +needed. If any of the languages is not enabled, its value for the +``CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES`` variable may instead be provided +by the project. Or, a :variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` +may set the variable to a value known for the specified toolchain. It will +either be overridden when the language is enabled, or used as a fallback. + +See also the :variable:`CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES` variable. diff --git a/Help/variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE.rst b/Help/variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE.rst new file mode 100644 index 0000000..be6c210 --- /dev/null +++ b/Help/variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE +--------------------------------- + +.. versionadded:: 3.3 + +Default value for :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE` target property. +This variable is used to initialize the property on each target as it is +created. This is done only when ``<LANG>`` is ``C`` or ``CXX``. diff --git a/Help/variable/CMAKE_LANG_LIBRARY_ARCHITECTURE.rst b/Help/variable/CMAKE_LANG_LIBRARY_ARCHITECTURE.rst new file mode 100644 index 0000000..7f888ee --- /dev/null +++ b/Help/variable/CMAKE_LANG_LIBRARY_ARCHITECTURE.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_LIBRARY_ARCHITECTURE +--------------------------------- + +Target architecture library directory name detected for ``<LANG>``. + +If the ``<LANG>`` compiler passes to the linker an architecture-specific +system library search directory such as ``<prefix>/lib/<arch>`` this +variable contains the ``<arch>`` name if/as detected by CMake. diff --git a/Help/variable/CMAKE_LANG_LINKER_LAUNCHER.rst b/Help/variable/CMAKE_LANG_LINKER_LAUNCHER.rst new file mode 100644 index 0000000..b76b939 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_LAUNCHER.rst @@ -0,0 +1,11 @@ +CMAKE_<LANG>_LINKER_LAUNCHER +---------------------------- + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`<LANG>_LINKER_LAUNCHER` target property. This +variable is used to initialize the property on each target as it is created. +This is done only when ``<LANG>`` is ``C``, ``CXX``, ``OBJC``, or ``OBJCXX``. + +This variable is initialized to the :envvar:`CMAKE_<LANG>_LINKER_LAUNCHER` +environment variable if it is set. diff --git a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst new file mode 100644 index 0000000..a4035bd --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_LINKER_PREFERENCE +------------------------------ + +An internal variable subject to change. + +Preference value for linker language selection. + +The "linker language" for executable, shared library, and module +targets is the language whose compiler will invoke the linker. The +:prop_tgt:`LINKER_LANGUAGE` target property sets the language explicitly. +Otherwise, the linker language is that whose linker preference value +is highest among languages compiled and linked into the target. See +also the :variable:`CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES` variable. diff --git a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst new file mode 100644 index 0000000..df33edb --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst @@ -0,0 +1,11 @@ +CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES +----------------------------------------- + +An internal variable subject to change. + +True if :variable:`CMAKE_<LANG>_LINKER_PREFERENCE` propagates across targets. + +This is used when CMake selects a linker language for a target. +Languages compiled directly into the target are always considered. A +language compiled into static libraries linked by the target is +considered if this variable is true. diff --git a/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst new file mode 100644 index 0000000..471c351 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst @@ -0,0 +1,41 @@ +CMAKE_<LANG>_LINKER_WRAPPER_FLAG +-------------------------------- + +.. versionadded:: 3.13 + +Defines the syntax of compiler driver option to pass options to the linker +tool. It will be used to translate the ``LINKER:`` prefix in the link options +(see :command:`add_link_options` and :command:`target_link_options`). + +This variable holds a :ref:`semicolon-separated list <CMake Language Lists>` of tokens. +If a space (i.e. " ") is specified as last token, flag and ``LINKER:`` +arguments will be specified as separate arguments to the compiler driver. +The :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variable can be specified +to manage concatenation of arguments. + +For example, for ``Clang`` we have: + +.. code-block:: cmake + + set (CMAKE_C_LINKER_WRAPPER_FLAG "-Xlinker" " ") + +Specifying ``"LINKER:-z,defs"`` will be transformed in +``-Xlinker -z -Xlinker defs``. + +For ``GNU GCC``: + +.. code-block:: cmake + + set (CMAKE_C_LINKER_WRAPPER_FLAG "-Wl,") + set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",") + +Specifying ``"LINKER:-z,defs"`` will be transformed in ``-Wl,-z,defs``. + +And for ``SunPro``: + +.. code-block:: cmake + + set (CMAKE_C_LINKER_WRAPPER_FLAG "-Qoption" "ld" " ") + set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",") + +Specifying ``"LINKER:-z,defs"`` will be transformed in ``-Qoption ld -z,defs``. diff --git a/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP.rst b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP.rst new file mode 100644 index 0000000..a3895af --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP.rst @@ -0,0 +1,11 @@ +CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP +------------------------------------ + +.. versionadded:: 3.13 + +This variable is used with :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` +variable to format ``LINKER:`` prefix in the link options +(see :command:`add_link_options` and :command:`target_link_options`). + +When specified, arguments of the ``LINKER:`` prefix will be concatenated using +this value as separator. diff --git a/Help/variable/CMAKE_LANG_LINK_EXECUTABLE.rst b/Help/variable/CMAKE_LANG_LINK_EXECUTABLE.rst new file mode 100644 index 0000000..abd5891 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_EXECUTABLE.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_LINK_EXECUTABLE +---------------------------- + +Rule variable to link an executable. + +Rule variable to link an executable for the given language. diff --git a/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst new file mode 100644 index 0000000..7c929d0 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE.rst @@ -0,0 +1,16 @@ +CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE> +--------------------------------------- + +.. versionadded:: 3.24 + +This variable defines how to link a group of libraries for the specified +``<FEATURE>`` when a :genex:`LINK_GROUP` generator expression is used and +the link language for the target is ``<LANG>``. +For this variable to have any effect, the associated +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable +must be set to true. + +The :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable should be defined +instead for features that are independent of the link language. + +.. include:: CMAKE_LINK_GROUP_USING_FEATURE.txt diff --git a/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..b314c5a --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,14 @@ +CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED +------------------------------------------------- + +.. versionadded:: 3.24 + +This variable specifies whether the ``<FEATURE>`` is supported for the link +language ``<LANG>``. If this variable is true, then the ``<FEATURE>`` must +be defined by :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>`, and the +more generic :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` and +:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variables are not used. + +If ``CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED`` is false or is not +set, then the :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` variable +will determine whether ``<FEATURE>`` is deemed to be supported. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst new file mode 100644 index 0000000..23ece88 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_LINK_LIBRARY_FILE_FLAG +----------------------------------- + +.. versionadded:: 3.16 + +Language-specific flag to be used to link a library specified by +a path to its file. + +The flag will be used before a library file path is given to the +linker. This is needed only on very few platforms. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_FLAG.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FLAG.rst new file mode 100644 index 0000000..0f528db --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FLAG.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_LINK_LIBRARY_FLAG +------------------------------ + +.. versionadded:: 3.16 + +Flag to be used to link a library into a shared library or executable. + +This flag will be used to specify a library to link to a shared library or an +executable for the specific language. On most compilers this is ``-l``. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst new file mode 100644 index 0000000..359e29f --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_LINK_LIBRARY_SUFFIX +-------------------------------- + +.. versionadded:: 3.16 + +Language-specific suffix for libraries that you link to. + +The suffix to use for the end of a library filename, ``.lib`` on Windows. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst new file mode 100644 index 0000000..39fcff8 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE.rst @@ -0,0 +1,16 @@ +CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> +----------------------------------------- + +.. versionadded:: 3.24 + +This variable defines how to link a library or framework for the specified +``<FEATURE>`` when a :genex:`LINK_LIBRARY` generator expression is used and +the link language for the target is ``<LANG>``. +For this variable to have any effect, the associated +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` variable +must be set to true. + +The :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable should be defined +instead for features that are independent of the link language. + +.. include:: CMAKE_LINK_LIBRARY_USING_FEATURE.txt diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..e595bc7 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED +--------------------------------------------------- + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>`, is supported for the +linker language ``<LANG>``. + +.. note:: + + This variable is evaluated before the more generic variable + :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED`. diff --git a/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst b/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst new file mode 100644 index 0000000..5004530 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG +----------------------------------- + +.. versionadded:: 3.22 + +Linker flag to be used to configure linker so that all specified libraries on +the command line will be linked into the target. + +See also variable :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK`. diff --git a/Help/variable/CMAKE_LANG_OUTPUT_EXTENSION.rst b/Help/variable/CMAKE_LANG_OUTPUT_EXTENSION.rst new file mode 100644 index 0000000..0fbc566 --- /dev/null +++ b/Help/variable/CMAKE_LANG_OUTPUT_EXTENSION.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_OUTPUT_EXTENSION +----------------------------- + +Extension for the output of a compile for a single file. + +This is the extension for an object file for the given ``<LANG>``. For +example ``.obj`` for C on Windows. diff --git a/Help/variable/CMAKE_LANG_PLATFORM_ID.rst b/Help/variable/CMAKE_LANG_PLATFORM_ID.rst new file mode 100644 index 0000000..1b243e3 --- /dev/null +++ b/Help/variable/CMAKE_LANG_PLATFORM_ID.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_PLATFORM_ID +------------------------ + +An internal variable subject to change. + +This is used in determining the platform and is subject to change. diff --git a/Help/variable/CMAKE_LANG_SIMULATE_ID.rst b/Help/variable/CMAKE_LANG_SIMULATE_ID.rst new file mode 100644 index 0000000..3226352 --- /dev/null +++ b/Help/variable/CMAKE_LANG_SIMULATE_ID.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_SIMULATE_ID +------------------------ + +Identification string of the "simulated" compiler. + +Some compilers simulate other compilers to serve as drop-in +replacements. When CMake detects such a compiler it sets this +variable to what would have been the :variable:`CMAKE_<LANG>_COMPILER_ID` for +the simulated compiler. + +.. note:: + In other words, this variable describes the ABI compatibility + of the generated code. diff --git a/Help/variable/CMAKE_LANG_SIMULATE_VERSION.rst b/Help/variable/CMAKE_LANG_SIMULATE_VERSION.rst new file mode 100644 index 0000000..d6325e0 --- /dev/null +++ b/Help/variable/CMAKE_LANG_SIMULATE_VERSION.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_SIMULATE_VERSION +----------------------------- + +Version string of "simulated" compiler. + +Some compilers simulate other compilers to serve as drop-in +replacements. When CMake detects such a compiler it sets this +variable to what would have been the :variable:`CMAKE_<LANG>_COMPILER_VERSION` +for the simulated compiler. diff --git a/Help/variable/CMAKE_LANG_SIZEOF_DATA_PTR.rst b/Help/variable/CMAKE_LANG_SIZEOF_DATA_PTR.rst new file mode 100644 index 0000000..7465923 --- /dev/null +++ b/Help/variable/CMAKE_LANG_SIZEOF_DATA_PTR.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_SIZEOF_DATA_PTR +---------------------------- + +Size of pointer-to-data types for language ``<LANG>``. + +This holds the size (in bytes) of pointer-to-data types in the target +platform ABI. It is defined for languages ``C`` and ``CXX`` (C++). diff --git a/Help/variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS.rst b/Help/variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS.rst new file mode 100644 index 0000000..e085fee --- /dev/null +++ b/Help/variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS +----------------------------------- + +Extensions of source files for the given language. + +This is the list of extensions for a given language's source files. diff --git a/Help/variable/CMAKE_LANG_STANDARD.rst b/Help/variable/CMAKE_LANG_STANDARD.rst new file mode 100644 index 0000000..0c41e19 --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD.rst @@ -0,0 +1,19 @@ +CMAKE_<LANG>_STANDARD +--------------------- + +The variations are: + +* :variable:`CMAKE_C_STANDARD` +* :variable:`CMAKE_CXX_STANDARD` +* :variable:`CMAKE_CUDA_STANDARD` +* :variable:`CMAKE_HIP_STANDARD` +* :variable:`CMAKE_OBJC_STANDARD` +* :variable:`CMAKE_OBJCXX_STANDARD` + +Default values for :prop_tgt:`<LANG>_STANDARD` target properties if set when a +target is created. + +For supported CMake versions see the respective pages. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LANG_STANDARD_DEFAULT.rst b/Help/variable/CMAKE_LANG_STANDARD_DEFAULT.rst new file mode 100644 index 0000000..eb63d20 --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD_DEFAULT.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_STANDARD_DEFAULT +----------------------------- + +.. versionadded:: 3.9 + +The compiler's default standard for the language ``<LANG>``. Empty if the +compiler has no conception of standard levels. diff --git a/Help/variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..24aca8b --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,16 @@ +CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES +----------------------------------------- + +.. versionadded:: 3.6 + +Include directories to be used for every source file compiled with +the ``<LANG>`` compiler. This is meant for specification of system +include directories needed by the language for the current platform. +The directories always appear at the end of the include path passed +to the compiler. + +This variable should not be set by project code. It is meant to be set by +CMake's platform information modules for the current toolchain, or by a +toolchain file when used with :variable:`CMAKE_TOOLCHAIN_FILE`. + +See also :variable:`CMAKE_<LANG>_STANDARD_LIBRARIES`. diff --git a/Help/variable/CMAKE_LANG_STANDARD_LIBRARIES.rst b/Help/variable/CMAKE_LANG_STANDARD_LIBRARIES.rst new file mode 100644 index 0000000..d5f3351 --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD_LIBRARIES.rst @@ -0,0 +1,14 @@ +CMAKE_<LANG>_STANDARD_LIBRARIES +------------------------------- + +.. versionadded:: 3.6 + +Libraries linked into every executable and shared library linked +for language ``<LANG>``. This is meant for specification of system +libraries needed by the language for the current platform. + +This variable should not be set by project code. It is meant to be set by +CMake's platform information modules for the current toolchain, or by a +toolchain file when used with :variable:`CMAKE_TOOLCHAIN_FILE`. + +See also :variable:`CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES`. diff --git a/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..d7fa9b6 --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst @@ -0,0 +1,19 @@ +CMAKE_<LANG>_STANDARD_REQUIRED +------------------------------ + +The variations are: + +* :variable:`CMAKE_C_STANDARD_REQUIRED` +* :variable:`CMAKE_CXX_STANDARD_REQUIRED` +* :variable:`CMAKE_CUDA_STANDARD_REQUIRED` +* :variable:`CMAKE_HIP_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJC_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED` + +Default values for :prop_tgt:`<LANG>_STANDARD_REQUIRED` target properties if +set when a target is created. + +For supported CMake versions see the respective pages. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LANG_VISIBILITY_PRESET.rst b/Help/variable/CMAKE_LANG_VISIBILITY_PRESET.rst new file mode 100644 index 0000000..1961ea0 --- /dev/null +++ b/Help/variable/CMAKE_LANG_VISIBILITY_PRESET.rst @@ -0,0 +1,5 @@ +CMAKE_<LANG>_VISIBILITY_PRESET +------------------------------ + +Default value for the :prop_tgt:`<LANG>_VISIBILITY_PRESET` target +property when a target is created. diff --git a/Help/variable/CMAKE_LIBRARY_ARCHITECTURE.rst b/Help/variable/CMAKE_LIBRARY_ARCHITECTURE.rst new file mode 100644 index 0000000..8a7dcbd --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_ARCHITECTURE.rst @@ -0,0 +1,7 @@ +CMAKE_LIBRARY_ARCHITECTURE +-------------------------- + +Target architecture library directory name, if detected. + +This is the value of :variable:`CMAKE_<LANG>_LIBRARY_ARCHITECTURE` as detected +for one of the enabled languages. diff --git a/Help/variable/CMAKE_LIBRARY_ARCHITECTURE_REGEX.rst b/Help/variable/CMAKE_LIBRARY_ARCHITECTURE_REGEX.rst new file mode 100644 index 0000000..1eb2ac2 --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_ARCHITECTURE_REGEX.rst @@ -0,0 +1,7 @@ +CMAKE_LIBRARY_ARCHITECTURE_REGEX +-------------------------------- + +Regex matching possible target architecture library directory names. + +This is used to detect :variable:`CMAKE_<LANG>_LIBRARY_ARCHITECTURE` from the +implicit linker search path by matching the ``<arch>`` name. diff --git a/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..e97296d --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst @@ -0,0 +1,9 @@ +CMAKE_LIBRARY_OUTPUT_DIRECTORY +------------------------------ + +Where to put all the :ref:`LIBRARY <Library Output Artifacts>` +target files when built. + +This variable is used to initialize the :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..08f95c4 --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,11 @@ +CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------------- + +.. versionadded:: 3.3 + +Where to put all the :ref:`LIBRARY <Library Output Artifacts>` +target files when built for a specific configuration. + +This variable is used to initialize the +:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY_<CONFIG>` property on all the targets. +See that target property for additional information. diff --git a/Help/variable/CMAKE_LIBRARY_PATH.rst b/Help/variable/CMAKE_LIBRARY_PATH.rst new file mode 100644 index 0000000..8135b65 --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_LIBRARY_PATH +------------------ + +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path +for the :command:`find_library` command. By default it is empty, it is +intended to be set by the project. See also +:variable:`CMAKE_SYSTEM_LIBRARY_PATH` and :variable:`CMAKE_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_LIBRARY_PATH_FLAG.rst b/Help/variable/CMAKE_LIBRARY_PATH_FLAG.rst new file mode 100644 index 0000000..ebe5fda --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_PATH_FLAG.rst @@ -0,0 +1,7 @@ +CMAKE_LIBRARY_PATH_FLAG +----------------------- + +The flag to be used to add a library search path to a compiler. + +The flag will be used to specify a library directory to the compiler. +On most compilers this is ``-L``. diff --git a/Help/variable/CMAKE_LINK_DEF_FILE_FLAG.rst b/Help/variable/CMAKE_LINK_DEF_FILE_FLAG.rst new file mode 100644 index 0000000..fa09f9f --- /dev/null +++ b/Help/variable/CMAKE_LINK_DEF_FILE_FLAG.rst @@ -0,0 +1,7 @@ +CMAKE_LINK_DEF_FILE_FLAG +------------------------ + +Linker flag to be used to specify a ``.def`` file for dll creation. + +The flag will be used to add a ``.def`` file when creating a dll on +Windows; this is only defined on Windows. diff --git a/Help/variable/CMAKE_LINK_DEPENDS_NO_SHARED.rst b/Help/variable/CMAKE_LINK_DEPENDS_NO_SHARED.rst new file mode 100644 index 0000000..cec7906 --- /dev/null +++ b/Help/variable/CMAKE_LINK_DEPENDS_NO_SHARED.rst @@ -0,0 +1,8 @@ +CMAKE_LINK_DEPENDS_NO_SHARED +---------------------------- + +Whether to skip link dependencies on shared library files. + +This variable initializes the :prop_tgt:`LINK_DEPENDS_NO_SHARED` property on +targets when they are created. See that target property for +additional information. diff --git a/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst b/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst new file mode 100644 index 0000000..f120866 --- /dev/null +++ b/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst @@ -0,0 +1,11 @@ +CMAKE_LINK_DIRECTORIES_BEFORE +----------------------------- + +.. versionadded:: 3.13 + +Whether to append or prepend directories by default in +:command:`link_directories`. + +This variable affects the default behavior of the :command:`link_directories` +command. Setting this variable to ``ON`` is equivalent to using the ``BEFORE`` +option in all uses of that command. diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst new file mode 100644 index 0000000..90b7f8b --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.rst @@ -0,0 +1,22 @@ +CMAKE_LINK_GROUP_USING_<FEATURE> +-------------------------------- + +.. versionadded:: 3.24 + +This variable defines how to link a group of libraries for the specified +``<FEATURE>`` when a :genex:`LINK_GROUP` generator expression is used. +Both of the following conditions must be met for this variable to have any +effect: + +* The associated :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + variable must be set to true. + +* There is no language-specific definition for the same ``<FEATURE>``. + This means :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + cannot be true for the link language used by the target for which the + :genex:`LINK_GROUP` generator expression is evaluated. + +The :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` variable should be +defined instead for features that are dependent on the link language. + +.. include:: CMAKE_LINK_GROUP_USING_FEATURE.txt diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt new file mode 100644 index 0000000..23ea157 --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE.txt @@ -0,0 +1,78 @@ +Feature names are case-sensitive and may only contain letters, numbers +and underscores. Feature names defined in all uppercase are reserved for +CMake's own built-in features (see `Predefined Features`_ further below). + + +Feature Definitions +^^^^^^^^^^^^^^^^^^^ + +A group feature definition is a list that contains exactly two elements: + +:: + + <PREFIX> <SUFFIX> + +On the linker command line, ``<PREFIX>`` will precede the list of libraries +in the group and ``<SUFFIX>`` will follow after. + +For the elements of this variable, the ``LINKER:`` prefix can be used. + +.. include:: ../command/LINK_OPTIONS_LINKER.txt + :start-line: 3 + +Examples +^^^^^^^^ + +Solving cross-references between two static libraries +""""""""""""""""""""""""""""""""""""""""""""""""""""" + +A project may define two or more static libraries which have circular +dependencies between them. In order for the linker to resolve all symbols +at link time, it may need to search repeatedly among the libraries until no +new undefined references are created. Different linkers use different syntax +for achieving this. The following example shows how this may be implemented +for some linkers. Note that this is for illustration purposes only. +Projects should use the built-in ``RESCAN`` group feature instead +(see `Predefined Features`_), which provides a more complete and more robust +implementation of this functionality. + +.. code-block:: cmake + + set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED TRUE) + if(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux") + set(CMAKE_C_LINK_GROUP_USING_cross_refs + "LINKER:--start-group" + "LINKER:--end-group" + ) + elseif(CMAKE_C_COMPILER_ID STREQUAL "SunPro" AND CMAKE_SYSTEM_NAME STREQUAL "SunOS") + set(CMAKE_C_LINK_GROUP_USING_cross_refs + "LINKER:-z,rescan-start" + "LINKER:-z,rescan-end" + ) + else() + # feature not yet supported for the other environments + set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED FALSE) + endif() + + add_library(lib1 STATIC ...) + add_library(lib2 SHARED ...) + + if(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED) + target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>") + else() + target_link_libraries(lib2 PRIVATE lib1 external) + endif() + +CMake will generate the following linker command line fragments when linking +``lib2``: + +* ``GNU``: ``-Wl,--start-group /path/to/lib1.a -lexternal -Wl,--end-group`` +* ``SunPro``: ``-Wl,-z,rescan-start /path/to/lib1.a -lexternal -Wl,-z,rescan-end`` + + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +The following built-in group features are pre-defined by CMake: + +.. include:: LINK_GROUP_PREDEFINED_FEATURES.txt diff --git a/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..8b4ee6e --- /dev/null +++ b/Help/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,12 @@ +CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED +------------------------------------------ + +.. versionadded:: 3.24 + +This variable specifies whether the ``<FEATURE>`` is supported regardless of +the link language. If this variable is true, then the ``<FEATURE>`` must +be defined by :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>`. + +Note that this variable has no effect if +:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` is true for +the link language of the target. diff --git a/Help/variable/CMAKE_LINK_INTERFACE_LIBRARIES.rst b/Help/variable/CMAKE_LINK_INTERFACE_LIBRARIES.rst new file mode 100644 index 0000000..33865da --- /dev/null +++ b/Help/variable/CMAKE_LINK_INTERFACE_LIBRARIES.rst @@ -0,0 +1,8 @@ +CMAKE_LINK_INTERFACE_LIBRARIES +------------------------------ + +Default value for :prop_tgt:`LINK_INTERFACE_LIBRARIES` of targets. + +This variable is used to initialize the :prop_tgt:`LINK_INTERFACE_LIBRARIES` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS.rst b/Help/variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS.rst new file mode 100644 index 0000000..513c3d0 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS.rst @@ -0,0 +1,10 @@ +CMAKE_LINK_LIBRARIES_ONLY_TARGETS +--------------------------------- + +.. versionadded:: 3.23 + +Set this variable to initialize the :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` +property of non-imported targets when they are created. Setting it to true +enables an additional check that all items named by +:command:`target_link_libraries` that can be target names are actually names +of existing targets. See the target property documentation for details. diff --git a/Help/variable/CMAKE_LINK_LIBRARY_FILE_FLAG.rst b/Help/variable/CMAKE_LINK_LIBRARY_FILE_FLAG.rst new file mode 100644 index 0000000..6858e2c --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_FILE_FLAG.rst @@ -0,0 +1,7 @@ +CMAKE_LINK_LIBRARY_FILE_FLAG +---------------------------- + +Flag to be used to link a library specified by a path to its file. + +The flag will be used before a library file path is given to the +linker. This is needed only on very few platforms. diff --git a/Help/variable/CMAKE_LINK_LIBRARY_FLAG.rst b/Help/variable/CMAKE_LINK_LIBRARY_FLAG.rst new file mode 100644 index 0000000..b5197e4 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_FLAG.rst @@ -0,0 +1,7 @@ +CMAKE_LINK_LIBRARY_FLAG +----------------------- + +Flag to be used to link a library into an executable. + +The flag will be used to specify a library to link to an executable. +On most compilers this is ``-l``. diff --git a/Help/variable/CMAKE_LINK_LIBRARY_SUFFIX.rst b/Help/variable/CMAKE_LINK_LIBRARY_SUFFIX.rst new file mode 100644 index 0000000..0ddafe8 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_SUFFIX.rst @@ -0,0 +1,6 @@ +CMAKE_LINK_LIBRARY_SUFFIX +------------------------- + +The suffix for libraries that you link to. + +The suffix to use for the end of a library filename, ``.lib`` on Windows. diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst new file mode 100644 index 0000000..c652733 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.rst @@ -0,0 +1,19 @@ +CMAKE_LINK_LIBRARY_USING_<FEATURE> +---------------------------------- + +.. versionadded:: 3.24 + +This variable defines how to link a library or framework for the specified +``<FEATURE>`` when a :genex:`LINK_LIBRARY` generator expression is used. +Both of the following conditions must be met for this variable to have any +effect: + +* The associated :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` + variable must be set to true. + +* There is no language-specific definition for the same ``<FEATURE>``. + This means :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` + cannot be true for the link language used by the target for which the + :genex:`LINK_LIBRARY` generator expression is evaluated. + +.. include:: CMAKE_LINK_LIBRARY_USING_FEATURE.txt diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt new file mode 100644 index 0000000..4b13b7c --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt @@ -0,0 +1,150 @@ +Feature names are case-sensitive and may only contain letters, numbers +and underscores. Feature names defined in all uppercase are reserved for +CMake's own built-in features (see `Predefined Features`_ further below). + + +Feature Definitions +^^^^^^^^^^^^^^^^^^^ + +A library feature definition is a list that contains one or three elements: + +:: + + [<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>] + +When ``<PREFIX>`` and ``<SUFFIX>`` are specified, they precede and follow +respectively the whole list of libraries specified in the +:genex:`LINK_LIBRARY` expression, not each library item individually. +There is no guarantee that the list of specified libraries will be kept +grouped together though, so the ``<PREFIX>`` and ``<SUFFIX>`` may appear +more than once if the library list is reorganized by CMake to satisfy other +constraints. This means constructs like ``--start-group`` and ``--end-group``, +as supported by the GNU ``ld`` linker, cannot be used in this way. The +:genex:`LINK_GROUP` generator expression should be used instead for such +constructs. + +``<LIBRARY_EXPRESSION>`` is used to specify the pattern for constructing the +corresponding fragment on the linker command line for each library. +The following placeholders can be used in the expression: + +* ``<LIBRARY>`` is expanded to the full path to the library for CMake targets, + or to a platform-specific value based on the item otherwise (the same as + ``<LINK_ITEM>`` on Windows, or the library base name for other platforms). +* ``<LINK_ITEM>`` is expanded to how the library would normally be linked on + the linker command line. +* ``<LIB_ITEM>`` is expanded to the full path to the library for CMake targets, + or the item itself exactly as specified in the ``<LIBRARY_EXPRESSION>`` + otherwise. + +In addition to the above, it is possible to have one pattern for paths +(CMake targets and external libraries specified with file paths) and another +for other items specified by name only. The ``PATH{}`` and ``NAME{}`` wrappers +can be used to provide the expansion for those two cases, respectively. +When wrappers are used, both must be present. For example: + +.. code-block:: cmake + + set(CMAKE_LINK_LIBRARY_USING_weak_library + "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}" + ) + +For all three elements of this variable (``<PREFIX>``, ``<LIBRARY_EXPRESSION>``, +and ``<SUFFIX>``), the ``LINKER:`` prefix can be used. + +.. include:: ../command/LINK_OPTIONS_LINKER.txt + :start-line: 3 + +Examples +^^^^^^^^ + +Loading a whole static library +"""""""""""""""""""""""""""""" + +A common need is to prevent the linker from discarding any symbols from a +static library. Different linkers use different syntax for achieving this. +The following example shows how this may be implemented for some linkers. +Note that this is for illustration purposes only. Projects should use the +built-in ``WHOLE_ARCHIVE`` feature instead (see `Predefined Features`_), which +provides a more complete and more robust implementation of this functionality. + +.. code-block:: cmake + + set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED TRUE) + if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang") + set(CMAKE_C_LINK_LIBRARY_USING_load_archive "-force_load <LIB_ITEM>") + elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux") + set(CMAKE_C_LINK_LIBRARY_USING_load_archive + "LINKER:--push-state,--whole-archive" + "<LINK_ITEM>" + "LINKER:--pop-state" + ) + elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC") + set(CMAKE_C_LINK_LIBRARY_USING_load_archive "/WHOLEARCHIVE:<LIBRARY>") + else() + # feature not yet supported for the other environments + set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED FALSE) + endif() + + add_library(lib1 STATIC ...) + add_library(lib2 SHARED ...) + + if(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED) + # The -force_load Apple linker option requires a file name + set(external_lib + "$<IF:$<LINK_LANG_AND_ID:C,AppleClang>,libexternal.a,external>" + ) + target_link_libraries(lib2 PRIVATE + "$<LINK_LIBRARY:load_archive,lib1,${external_lib}>" + ) + else() + target_link_libraries(lib2 PRIVATE lib1 external) + endif() + +CMake will generate the following link expressions: + +* ``AppleClang``: ``-force_load /path/to/lib1.a -force_load libexternal.a`` +* ``GNU``: ``-Wl,--push-state,--whole-archive /path/to/lib1.a -lexternal -Wl,--pop-state`` +* ``MSVC``: ``/WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib`` + +Linking a library as weak +""""""""""""""""""""""""" + +On macOS, it is possible to link a library in weak mode (the library and all +references are marked as weak imports). Different flags must be used for a +library specified by file path compared to one specified by name. +This constraint can be solved using ``PATH{}`` and ``NAME{}`` wrappers. +Again, the following example shows how this may be implemented for some +linkers, but it is for illustration purposes only. Projects should use the +built-in ``WEAK_FRAMEWORK`` or ``WEAK_LIBRARY`` features instead (see +`Predefined Features`_), which provide more complete and more robust +implementations of this functionality. + +.. code-block:: cmake + + if (CMAKE_C_COMPILER_ID STREQUAL "AppleClang") + set(CMAKE_LINK_LIBRARY_USING_weak_library + "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}" + ) + set(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED TRUE) + endif() + + add_library(lib SHARED ...) + add_executable(main ...) + if(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED) + target_link_libraries(main PRIVATE "$<LINK_LIBRARY:weak_library,lib,external>") + else() + target_link_libraries(main PRIVATE lib external) + endif() + +CMake will generate the following linker command line fragment when linking +``main`` using the ``AppleClang`` toolchain: + +``-weak_library /path/to/lib -Xlinker -weak-lexternal``. + + +Predefined Features +^^^^^^^^^^^^^^^^^^^ + +The following built-in library features are pre-defined by CMake: + +.. include:: LINK_LIBRARY_PREDEFINED_FEATURES.txt diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst new file mode 100644 index 0000000..417724b --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED.rst @@ -0,0 +1,14 @@ +CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED +-------------------------------------------- + +.. versionadded:: 3.24 + +Set to ``TRUE`` if the ``<FEATURE>``, as defined by variable +:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>`, is supported regardless the +linker language. + +.. note:: + + This variable is evaluated if, and only if, the variable + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` is not + defined. diff --git a/Help/variable/CMAKE_LINK_SEARCH_END_STATIC.rst b/Help/variable/CMAKE_LINK_SEARCH_END_STATIC.rst new file mode 100644 index 0000000..e86f639 --- /dev/null +++ b/Help/variable/CMAKE_LINK_SEARCH_END_STATIC.rst @@ -0,0 +1,21 @@ +CMAKE_LINK_SEARCH_END_STATIC +---------------------------- + +.. versionadded:: 3.4 + +End a link line such that static system libraries are used. + +Some linkers support switches such as ``-Bstatic`` and ``-Bdynamic`` to +determine whether to use static or shared libraries for ``-lXXX`` options. +CMake uses these options to set the link type for libraries whose full +paths are not known or (in some cases) are in implicit link +directories for the platform. By default CMake adds an option at the +end of the library list (if necessary) to set the linker search type +back to its starting type. This property switches the final linker +search type to ``-Bstatic`` regardless of how it started. + +This variable is used to initialize the target property +:prop_tgt:`LINK_SEARCH_END_STATIC` for all targets. If set, its +value is also used by the :command:`try_compile` command. + +See also :variable:`CMAKE_LINK_SEARCH_START_STATIC`. diff --git a/Help/variable/CMAKE_LINK_SEARCH_START_STATIC.rst b/Help/variable/CMAKE_LINK_SEARCH_START_STATIC.rst new file mode 100644 index 0000000..ab1837c --- /dev/null +++ b/Help/variable/CMAKE_LINK_SEARCH_START_STATIC.rst @@ -0,0 +1,22 @@ +CMAKE_LINK_SEARCH_START_STATIC +------------------------------ + +.. versionadded:: 3.4 + +Assume the linker looks for static libraries by default. + +Some linkers support switches such as ``-Bstatic`` and ``-Bdynamic`` to +determine whether to use static or shared libraries for ``-lXXX`` options. +CMake uses these options to set the link type for libraries whose full +paths are not known or (in some cases) are in implicit link +directories for the platform. By default the linker search type is +assumed to be ``-Bdynamic`` at the beginning of the library list. This +property switches the assumption to ``-Bstatic``. It is intended for use +when linking an executable statically (e.g. with the GNU ``-static`` +option). + +This variable is used to initialize the target property +:prop_tgt:`LINK_SEARCH_START_STATIC` for all targets. If set, its +value is also used by the :command:`try_compile` command. + +See also :variable:`CMAKE_LINK_SEARCH_END_STATIC`. diff --git a/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst new file mode 100644 index 0000000..bca4519 --- /dev/null +++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst @@ -0,0 +1,8 @@ +CMAKE_LINK_WHAT_YOU_USE +----------------------- + +.. versionadded:: 3.7 + +Default value for :prop_tgt:`LINK_WHAT_YOU_USE` target property. +This variable is used to initialize the property on each target as it is +created. diff --git a/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst b/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst new file mode 100644 index 0000000..e626641 --- /dev/null +++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst @@ -0,0 +1,10 @@ +CMAKE_LINK_WHAT_YOU_USE_CHECK +----------------------------- + +.. versionadded:: 3.22 + +Defines the command executed after the link step to check libraries usage. +This check is currently only defined on ``ELF`` platforms with value +``ldd -u -r``. + +See also :variable:`CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG` variables. diff --git a/Help/variable/CMAKE_MACOSX_BUNDLE.rst b/Help/variable/CMAKE_MACOSX_BUNDLE.rst new file mode 100644 index 0000000..43ddff5 --- /dev/null +++ b/Help/variable/CMAKE_MACOSX_BUNDLE.rst @@ -0,0 +1,10 @@ +CMAKE_MACOSX_BUNDLE +------------------- + +Default value for :prop_tgt:`MACOSX_BUNDLE` of targets. + +This variable is used to initialize the :prop_tgt:`MACOSX_BUNDLE` property on +all the targets. See that target property for additional information. + +This variable is set to ``ON`` by default if :variable:`CMAKE_SYSTEM_NAME` +equals to :ref:`iOS, tvOS or watchOS <Cross Compiling for iOS, tvOS, or watchOS>`. diff --git a/Help/variable/CMAKE_MACOSX_RPATH.rst b/Help/variable/CMAKE_MACOSX_RPATH.rst new file mode 100644 index 0000000..2fc648d --- /dev/null +++ b/Help/variable/CMAKE_MACOSX_RPATH.rst @@ -0,0 +1,7 @@ +CMAKE_MACOSX_RPATH +------------------- + +Whether to use rpaths on macOS and iOS. + +This variable is used to initialize the :prop_tgt:`MACOSX_RPATH` property on +all targets. diff --git a/Help/variable/CMAKE_MAJOR_VERSION.rst b/Help/variable/CMAKE_MAJOR_VERSION.rst new file mode 100644 index 0000000..079ad70 --- /dev/null +++ b/Help/variable/CMAKE_MAJOR_VERSION.rst @@ -0,0 +1,5 @@ +CMAKE_MAJOR_VERSION +------------------- + +First version number component of the :variable:`CMAKE_VERSION` +variable. diff --git a/Help/variable/CMAKE_MAKE_PROGRAM.rst b/Help/variable/CMAKE_MAKE_PROGRAM.rst new file mode 100644 index 0000000..9769c7a --- /dev/null +++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst @@ -0,0 +1,64 @@ +CMAKE_MAKE_PROGRAM +------------------ + +Tool that can launch the native build system. +The value may be the full path to an executable or just the tool +name if it is expected to be in the ``PATH``. + +The tool selected depends on the :variable:`CMAKE_GENERATOR` used +to configure the project: + +* The :ref:`Makefile Generators` set this to ``make``, ``gmake``, or + a generator-specific tool (e.g. ``nmake`` for :generator:`NMake Makefiles`). + + These generators store ``CMAKE_MAKE_PROGRAM`` in the CMake cache + so that it may be edited by the user. + +* The :generator:`Ninja` generator sets this to ``ninja``. + + This generator stores ``CMAKE_MAKE_PROGRAM`` in the CMake cache + so that it may be edited by the user. + +* The :generator:`Xcode` generator sets this to ``xcodebuild``. + + This generator prefers to lookup the build tool at build time + rather than to store ``CMAKE_MAKE_PROGRAM`` in the CMake cache + ahead of time. This is because ``xcodebuild`` is easy to find. + + For compatibility with versions of CMake prior to 3.2, if + a user or project explicitly adds ``CMAKE_MAKE_PROGRAM`` to + the CMake cache then CMake will use the specified value. + +* The :ref:`Visual Studio Generators` set this to the full path to + ``MSBuild.exe`` (VS >= 10), ``devenv.com`` (VS 7,8,9), or + ``VCExpress.exe`` (VS Express 8,9). + (See also variables + :variable:`CMAKE_VS_MSBUILD_COMMAND` and + :variable:`CMAKE_VS_DEVENV_COMMAND`. + + These generators prefer to lookup the build tool at build time + rather than to store ``CMAKE_MAKE_PROGRAM`` in the CMake cache + ahead of time. This is because the tools are version-specific + and can be located using the Windows Registry. It is also + necessary because the proper build tool may depend on the + project content (e.g. the Intel Fortran plugin to VS 10 and 11 + requires ``devenv.com`` to build its ``.vfproj`` project files + even though ``MSBuild.exe`` is normally preferred to support + the :variable:`CMAKE_GENERATOR_TOOLSET`). + + For compatibility with versions of CMake prior to 3.0, if + a user or project explicitly adds ``CMAKE_MAKE_PROGRAM`` to + the CMake cache then CMake will use the specified value if + possible. + +* The :generator:`Green Hills MULTI` generator sets this to the full + path to ``gbuild.exe(Windows)`` or ``gbuild(Linux)`` based upon + the toolset being used. + + Once the generator has initialized a particular value for this + variable, changing the value has undefined behavior. + +The ``CMAKE_MAKE_PROGRAM`` variable is set for use by project code. +The value is also used by the :option:`cmake --build` and +:option:`ctest --build-and-test` tools to launch the native +build process. diff --git a/Help/variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG.rst b/Help/variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG.rst new file mode 100644 index 0000000..ed29afe --- /dev/null +++ b/Help/variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG.rst @@ -0,0 +1,8 @@ +CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> +---------------------------------- + +Default value for :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` of targets. + +This variable is used to initialize the +:prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` property on all the targets. See +that target property for additional information. diff --git a/Help/variable/CMAKE_MATCH_COUNT.rst b/Help/variable/CMAKE_MATCH_COUNT.rst new file mode 100644 index 0000000..deeec8b --- /dev/null +++ b/Help/variable/CMAKE_MATCH_COUNT.rst @@ -0,0 +1,11 @@ +CMAKE_MATCH_COUNT +----------------- + +.. versionadded:: 3.2 + +The number of matches with the last regular expression. + +When a regular expression match is used, CMake fills in +:variable:`CMAKE_MATCH_<n>` variables with the match contents. +The ``CMAKE_MATCH_COUNT`` variable holds the number of match +expressions when these are filled. diff --git a/Help/variable/CMAKE_MATCH_n.rst b/Help/variable/CMAKE_MATCH_n.rst new file mode 100644 index 0000000..a92788e --- /dev/null +++ b/Help/variable/CMAKE_MATCH_n.rst @@ -0,0 +1,12 @@ +CMAKE_MATCH_<n> +--------------- + +.. versionadded:: 3.9 + +Capture group ``<n>`` matched by the last regular expression, for groups +0 through 9. Group 0 is the entire match. Groups 1 through 9 are the +subexpressions captured by ``()`` syntax. + +When a regular expression match is used, CMake fills in ``CMAKE_MATCH_<n>`` +variables with the match contents. The :variable:`CMAKE_MATCH_COUNT` +variable holds the number of match expressions when these are filled. diff --git a/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst b/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst new file mode 100644 index 0000000..59c60d3 --- /dev/null +++ b/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst @@ -0,0 +1,35 @@ +CMAKE_MAXIMUM_RECURSION_DEPTH +----------------------------- + +.. versionadded:: 3.14 + +Maximum recursion depth for CMake scripts. It is intended to be set on the +command line with ``-DCMAKE_MAXIMUM_RECURSION_DEPTH=<x>``, or within +``CMakeLists.txt`` by projects that require a large recursion depth. Projects +that set this variable should provide the user with a way to override it. For +example: + +.. code-block:: cmake + + # About to perform deeply recursive actions + if(NOT CMAKE_MAXIMUM_RECURSION_DEPTH) + set(CMAKE_MAXIMUM_RECURSION_DEPTH 2000) + endif() + +If it is not set, or is set to a non-integer value, a sensible default limit is +used. If the recursion limit is reached, the script terminates immediately with +a fatal error. + +Calling any of the following commands increases the recursion depth: + +* :command:`include` +* :command:`find_package` +* :command:`add_subdirectory` +* :command:`try_compile` +* :command:`ctest_read_custom_files` +* :command:`ctest_run_script` (unless ``NEW_PROCESS`` is specified) +* User-defined :command:`function`'s and :command:`macro`'s (note that + :command:`function` and :command:`macro` themselves don't increase recursion + depth) +* Reading or writing variables that are being watched by a + :command:`variable_watch` diff --git a/Help/variable/CMAKE_MESSAGE_CONTEXT.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst new file mode 100644 index 0000000..7274b7b --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_CONTEXT.rst @@ -0,0 +1,64 @@ +CMAKE_MESSAGE_CONTEXT +--------------------- + +.. versionadded:: 3.17 + +When enabled by the :option:`cmake --log-context` command line +option or the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable, the +:command:`message` command converts the ``CMAKE_MESSAGE_CONTEXT`` list into a +dot-separated string surrounded by square brackets and prepends it to each line +for messages of log levels ``NOTICE`` and below. + +For logging contexts to work effectively, projects should generally +``APPEND`` and ``POP_BACK`` an item to the current value of +``CMAKE_MESSAGE_CONTEXT`` rather than replace it. +Projects should not assume the message context at the top of the source tree +is empty, as there are scenarios where the context might have already been set +(e.g. hierarchical projects). + +.. warning:: + + Valid context names are restricted to anything that could be used + as a CMake variable name. All names that begin with an underscore + or the string ``cmake_`` are also reserved for use by CMake and + should not be used by projects. + +Example: + +.. code-block:: cmake + + function(bar) + list(APPEND CMAKE_MESSAGE_CONTEXT "bar") + message(VERBOSE "bar VERBOSE message") + endfunction() + + function(baz) + list(APPEND CMAKE_MESSAGE_CONTEXT "baz") + message(DEBUG "baz DEBUG message") + endfunction() + + function(foo) + list(APPEND CMAKE_MESSAGE_CONTEXT "foo") + bar() + message(TRACE "foo TRACE message") + baz() + endfunction() + + list(APPEND CMAKE_MESSAGE_CONTEXT "top") + + message(VERBOSE "Before `foo`") + foo() + message(VERBOSE "After `foo`") + + list(POP_BACK CMAKE_MESSAGE_CONTEXT) + + +Which results in the following output: + +.. code-block:: none + + -- [top] Before `foo` + -- [top.foo.bar] bar VERBOSE message + -- [top.foo] foo TRACE message + -- [top.foo.baz] baz DEBUG message + -- [top] After `foo` diff --git a/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst b/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst new file mode 100644 index 0000000..382e9ff --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_CONTEXT_SHOW.rst @@ -0,0 +1,17 @@ +CMAKE_MESSAGE_CONTEXT_SHOW +-------------------------- + +.. versionadded:: 3.17 + +Setting this variable to true enables showing a context with each line +logged by the :command:`message` command (see :variable:`CMAKE_MESSAGE_CONTEXT` +for how the context itself is specified). + +This variable is an alternative to providing the ``--log-context`` option +on the :manual:`cmake <cmake(1)>` command line. Whereas the command line +option will apply only to that one CMake run, setting +``CMAKE_MESSAGE_CONTEXT_SHOW`` to true as a cache variable will ensure that +subsequent CMake runs will continue to show the message context. + +Projects should not set ``CMAKE_MESSAGE_CONTEXT_SHOW``. It is intended for +users so that they may control whether or not to include context with messages. diff --git a/Help/variable/CMAKE_MESSAGE_INDENT.rst b/Help/variable/CMAKE_MESSAGE_INDENT.rst new file mode 100644 index 0000000..c6263d2 --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_INDENT.rst @@ -0,0 +1,34 @@ +CMAKE_MESSAGE_INDENT +-------------------- + +.. versionadded:: 3.16 + +The :command:`message` command joins the strings from this list and for +log levels of ``NOTICE`` and below, it prepends the resultant string to +each line of the message. + +Example: + +.. code-block:: cmake + + list(APPEND listVar one two three) + + message(VERBOSE [[Collected items in the "listVar":]]) + list(APPEND CMAKE_MESSAGE_INDENT " ") + + foreach(item IN LISTS listVar) + message(VERBOSE ${item}) + endforeach() + + list(POP_BACK CMAKE_MESSAGE_INDENT) + message(VERBOSE "No more indent") + +Which results in the following output: + +.. code-block:: none + + -- Collected items in the "listVar": + -- one + -- two + -- three + -- No more indent diff --git a/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst new file mode 100644 index 0000000..4539c90 --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst @@ -0,0 +1,23 @@ +CMAKE_MESSAGE_LOG_LEVEL +----------------------- + +.. versionadded:: 3.17 + +When set, this variable specifies the logging level used by the +:command:`message` command. Valid values are the same as those for the +:option:`--log-level <cmake --log-level>` command line option of the +:manual:`cmake(1)` program. If this variable is set and the +:option:`--log-level <cmake --log-level>` command line option is +given, the command line option takes precedence. + +The main advantage to using this variable is to make a log level persist +between CMake runs. Setting it as a cache variable will ensure that +subsequent CMake runs will continue to use the chosen log level. + +Projects should not set this variable, it is intended for users so that +they may control the log level according to their own needs. + +.. versionadded:: 3.25 + See the :command:`cmake_language` + :ref:`cmake_language <query_message_log_level>` command for a way to query + the current message logging level. diff --git a/Help/variable/CMAKE_MFC_FLAG.rst b/Help/variable/CMAKE_MFC_FLAG.rst new file mode 100644 index 0000000..118e9c6 --- /dev/null +++ b/Help/variable/CMAKE_MFC_FLAG.rst @@ -0,0 +1,20 @@ +CMAKE_MFC_FLAG +-------------- + +Use the MFC library for an executable or dll. + +Enables the use of the Microsoft Foundation Classes (MFC). +It should be set to ``1`` for the static MFC library, and +``2`` for the shared MFC library. This is used in Visual Studio +project files. + +Usage example: + +.. code-block:: cmake + + add_definitions(-D_AFXDLL) + set(CMAKE_MFC_FLAG 2) + add_executable(CMakeSetup WIN32 ${SRCS}) + +Contents of ``CMAKE_MFC_FLAG`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst new file mode 100644 index 0000000..8d6b533 --- /dev/null +++ b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst @@ -0,0 +1,6 @@ +CMAKE_MINIMUM_REQUIRED_VERSION +------------------------------ + +The ``<min>`` version of CMake given to the most recent call to the +:command:`cmake_minimum_required(VERSION)` command in the current +variable scope or any parent variable scope. diff --git a/Help/variable/CMAKE_MINOR_VERSION.rst b/Help/variable/CMAKE_MINOR_VERSION.rst new file mode 100644 index 0000000..f67cfb9 --- /dev/null +++ b/Help/variable/CMAKE_MINOR_VERSION.rst @@ -0,0 +1,5 @@ +CMAKE_MINOR_VERSION +------------------- + +Second version number component of the :variable:`CMAKE_VERSION` +variable. diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS.rst new file mode 100644 index 0000000..6372bbd --- /dev/null +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS.rst @@ -0,0 +1,6 @@ +CMAKE_MODULE_LINKER_FLAGS +------------------------- + +Linker flags to be used to create modules. + +These flags will be used by the linker when creating a module. diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG.rst new file mode 100644 index 0000000..393263e --- /dev/null +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG.rst @@ -0,0 +1,6 @@ +CMAKE_MODULE_LINKER_FLAGS_<CONFIG> +---------------------------------- + +Flags to be used when linking a module. + +Same as ``CMAKE_C_FLAGS_*`` but used by the linker when creating modules. diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..e8a6401 --- /dev/null +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,12 @@ +CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_MODULE_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_MODULE_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..d59e9bf --- /dev/null +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst @@ -0,0 +1,13 @@ +CMAKE_MODULE_LINKER_FLAGS_INIT +------------------------------ + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_MODULE_LINKER_FLAGS` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also the configuration-specific variable +:variable:`CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_MODULE_PATH.rst b/Help/variable/CMAKE_MODULE_PATH.rst new file mode 100644 index 0000000..4dcf6b5 --- /dev/null +++ b/Help/variable/CMAKE_MODULE_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_MODULE_PATH +----------------- + +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path +for CMake modules to be loaded by the :command:`include` or +:command:`find_package` commands before checking the default modules that come +with CMake. By default it is empty, it is intended to be set by the project. diff --git a/Help/variable/CMAKE_MSVCIDE_RUN_PATH.rst b/Help/variable/CMAKE_MSVCIDE_RUN_PATH.rst new file mode 100644 index 0000000..721ceaa --- /dev/null +++ b/Help/variable/CMAKE_MSVCIDE_RUN_PATH.rst @@ -0,0 +1,12 @@ +CMAKE_MSVCIDE_RUN_PATH +---------------------- + +.. versionadded:: 3.10 + +Extra PATH locations that should be used when executing +:command:`add_custom_command` or :command:`add_custom_target` when using the +:generator:`Visual Studio 9 2008` (or above) generator. This allows +for running commands and using dll's that the IDE environment is not aware of. + +If not set explicitly the value is initialized by the ``CMAKE_MSVCIDE_RUN_PATH`` +environment variable, if set, and otherwise left empty. diff --git a/Help/variable/CMAKE_MSVC_DEBUG_INFORMATION_FORMAT.rst b/Help/variable/CMAKE_MSVC_DEBUG_INFORMATION_FORMAT.rst new file mode 100644 index 0000000..80df8fc --- /dev/null +++ b/Help/variable/CMAKE_MSVC_DEBUG_INFORMATION_FORMAT.rst @@ -0,0 +1,36 @@ +CMAKE_MSVC_DEBUG_INFORMATION_FORMAT +----------------------------------- + +.. versionadded:: 3.25 + +Select the MSVC debug information format targeting the MSVC ABI. +This variable is used to initialize the +:prop_tgt:`MSVC_DEBUG_INFORMATION_FORMAT` property on all targets as they are +created. It is also propagated by calls to the :command:`try_compile` command +into the test project. + +The allowed values are: + +.. include:: ../prop_tgt/MSVC_DEBUG_INFORMATION_FORMAT-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to +support per-configuration specification. For example, the code: + +.. code-block:: cmake + + set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT "$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>") + +selects for all following targets the program database debug information format +for the Debug configuration. + +If this variable is not set, the :prop_tgt:`MSVC_DEBUG_INFORMATION_FORMAT` +target property will not be set automatically. If that property is not set, +CMake selects a debug information format using the default value +``$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>``, if supported by the +compiler, and otherwise ``$<$<CONFIG:Debug,RelWithDebInfo>:Embedded>``. + +.. note:: + + This variable has effect only when policy :policy:`CMP0141` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables a language using a compiler targeting the MSVC ABI. diff --git a/Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst b/Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst new file mode 100644 index 0000000..14806e6 --- /dev/null +++ b/Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst @@ -0,0 +1,34 @@ +CMAKE_MSVC_RUNTIME_LIBRARY +-------------------------- + +.. versionadded:: 3.15 + +Select the MSVC runtime library for use by compilers targeting the MSVC ABI. +This variable is used to initialize the :prop_tgt:`MSVC_RUNTIME_LIBRARY` +property on all targets as they are created. It is also propagated by +calls to the :command:`try_compile` command into the test project. + +The allowed values are: + +.. include:: ../prop_tgt/MSVC_RUNTIME_LIBRARY-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to +support per-configuration specification. For example, the code: + +.. code-block:: cmake + + set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>") + +selects for all following targets a multi-threaded statically-linked runtime +library with or without debug information depending on the configuration. + +If this variable is not set then the :prop_tgt:`MSVC_RUNTIME_LIBRARY` target +property will not be set automatically. If that property is not set then +CMake uses the default value ``MultiThreaded$<$<CONFIG:Debug>:Debug>DLL`` +to select a MSVC runtime library. + +.. note:: + + This variable has effect only when policy :policy:`CMP0091` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables a language using a compiler targeting the MSVC ABI. diff --git a/Help/variable/CMAKE_NETRC.rst b/Help/variable/CMAKE_NETRC.rst new file mode 100644 index 0000000..bddfca5 --- /dev/null +++ b/Help/variable/CMAKE_NETRC.rst @@ -0,0 +1,13 @@ +CMAKE_NETRC +----------- + +.. versionadded:: 3.11 + +This variable is used to initialize the ``NETRC`` option for the +:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands. +See those commands for additional information. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. + +The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_NETRC_FILE.rst b/Help/variable/CMAKE_NETRC_FILE.rst new file mode 100644 index 0000000..af98170 --- /dev/null +++ b/Help/variable/CMAKE_NETRC_FILE.rst @@ -0,0 +1,13 @@ +CMAKE_NETRC_FILE +---------------- + +.. versionadded:: 3.11 + +This variable is used to initialize the ``NETRC_FILE`` option for the +:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands. +See those commands for additional information. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. + +The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst b/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst new file mode 100644 index 0000000..a8c4035 --- /dev/null +++ b/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst @@ -0,0 +1,29 @@ +CMAKE_NINJA_OUTPUT_PATH_PREFIX +------------------------------ + +.. versionadded:: 3.6 + +Set output files path prefix for the :generator:`Ninja` generator. + +Every output files listed in the generated ``build.ninja`` will be +prefixed by the contents of this variable (a trailing slash is +appended if missing). This is useful when the generated ninja file is +meant to be embedded as a ``subninja`` file into a *super* ninja +project. For example, a ninja build file generated with a command +like:: + + cd top-build-dir/sub && + cmake -G Ninja -DCMAKE_NINJA_OUTPUT_PATH_PREFIX=sub/ path/to/source + +can be embedded in ``top-build-dir/build.ninja`` with a directive like +this:: + + subninja sub/build.ninja + +The ``auto-regeneration`` rule in ``top-build-dir/build.ninja`` must have an +order-only dependency on ``sub/build.ninja``. + +.. note:: + When ``CMAKE_NINJA_OUTPUT_PATH_PREFIX`` is set, the project generated + by CMake cannot be used as a standalone project. No default targets + are specified. diff --git a/Help/variable/CMAKE_NOT_USING_CONFIG_FLAGS.rst b/Help/variable/CMAKE_NOT_USING_CONFIG_FLAGS.rst new file mode 100644 index 0000000..98960c5 --- /dev/null +++ b/Help/variable/CMAKE_NOT_USING_CONFIG_FLAGS.rst @@ -0,0 +1,7 @@ +CMAKE_NOT_USING_CONFIG_FLAGS +---------------------------- + +Skip ``_BUILD_TYPE`` flags if true. + +This is an internal flag used by the generators in CMake to tell CMake +to skip the ``_BUILD_TYPE`` flags. diff --git a/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst b/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst new file mode 100644 index 0000000..483ec5f --- /dev/null +++ b/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst @@ -0,0 +1,20 @@ +CMAKE_NO_BUILTIN_CHRPATH +------------------------ + +Do not use the builtin binary editor to fix runtime library search +paths on installation. + +When an ELF or XCOFF binary needs to have a different runtime library +search path after installation than it does in the build tree, CMake uses +a builtin editor to change the runtime search path in the installed copy. +If this variable is set to true then CMake will relink the binary before +installation instead of using its builtin editor. + +For more information on RPATH handling see +the :prop_tgt:`INSTALL_RPATH` and :prop_tgt:`BUILD_RPATH` target properties. + +.. versionadded:: 3.20 + + This variable also applies to XCOFF binaries' LIBPATH. Prior to the + addition of the XCOFF editor in CMake 3.20, this variable applied only + to ELF binaries' RPATH/RUNPATH. diff --git a/Help/variable/CMAKE_NO_SYSTEM_FROM_IMPORTED.rst b/Help/variable/CMAKE_NO_SYSTEM_FROM_IMPORTED.rst new file mode 100644 index 0000000..61e04b4 --- /dev/null +++ b/Help/variable/CMAKE_NO_SYSTEM_FROM_IMPORTED.rst @@ -0,0 +1,8 @@ +CMAKE_NO_SYSTEM_FROM_IMPORTED +----------------------------- + +Default value for :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` of targets. + +This variable is used to initialize the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst new file mode 100644 index 0000000..46736aa --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst @@ -0,0 +1,10 @@ +CMAKE_OBJCXX_EXTENSIONS +----------------------- + +.. versionadded:: 3.16 + +Default value for :prop_tgt:`OBJCXX_EXTENSIONS` target property if set when a +target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJCXX_STANDARD.rst b/Help/variable/CMAKE_OBJCXX_STANDARD.rst new file mode 100644 index 0000000..0913382 --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_STANDARD.rst @@ -0,0 +1,10 @@ +CMAKE_OBJCXX_STANDARD +--------------------- + +.. versionadded:: 3.16 + +Default value for :prop_tgt:`OBJCXX_STANDARD` target property if set when a +target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..9afc4ea --- /dev/null +++ b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst @@ -0,0 +1,10 @@ +CMAKE_OBJCXX_STANDARD_REQUIRED +------------------------------ + +.. versionadded:: 3.16 + +Default value for :prop_tgt:`OBJCXX_STANDARD_REQUIRED` target property if set +when a target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_EXTENSIONS.rst b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst new file mode 100644 index 0000000..9df11f1 --- /dev/null +++ b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst @@ -0,0 +1,10 @@ +CMAKE_OBJC_EXTENSIONS +--------------------- + +.. versionadded:: 3.16 + +Default value for :prop_tgt:`OBJC_EXTENSIONS` target property if set when a +target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_STANDARD.rst b/Help/variable/CMAKE_OBJC_STANDARD.rst new file mode 100644 index 0000000..0b9b63f --- /dev/null +++ b/Help/variable/CMAKE_OBJC_STANDARD.rst @@ -0,0 +1,10 @@ +CMAKE_OBJC_STANDARD +------------------- + +.. versionadded:: 3.16 + +Default value for :prop_tgt:`OBJC_STANDARD` target property if set when a +target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..c74db55 --- /dev/null +++ b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst @@ -0,0 +1,10 @@ +CMAKE_OBJC_STANDARD_REQUIRED +---------------------------- + +.. versionadded:: 3.16 + +Default value for :prop_tgt:`OBJC_STANDARD_REQUIRED` target property if set +when a target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJECT_PATH_MAX.rst b/Help/variable/CMAKE_OBJECT_PATH_MAX.rst new file mode 100644 index 0000000..9e30cbb --- /dev/null +++ b/Help/variable/CMAKE_OBJECT_PATH_MAX.rst @@ -0,0 +1,16 @@ +CMAKE_OBJECT_PATH_MAX +--------------------- + +Maximum object file full-path length allowed by native build tools. + +CMake computes for every source file an object file name that is +unique to the source file and deterministic with respect to the full +path to the source file. This allows multiple source files in a +target to share the same name if they lie in different directories +without rebuilding when one is added or removed. However, it can +produce long full paths in a few cases, so CMake shortens the path +using a hashing scheme when the full path to an object file exceeds a +limit. CMake has a built-in limit for each platform that is +sufficient for common tools, but some native tools may have a lower +limit. This variable may be set to specify the limit explicitly. The +value must be an integer no less than 128. diff --git a/Help/variable/CMAKE_OPTIMIZE_DEPENDENCIES.rst b/Help/variable/CMAKE_OPTIMIZE_DEPENDENCIES.rst new file mode 100644 index 0000000..0ffb902 --- /dev/null +++ b/Help/variable/CMAKE_OPTIMIZE_DEPENDENCIES.rst @@ -0,0 +1,6 @@ +CMAKE_OPTIMIZE_DEPENDENCIES +--------------------------- + +.. versionadded:: 3.19 + +Initializes the :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property. diff --git a/Help/variable/CMAKE_OSX_ARCHITECTURES.rst b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst new file mode 100644 index 0000000..fdaca28 --- /dev/null +++ b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst @@ -0,0 +1,10 @@ +CMAKE_OSX_ARCHITECTURES +----------------------- + +Target specific architectures for macOS and iOS. + +This variable is used to initialize the :prop_tgt:`OSX_ARCHITECTURES` +property on each target as it is created. See that target property +for additional information. + +.. include:: CMAKE_OSX_VARIABLE.txt diff --git a/Help/variable/CMAKE_OSX_DEPLOYMENT_TARGET.rst b/Help/variable/CMAKE_OSX_DEPLOYMENT_TARGET.rst new file mode 100644 index 0000000..9df5edd --- /dev/null +++ b/Help/variable/CMAKE_OSX_DEPLOYMENT_TARGET.rst @@ -0,0 +1,15 @@ +CMAKE_OSX_DEPLOYMENT_TARGET +--------------------------- + +Specify the minimum version of the target platform (e.g. macOS or iOS) +on which the target binaries are to be deployed. CMake uses this +variable value for the ``-mmacosx-version-min`` flag or their respective +target platform equivalents. For older Xcode versions that shipped +multiple macOS SDKs this variable also helps to choose the SDK in case +:variable:`CMAKE_OSX_SYSROOT` is unset. + +If not set explicitly the value is initialized by the +``MACOSX_DEPLOYMENT_TARGET`` environment variable, if set, +and otherwise computed based on the host platform. + +.. include:: CMAKE_OSX_VARIABLE.txt diff --git a/Help/variable/CMAKE_OSX_SYSROOT.rst b/Help/variable/CMAKE_OSX_SYSROOT.rst new file mode 100644 index 0000000..db9fccd --- /dev/null +++ b/Help/variable/CMAKE_OSX_SYSROOT.rst @@ -0,0 +1,13 @@ +CMAKE_OSX_SYSROOT +----------------- + +Specify the location or name of the macOS platform SDK to be used. +CMake uses this value to compute the value of the ``-isysroot`` flag +or equivalent and to help the ``find_*`` commands locate files in +the SDK. + +If not set explicitly the value is initialized by the ``SDKROOT`` +environment variable, if set, and otherwise computed based on the +:variable:`CMAKE_OSX_DEPLOYMENT_TARGET` or the host platform. + +.. include:: CMAKE_OSX_VARIABLE.txt diff --git a/Help/variable/CMAKE_OSX_VARIABLE.txt b/Help/variable/CMAKE_OSX_VARIABLE.txt new file mode 100644 index 0000000..5670980 --- /dev/null +++ b/Help/variable/CMAKE_OSX_VARIABLE.txt @@ -0,0 +1,12 @@ +The value of this variable should be set prior to the first +:command:`project` or :command:`enable_language` command invocation +because it may influence configuration of the toolchain and flags. +It is intended to be set locally by the user creating a build tree. +This variable should be set as a ``CACHE`` entry (or else CMake may +remove it while initializing a cache entry of the same name) unless +policy :policy:`CMP0126` is set to ``NEW``. + +Despite the ``OSX`` part in the variable name(s) they apply also to +other SDKs than macOS like iOS, tvOS, or watchOS. + +This variable is ignored on platforms other than Apple. diff --git a/Help/variable/CMAKE_PARENT_LIST_FILE.rst b/Help/variable/CMAKE_PARENT_LIST_FILE.rst new file mode 100644 index 0000000..cfd8608 --- /dev/null +++ b/Help/variable/CMAKE_PARENT_LIST_FILE.rst @@ -0,0 +1,9 @@ +CMAKE_PARENT_LIST_FILE +---------------------- + +Full path to the CMake file that included the current one. + +While processing a CMake file loaded by :command:`include` or +:command:`find_package` this variable contains the full path to the file +including it. The top of the include stack is always the ``CMakeLists.txt`` +for the current directory. See also :variable:`CMAKE_CURRENT_LIST_FILE`. diff --git a/Help/variable/CMAKE_PATCH_VERSION.rst b/Help/variable/CMAKE_PATCH_VERSION.rst new file mode 100644 index 0000000..991ae76 --- /dev/null +++ b/Help/variable/CMAKE_PATCH_VERSION.rst @@ -0,0 +1,5 @@ +CMAKE_PATCH_VERSION +------------------- + +Third version number component of the :variable:`CMAKE_VERSION` +variable. diff --git a/Help/variable/CMAKE_PCH_INSTANTIATE_TEMPLATES.rst b/Help/variable/CMAKE_PCH_INSTANTIATE_TEMPLATES.rst new file mode 100644 index 0000000..9867f17 --- /dev/null +++ b/Help/variable/CMAKE_PCH_INSTANTIATE_TEMPLATES.rst @@ -0,0 +1,7 @@ +CMAKE_PCH_INSTANTIATE_TEMPLATES +------------------------------- + +.. versionadded:: 3.19 + +This variable is used to initialize the :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` +property of targets when they are created. diff --git a/Help/variable/CMAKE_PCH_WARN_INVALID.rst b/Help/variable/CMAKE_PCH_WARN_INVALID.rst new file mode 100644 index 0000000..457a428 --- /dev/null +++ b/Help/variable/CMAKE_PCH_WARN_INVALID.rst @@ -0,0 +1,7 @@ +CMAKE_PCH_WARN_INVALID +---------------------- + +.. versionadded:: 3.18 + +This variable is used to initialize the :prop_tgt:`PCH_WARN_INVALID` +property of targets when they are created. diff --git a/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..763bcb3 --- /dev/null +++ b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY.rst @@ -0,0 +1,9 @@ +CMAKE_PDB_OUTPUT_DIRECTORY +-------------------------- + +Output directory for MS debug symbol ``.pdb`` files generated by the +linker for executable and shared library targets. + +This variable is used to initialize the :prop_tgt:`PDB_OUTPUT_DIRECTORY` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..4d18eec --- /dev/null +++ b/Help/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,11 @@ +CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG> +----------------------------------- + +Per-configuration output directory for MS debug symbol ``.pdb`` files +generated by the linker for executable and shared library targets. + +This is a per-configuration version of :variable:`CMAKE_PDB_OUTPUT_DIRECTORY`. +This variable is used to initialize the +:prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME.rst b/Help/variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME.rst new file mode 100644 index 0000000..bf15fc8 --- /dev/null +++ b/Help/variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME.rst @@ -0,0 +1,14 @@ +CMAKE_PLATFORM_NO_VERSIONED_SONAME +---------------------------------- + +.. versionadded:: 3.1 + +This variable is used to globally control whether the +:prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target +properties should be used for shared libraries. +When set to true, adding version information to each +shared library target is disabled. + +By default this variable is set only on platforms where +CMake knows it is needed. On other platforms, the +specified properties will be used for shared libraries. diff --git a/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst new file mode 100644 index 0000000..d643fb8 --- /dev/null +++ b/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst @@ -0,0 +1,24 @@ +CMAKE_POLICY_DEFAULT_CMP<NNNN> +------------------------------ + +Default for CMake Policy ``CMP<NNNN>`` when it is otherwise left unset. + +Commands :command:`cmake_minimum_required(VERSION)` and +:command:`cmake_policy(VERSION)` by default leave policies introduced after +the given version unset. Set ``CMAKE_POLICY_DEFAULT_CMP<NNNN>`` to ``OLD`` +or ``NEW`` to specify the default for policy ``CMP<NNNN>``, where ``<NNNN>`` +is the policy number. + +This variable should not be set by a project in CMake code as a way to +set its own policies; use :command:`cmake_policy(SET)` instead. This +variable is meant to externally set policies for which a project has +not itself been updated: + +* Users running CMake may set this variable in the cache + (e.g. ``-DCMAKE_POLICY_DEFAULT_CMP<NNNN>=<OLD|NEW>``). Set it to ``OLD`` + to quiet a policy warning while using old behavior or to ``NEW`` to + try building the project with new behavior. + +* Projects may set this variable before a call to :command:`add_subdirectory` + that adds a third-party project in order to set its policies without + modifying third-party code. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst new file mode 100644 index 0000000..f844105 --- /dev/null +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -0,0 +1,49 @@ +CMAKE_POLICY_WARNING_CMP<NNNN> +------------------------------ + +Explicitly enable or disable the warning when CMake Policy ``CMP<NNNN>`` +has not been set explicitly by :command:`cmake_policy` or implicitly +by :command:`cmake_minimum_required`. This is meaningful +only for the policies that do not warn by default: + +* ``CMAKE_POLICY_WARNING_CMP0025`` controls the warning for + policy :policy:`CMP0025`. +* ``CMAKE_POLICY_WARNING_CMP0047`` controls the warning for + policy :policy:`CMP0047`. +* ``CMAKE_POLICY_WARNING_CMP0056`` controls the warning for + policy :policy:`CMP0056`. +* ``CMAKE_POLICY_WARNING_CMP0060`` controls the warning for + policy :policy:`CMP0060`. +* ``CMAKE_POLICY_WARNING_CMP0065`` controls the warning for + policy :policy:`CMP0065`. +* ``CMAKE_POLICY_WARNING_CMP0066`` controls the warning for + policy :policy:`CMP0066`. +* ``CMAKE_POLICY_WARNING_CMP0067`` controls the warning for + policy :policy:`CMP0067`. +* ``CMAKE_POLICY_WARNING_CMP0082`` controls the warning for + policy :policy:`CMP0082`. +* ``CMAKE_POLICY_WARNING_CMP0089`` controls the warning for + policy :policy:`CMP0089`. +* ``CMAKE_POLICY_WARNING_CMP0102`` controls the warning for + policy :policy:`CMP0102`. +* ``CMAKE_POLICY_WARNING_CMP0112`` controls the warning for + policy :policy:`CMP0112`. +* ``CMAKE_POLICY_WARNING_CMP0116`` controls the warning for + policy :policy:`CMP0116`. +* ``CMAKE_POLICY_WARNING_CMP0126`` controls the warning for + policy :policy:`CMP0126`. +* ``CMAKE_POLICY_WARNING_CMP0128`` controls the warning for + policy :policy:`CMP0128`. +* ``CMAKE_POLICY_WARNING_CMP0129`` controls the warning for + policy :policy:`CMP0129`. +* ``CMAKE_POLICY_WARNING_CMP0133`` controls the warning for + policy :policy:`CMP0133`. + +This variable should not be set by a project in CMake code. Project +developers running CMake may set this variable in their cache to +enable the warning (e.g. ``-DCMAKE_POLICY_WARNING_CMP<NNNN>=ON``). +Alternatively, running :manual:`cmake(1)` with the +:option:`--debug-output <cmake --debug-output>`, +:option:`--trace <cmake --trace>`, or +:option:`--trace-expand <cmake --trace-expand>` option will also +enable the warning. diff --git a/Help/variable/CMAKE_POSITION_INDEPENDENT_CODE.rst b/Help/variable/CMAKE_POSITION_INDEPENDENT_CODE.rst new file mode 100644 index 0000000..b010317 --- /dev/null +++ b/Help/variable/CMAKE_POSITION_INDEPENDENT_CODE.rst @@ -0,0 +1,9 @@ +CMAKE_POSITION_INDEPENDENT_CODE +------------------------------- + +Default value for :prop_tgt:`POSITION_INDEPENDENT_CODE` of targets. + +This variable is used to initialize the +:prop_tgt:`POSITION_INDEPENDENT_CODE` property on all the targets. +See that target property for additional information. If set, its +value is also used by the :command:`try_compile` command. diff --git a/Help/variable/CMAKE_PREFIX_PATH.rst b/Help/variable/CMAKE_PREFIX_PATH.rst new file mode 100644 index 0000000..1d4fd0b --- /dev/null +++ b/Help/variable/CMAKE_PREFIX_PATH.rst @@ -0,0 +1,15 @@ +CMAKE_PREFIX_PATH +----------------- + +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying installation +*prefixes* to be searched by the :command:`find_package`, +:command:`find_program`, :command:`find_library`, :command:`find_file`, and +:command:`find_path` commands. Each command will add appropriate +subdirectories (like ``bin``, ``lib``, or ``include``) as specified in its own +documentation. + +By default this is empty. It is intended to be set by the project. + +See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`, :variable:`CMAKE_INCLUDE_PATH`, +:variable:`CMAKE_LIBRARY_PATH`, :variable:`CMAKE_PROGRAM_PATH`, and +:variable:`CMAKE_IGNORE_PATH`. diff --git a/Help/variable/CMAKE_PROGRAM_PATH.rst b/Help/variable/CMAKE_PROGRAM_PATH.rst new file mode 100644 index 0000000..2d0c090 --- /dev/null +++ b/Help/variable/CMAKE_PROGRAM_PATH.rst @@ -0,0 +1,7 @@ +CMAKE_PROGRAM_PATH +------------------ + +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path +for the :command:`find_program` command. By default it is empty, it is +intended to be set by the project. See also +:variable:`CMAKE_SYSTEM_PROGRAM_PATH` and :variable:`CMAKE_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst new file mode 100644 index 0000000..95cbe40 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst @@ -0,0 +1,37 @@ +CMAKE_PROJECT_DESCRIPTION +------------------------- + +.. versionadded:: 3.9 + +The description of the top level project. + +This variable holds the description of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. In the event that +the top level CMakeLists.txt contains multiple :command:`project` calls, +the most recently called one from that top level CMakeLists.txt will determine +the value that ``CMAKE_PROJECT_DESCRIPTION`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First DESCRIPTION "I am First") + project(Second DESCRIPTION "I am Second") + add_subdirectory(sub) + project(Third DESCRIPTION "I am Third") + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj DESCRIPTION "I am SubProj") + message("CMAKE_PROJECT_DESCRIPTION = ${CMAKE_PROJECT_DESCRIPTION}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second ...)``, so this will print:: + + CMAKE_PROJECT_DESCRIPTION = I am Second + +To obtain the description from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_DESCRIPTION` +variable. diff --git a/Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst b/Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst new file mode 100644 index 0000000..4c5debe --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst @@ -0,0 +1,37 @@ +CMAKE_PROJECT_HOMEPAGE_URL +-------------------------- + +.. versionadded:: 3.12 + +The homepage URL of the top level project. + +This variable holds the homepage URL of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. In the event that +the top level CMakeLists.txt contains multiple :command:`project` calls, +the most recently called one from that top level CMakeLists.txt will determine +the value that ``CMAKE_PROJECT_HOMEPAGE_URL`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First HOMEPAGE_URL "http://first.example.com") + project(Second HOMEPAGE_URL "http://second.example.com") + add_subdirectory(sub) + project(Third HOMEPAGE_URL "http://third.example.com") + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj HOMEPAGE_URL "http://subproj.example.com") + message("CMAKE_PROJECT_HOMEPAGE_URL = ${CMAKE_PROJECT_HOMEPAGE_URL}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second ...)``, so this will print:: + + CMAKE_PROJECT_HOMEPAGE_URL = http://second.example.com + +To obtain the homepage URL from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_HOMEPAGE_URL` +variable. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE.rst new file mode 100644 index 0000000..76b9d92 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_INCLUDE.rst @@ -0,0 +1,15 @@ +CMAKE_PROJECT_INCLUDE +--------------------- + +.. versionadded:: 3.15 + +A CMake language file or module to be included as the last step of all +:command:`project` command calls. This is intended for injecting custom code +into project builds without modifying their source. See :ref:`Code Injection` +for a more detailed discussion of files potentially included during a +:command:`project` call. + +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, and +:variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables. diff --git a/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst new file mode 100644 index 0000000..9a8c4b5 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst @@ -0,0 +1,15 @@ +CMAKE_PROJECT_INCLUDE_BEFORE +---------------------------- + +.. versionadded:: 3.15 + +A CMake language file or module to be included as the first step of all +:command:`project` command calls. This is intended for injecting custom code +into project builds without modifying their source. See :ref:`Code Injection` +for a more detailed discussion of files potentially included during a +:command:`project` call. + +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_INCLUDE`, and +:variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables. diff --git a/Help/variable/CMAKE_PROJECT_NAME.rst b/Help/variable/CMAKE_PROJECT_NAME.rst new file mode 100644 index 0000000..94b8dba --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_NAME.rst @@ -0,0 +1,35 @@ +CMAKE_PROJECT_NAME +------------------ + +The name of the top level project. + +This variable holds the name of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. In the event that +the top level CMakeLists.txt contains multiple :command:`project` calls, +the most recently called one from that top level CMakeLists.txt will determine +the name that ``CMAKE_PROJECT_NAME`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First) + project(Second) + add_subdirectory(sub) + project(Third) + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj) + message("CMAKE_PROJECT_NAME = ${CMAKE_PROJECT_NAME}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second)``, so this will print:: + + CMAKE_PROJECT_NAME = Second + +To obtain the name from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_NAME` +variable. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst new file mode 100644 index 0000000..3bb5cd8 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst @@ -0,0 +1,12 @@ +CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE +------------------------------------ + +A CMake language file or module to be included as the last step of any +:command:`project` command calls that specify ``<PROJECT-NAME>`` as the project +name. This is intended for injecting custom code into project builds without +modifying their source. See :ref:`Code Injection` for a more detailed +discussion of files potentially included during a :command:`project` call. + +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_INCLUDE`, :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, +and :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables. diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst new file mode 100644 index 0000000..ca584c1 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE.rst @@ -0,0 +1,14 @@ +CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE +------------------------------------------- + +.. versionadded:: 3.17 + +A CMake language file or module to be included as the first step of any +:command:`project` command calls that specify ``<PROJECT-NAME>`` as the project +name. This is intended for injecting custom code into project builds without +modifying their source. See :ref:`Code Injection` for a more detailed +discussion of files potentially included during a :command:`project` call. + +See also the :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +:variable:`CMAKE_PROJECT_INCLUDE`, :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, +and :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variables. diff --git a/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst b/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst new file mode 100644 index 0000000..2010b08 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES.rst @@ -0,0 +1,27 @@ +CMAKE_PROJECT_TOP_LEVEL_INCLUDES +-------------------------------- + +.. versionadded:: 3.24 + +:ref:`Semicolon-separated list <CMake Language Lists>` of CMake language +files to include as part of the very first :command:`project` call. +The files will be included immediately after the toolchain file has been read +(if one is specified) and platform variables have been set, but before any +languages have been enabled. Therefore, language-specific variables, +including things like :variable:`CMAKE_<LANG>_COMPILER`, might not be set. +See :ref:`Code Injection` for a more detailed discussion of files potentially +included during a :command:`project` call. + +This variable is intended for specifying files that perform one-time setup +for the build. It provides an injection point for things like configuring +package managers, adding logic the user shares between projects (e.g. defining +their own custom build types), and so on. It is primarily for users to add +things specific to their environment, but not for specifying the toolchain +details (use :variable:`CMAKE_TOOLCHAIN_FILE` for that). + +By default, this variable is empty. It is intended to be set by the user. + +See also the :variable:`CMAKE_PROJECT_INCLUDE`, +:variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, and +:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables. diff --git a/Help/variable/CMAKE_PROJECT_VERSION.rst b/Help/variable/CMAKE_PROJECT_VERSION.rst new file mode 100644 index 0000000..450c136 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION.rst @@ -0,0 +1,37 @@ +CMAKE_PROJECT_VERSION +--------------------- + +.. versionadded:: 3.12 + +The version of the top level project. + +This variable holds the version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. In the event that +the top level CMakeLists.txt contains multiple :command:`project` calls, +the most recently called one from that top level CMakeLists.txt will determine +the value that ``CMAKE_PROJECT_VERSION`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First VERSION 1.2.3) + project(Second VERSION 3.4.5) + add_subdirectory(sub) + project(Third VERSION 6.7.8) + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj VERSION 1) + message("CMAKE_PROJECT_VERSION = ${CMAKE_PROJECT_VERSION}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second ...)``, so this will print:: + + CMAKE_PROJECT_VERSION = 3.4.5 + +To obtain the version from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_VERSION` +variable. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst b/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst new file mode 100644 index 0000000..c7511e7 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst @@ -0,0 +1,11 @@ +CMAKE_PROJECT_VERSION_MAJOR +--------------------------- + +.. versionadded:: 3.12 + +The major version of the top level project. + +This variable holds the major version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst b/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst new file mode 100644 index 0000000..dd91dcf --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst @@ -0,0 +1,11 @@ +CMAKE_PROJECT_VERSION_MINOR +--------------------------- + +.. versionadded:: 3.12 + +The minor version of the top level project. + +This variable holds the minor version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst b/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst new file mode 100644 index 0000000..61fd1f3 --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst @@ -0,0 +1,11 @@ +CMAKE_PROJECT_VERSION_PATCH +--------------------------- + +.. versionadded:: 3.12 + +The patch version of the top level project. + +This variable holds the patch version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst b/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst new file mode 100644 index 0000000..0deae8b --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst @@ -0,0 +1,11 @@ +CMAKE_PROJECT_VERSION_TWEAK +--------------------------- + +.. versionadded:: 3.12 + +The tweak version of the top level project. + +This variable holds the tweak version of the project as specified in the top +level CMakeLists.txt file by a :command:`project` command. Please see +:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when +multiple :command:`project` commands are used in the sources. diff --git a/Help/variable/CMAKE_RANLIB.rst b/Help/variable/CMAKE_RANLIB.rst new file mode 100644 index 0000000..82672e9 --- /dev/null +++ b/Help/variable/CMAKE_RANLIB.rst @@ -0,0 +1,7 @@ +CMAKE_RANLIB +------------ + +Name of randomizing tool for static libraries. + +This specifies name of the program that randomizes libraries on UNIX, +not used on Windows, but may be present. diff --git a/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst new file mode 100644 index 0000000..893f1ae --- /dev/null +++ b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst @@ -0,0 +1,14 @@ +CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> +---------------------------------------- + +.. versionadded:: 3.22 + +Variable for making :command:`find_package` call ``REQUIRED``. + +Every non-``REQUIRED`` :command:`find_package` call in a project can be +turned into ``REQUIRED`` by setting the variable +``CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>`` to ``TRUE``. +This can be used to assert assumptions about build environment and to +ensure the build will fail early if they do not hold. + +See also the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable. diff --git a/Help/variable/CMAKE_ROOT.rst b/Help/variable/CMAKE_ROOT.rst new file mode 100644 index 0000000..1d0a8af --- /dev/null +++ b/Help/variable/CMAKE_ROOT.rst @@ -0,0 +1,8 @@ +CMAKE_ROOT +---------- + +Install directory for running cmake. + +This is the install root for the running CMake and the ``Modules`` +directory can be found here. This is commonly used in this format: +``${CMAKE_ROOT}/Modules`` diff --git a/Help/variable/CMAKE_RULE_MESSAGES.rst b/Help/variable/CMAKE_RULE_MESSAGES.rst new file mode 100644 index 0000000..39be2e9 --- /dev/null +++ b/Help/variable/CMAKE_RULE_MESSAGES.rst @@ -0,0 +1,10 @@ +CMAKE_RULE_MESSAGES +------------------- + +.. versionadded:: 3.13 + +Specify whether to report a message for each make rule. + +If set in the cache it is used to initialize the value of the :prop_gbl:`RULE_MESSAGES` property. +Users may disable the option in their local build tree to disable granular messages +and report only as each target completes in Makefile builds. diff --git a/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..6253d4a --- /dev/null +++ b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst @@ -0,0 +1,9 @@ +CMAKE_RUNTIME_OUTPUT_DIRECTORY +------------------------------ + +Where to put all the :ref:`RUNTIME <Runtime Output Artifacts>` +target files when built. + +This variable is used to initialize the :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..c9c55c5 --- /dev/null +++ b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,11 @@ +CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------------- + +.. versionadded:: 3.3 + +Where to put all the :ref:`RUNTIME <Runtime Output Artifacts>` +target files when built for a specific configuration. + +This variable is used to initialize the +:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY_<CONFIG>` property on all the targets. +See that target property for additional information. diff --git a/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst b/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst new file mode 100644 index 0000000..313fb4e --- /dev/null +++ b/Help/variable/CMAKE_SCRIPT_MODE_FILE.rst @@ -0,0 +1,9 @@ +CMAKE_SCRIPT_MODE_FILE +---------------------- + +Full path to the :option:`cmake -P` script file currently being +processed. + +When run in :option:`cmake -P` script mode, CMake sets this variable to +the full path of the script file. When run to configure a ``CMakeLists.txt`` +file, this variable is not set. diff --git a/Help/variable/CMAKE_SHARED_LIBRARY_PREFIX.rst b/Help/variable/CMAKE_SHARED_LIBRARY_PREFIX.rst new file mode 100644 index 0000000..8afabaf --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LIBRARY_PREFIX.rst @@ -0,0 +1,8 @@ +CMAKE_SHARED_LIBRARY_PREFIX +--------------------------- + +The prefix for shared libraries that you link to. + +The prefix to use for the name of a shared library, ``lib`` on UNIX. + +``CMAKE_SHARED_LIBRARY_PREFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_SHARED_LIBRARY_SUFFIX.rst b/Help/variable/CMAKE_SHARED_LIBRARY_SUFFIX.rst new file mode 100644 index 0000000..1f96a32 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LIBRARY_SUFFIX.rst @@ -0,0 +1,9 @@ +CMAKE_SHARED_LIBRARY_SUFFIX +--------------------------- + +The suffix for shared libraries that you link to. + +The suffix to use for the end of a shared library filename, ``.dll`` on +Windows. + +``CMAKE_SHARED_LIBRARY_SUFFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS.rst new file mode 100644 index 0000000..fce950c --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS.rst @@ -0,0 +1,6 @@ +CMAKE_SHARED_LINKER_FLAGS +------------------------- + +Linker flags to be used to create shared libraries. + +These flags will be used by the linker when creating a shared library. diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG.rst new file mode 100644 index 0000000..4bf87a0 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG.rst @@ -0,0 +1,7 @@ +CMAKE_SHARED_LINKER_FLAGS_<CONFIG> +---------------------------------- + +Flags to be used when linking a shared library. + +Same as ``CMAKE_C_FLAGS_*`` but used by the linker when creating shared +libraries. diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..7f3dec7 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,12 @@ +CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_SHARED_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_SHARED_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..6d51afe --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst @@ -0,0 +1,13 @@ +CMAKE_SHARED_LINKER_FLAGS_INIT +------------------------------ + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_SHARED_LINKER_FLAGS` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also the configuration-specific variable +:variable:`CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_SHARED_MODULE_PREFIX.rst b/Help/variable/CMAKE_SHARED_MODULE_PREFIX.rst new file mode 100644 index 0000000..d6eef98 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_MODULE_PREFIX.rst @@ -0,0 +1,8 @@ +CMAKE_SHARED_MODULE_PREFIX +-------------------------- + +The prefix for loadable modules that you link to. + +The prefix to use for the name of a loadable module on this platform. + +``CMAKE_SHARED_MODULE_PREFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_SHARED_MODULE_SUFFIX.rst b/Help/variable/CMAKE_SHARED_MODULE_SUFFIX.rst new file mode 100644 index 0000000..81515c3 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_MODULE_SUFFIX.rst @@ -0,0 +1,9 @@ +CMAKE_SHARED_MODULE_SUFFIX +-------------------------- + +The suffix for shared libraries that you link to. + +The suffix to use for the end of a loadable module filename on this +platform + +``CMAKE_SHARED_MODULE_SUFFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_SIZEOF_VOID_P.rst b/Help/variable/CMAKE_SIZEOF_VOID_P.rst new file mode 100644 index 0000000..f5464d1 --- /dev/null +++ b/Help/variable/CMAKE_SIZEOF_VOID_P.rst @@ -0,0 +1,8 @@ +CMAKE_SIZEOF_VOID_P +------------------- + +Size of a ``void`` pointer. + +This is set to the size of a pointer on the target machine, and is determined +by a try compile. If a 64-bit size is found, then the library search +path is modified to look for 64-bit libraries first. diff --git a/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst b/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst new file mode 100644 index 0000000..dd3e2a0 --- /dev/null +++ b/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst @@ -0,0 +1,18 @@ +CMAKE_SKIP_BUILD_RPATH +---------------------- + +Do not include RPATHs in the build tree. + +Normally CMake uses the build tree for the RPATH when building +executables etc on systems that use RPATH. When the software is +installed the executables etc are relinked by CMake to have the +install RPATH. If this variable is set to ``TRUE`` then the software is +always built with no RPATH. + +This is used to initialize the :prop_tgt:`SKIP_BUILD_RPATH` target property +for all targets. For more information on RPATH handling see +the :prop_tgt:`INSTALL_RPATH` and :prop_tgt:`BUILD_RPATH` target properties. + +See also the :variable:`CMAKE_SKIP_INSTALL_RPATH` variable. +To omit RPATH in both the build and install steps, use +:variable:`CMAKE_SKIP_RPATH` instead. diff --git a/Help/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY.rst b/Help/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY.rst new file mode 100644 index 0000000..e88db36 --- /dev/null +++ b/Help/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY.rst @@ -0,0 +1,11 @@ +CMAKE_SKIP_INSTALL_ALL_DEPENDENCY +--------------------------------- + +Don't make the ``install`` target depend on the ``all`` target. + +By default, the ``install`` target depends on the ``all`` target. This +has the effect, that when ``make install`` is invoked or ``INSTALL`` is +built, first the ``all`` target is built, then the installation starts. +If ``CMAKE_SKIP_INSTALL_ALL_DEPENDENCY`` is set to ``TRUE``, this +dependency is not created, so the installation process will start immediately, +independent from whether the project has been completely built or not. diff --git a/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst b/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst new file mode 100644 index 0000000..465fdae --- /dev/null +++ b/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst @@ -0,0 +1,19 @@ +CMAKE_SKIP_INSTALL_RPATH +------------------------ + +Do not include RPATHs in the install tree. + +Normally CMake uses the build tree for the RPATH when building +executables etc on systems that use RPATH. When the software is +installed the executables etc are relinked by CMake to have the +install RPATH. If this variable is set to true then the software is +always installed without RPATH, even if RPATH is enabled when +building. This can be useful for example to allow running tests from +the build directory with RPATH enabled before the installation step. + +See also the :variable:`CMAKE_SKIP_BUILD_RPATH` variable. +To omit RPATH in both the build and install steps, use +:variable:`CMAKE_SKIP_RPATH` instead. + +For more information on RPATH handling see the :prop_tgt:`INSTALL_RPATH` +and :prop_tgt:`BUILD_RPATH` target properties. diff --git a/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst b/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst new file mode 100644 index 0000000..b77bb68 --- /dev/null +++ b/Help/variable/CMAKE_SKIP_INSTALL_RULES.rst @@ -0,0 +1,8 @@ +CMAKE_SKIP_INSTALL_RULES +------------------------ + +Whether to disable generation of installation rules. + +If ``TRUE``, CMake will neither generate installation rules nor +will it generate ``cmake_install.cmake`` files. This variable is ``FALSE`` by +default. diff --git a/Help/variable/CMAKE_SKIP_RPATH.rst b/Help/variable/CMAKE_SKIP_RPATH.rst new file mode 100644 index 0000000..43f6401 --- /dev/null +++ b/Help/variable/CMAKE_SKIP_RPATH.rst @@ -0,0 +1,14 @@ +CMAKE_SKIP_RPATH +---------------- + +If true, do not add run time path information. + +If this is set to ``TRUE``, then the rpath information is not added to +compiled executables. The default is to add rpath information if the +platform supports it. This allows for easy running from the build +tree. To omit RPATH in the install step, but not the build step, use +:variable:`CMAKE_SKIP_INSTALL_RPATH` instead. To omit RPATH in the build step, +use :variable:`CMAKE_SKIP_BUILD_RPATH`. + +For more information on RPATH handling see the :prop_tgt:`INSTALL_RPATH` +and :prop_tgt:`BUILD_RPATH` target properties. diff --git a/Help/variable/CMAKE_SOURCE_DIR.rst b/Help/variable/CMAKE_SOURCE_DIR.rst new file mode 100644 index 0000000..f1d1bee --- /dev/null +++ b/Help/variable/CMAKE_SOURCE_DIR.rst @@ -0,0 +1,13 @@ +CMAKE_SOURCE_DIR +---------------- + +The path to the top level of the source tree. + +This is the full path to the top level of the current CMake source +tree. For an in-source build, this would be the same as +:variable:`CMAKE_BINARY_DIR`. + +When run in :option:`cmake -P` script mode, CMake sets the variables +:variable:`CMAKE_BINARY_DIR`, ``CMAKE_SOURCE_DIR``, +:variable:`CMAKE_CURRENT_BINARY_DIR` and +:variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Help/variable/CMAKE_STAGING_PREFIX.rst b/Help/variable/CMAKE_STAGING_PREFIX.rst new file mode 100644 index 0000000..7b1048b --- /dev/null +++ b/Help/variable/CMAKE_STAGING_PREFIX.rst @@ -0,0 +1,14 @@ +CMAKE_STAGING_PREFIX +-------------------- + +This variable may be set to a path to install to when cross-compiling. This can +be useful if the path in :variable:`CMAKE_SYSROOT` is read-only, or otherwise +should remain pristine. + +The ``CMAKE_STAGING_PREFIX`` location is also used as a search prefix +by the ``find_*`` commands. This can be controlled by setting the +:variable:`CMAKE_FIND_NO_INSTALL_PREFIX` variable. + +If any ``RPATH``/``RUNPATH`` entries passed to the linker contain the +``CMAKE_STAGING_PREFIX``, the matching path fragments are replaced +with the :variable:`CMAKE_INSTALL_PREFIX`. diff --git a/Help/variable/CMAKE_STATIC_LIBRARY_PREFIX.rst b/Help/variable/CMAKE_STATIC_LIBRARY_PREFIX.rst new file mode 100644 index 0000000..714b5cc --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LIBRARY_PREFIX.rst @@ -0,0 +1,8 @@ +CMAKE_STATIC_LIBRARY_PREFIX +--------------------------- + +The prefix for static libraries that you link to. + +The prefix to use for the name of a static library, ``lib`` on UNIX. + +``CMAKE_STATIC_LIBRARY_PREFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_STATIC_LIBRARY_SUFFIX.rst b/Help/variable/CMAKE_STATIC_LIBRARY_SUFFIX.rst new file mode 100644 index 0000000..28dc09d --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LIBRARY_SUFFIX.rst @@ -0,0 +1,9 @@ +CMAKE_STATIC_LIBRARY_SUFFIX +--------------------------- + +The suffix for static libraries that you link to. + +The suffix to use for the end of a static library filename, ``.lib`` on +Windows. + +``CMAKE_STATIC_LIBRARY_SUFFIX_<LANG>`` overrides this for language ``<LANG>``. diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst new file mode 100644 index 0000000..1a810ce --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS.rst @@ -0,0 +1,12 @@ +CMAKE_STATIC_LINKER_FLAGS +------------------------- + +Flags to be used to create static libraries. These flags will be passed +to the archiver when creating a static library. + +See also :variable:`CMAKE_STATIC_LINKER_FLAGS_<CONFIG>`. + +.. note:: + Static libraries do not actually link. They are essentially archives + of object files. The use of the name "linker" in the name of this + variable is kept for compatibility. diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG.rst new file mode 100644 index 0000000..e561dc6 --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG.rst @@ -0,0 +1,13 @@ +CMAKE_STATIC_LINKER_FLAGS_<CONFIG> +---------------------------------- + +Flags to be used to create static libraries. These flags will be passed +to the archiver when creating a static library in the ``<CONFIG>`` +configuration. + +See also :variable:`CMAKE_STATIC_LINKER_FLAGS`. + +.. note:: + Static libraries do not actually link. They are essentially archives + of object files. The use of the name "linker" in the name of this + variable is kept for compatibility. diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..5e65ef2 --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,12 @@ +CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_STATIC_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_STATIC_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..cbf681c --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst @@ -0,0 +1,13 @@ +CMAKE_STATIC_LINKER_FLAGS_INIT +------------------------------ + +.. versionadded:: 3.7 + +Value used to initialize the :variable:`CMAKE_STATIC_LINKER_FLAGS` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also the configuration-specific variable +:variable:`CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS.rst b/Help/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS.rst new file mode 100644 index 0000000..5c1c8d1 --- /dev/null +++ b/Help/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS.rst @@ -0,0 +1,27 @@ +CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS +--------------------------------- + +.. versionadded:: 3.8 + +This variable contains a list of env vars as a list of tokens with the +syntax ``var=value``. + +Example: + +.. code-block:: cmake + + set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS + "FOO=FOO1\;FOO2\;FOON" + "BAR=BAR1\;BAR2\;BARN" + "BAZ=BAZ1\;BAZ2\;BAZN" + "FOOBAR=FOOBAR1\;FOOBAR2\;FOOBARN" + "VALID=" + ) + +In case of malformed variables CMake will fail: + +.. code-block:: cmake + + set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS + "THIS_IS_NOT_VALID" + ) diff --git a/Help/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE.rst b/Help/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE.rst new file mode 100644 index 0000000..28b0dbd --- /dev/null +++ b/Help/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE.rst @@ -0,0 +1,9 @@ +CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE +--------------------------------------- + +.. versionadded:: 3.8 + +If this variable evaluates to ``ON`` at the end of the top-level +``CMakeLists.txt`` file, the :generator:`Sublime Text 2` extra generator +excludes the build tree from the ``.sublime-project`` if it is inside the +source tree. diff --git a/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst b/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst new file mode 100644 index 0000000..48490ff --- /dev/null +++ b/Help/variable/CMAKE_SUPPRESS_REGENERATION.rst @@ -0,0 +1,13 @@ +CMAKE_SUPPRESS_REGENERATION +--------------------------- + +.. versionadded:: 3.12 + +If ``CMAKE_SUPPRESS_REGENERATION`` is ``OFF``, which is default, then CMake +adds a special target on which all other targets depend that checks the build +system and optionally re-runs CMake to regenerate the build system when +the target specification source changes. + +If this variable evaluates to ``ON`` at the end of the top-level +``CMakeLists.txt`` file, CMake will not add the regeneration target to the +build system or perform any build system checks. diff --git a/Help/variable/CMAKE_SYSROOT.rst b/Help/variable/CMAKE_SYSROOT.rst new file mode 100644 index 0000000..35b944f --- /dev/null +++ b/Help/variable/CMAKE_SYSROOT.rst @@ -0,0 +1,15 @@ +CMAKE_SYSROOT +------------- + +Path to pass to the compiler in the ``--sysroot`` flag. + +The ``CMAKE_SYSROOT`` content is passed to the compiler in the ``--sysroot`` +flag, if supported. The path is also stripped from the ``RPATH``/``RUNPATH`` +if necessary on installation. The ``CMAKE_SYSROOT`` is also used to prefix +paths searched by the ``find_*`` commands. + +This variable may only be set in a toolchain file specified by +the :variable:`CMAKE_TOOLCHAIN_FILE` variable. + +See also the :variable:`CMAKE_SYSROOT_COMPILE` and +:variable:`CMAKE_SYSROOT_LINK` variables. diff --git a/Help/variable/CMAKE_SYSROOT_COMPILE.rst b/Help/variable/CMAKE_SYSROOT_COMPILE.rst new file mode 100644 index 0000000..4aea48e --- /dev/null +++ b/Help/variable/CMAKE_SYSROOT_COMPILE.rst @@ -0,0 +1,11 @@ +CMAKE_SYSROOT_COMPILE +--------------------- + +.. versionadded:: 3.9 + +Path to pass to the compiler in the ``--sysroot`` flag when compiling source +files. This is the same as :variable:`CMAKE_SYSROOT` but is used only for +compiling sources and not linking. + +This variable may only be set in a toolchain file specified by +the :variable:`CMAKE_TOOLCHAIN_FILE` variable. diff --git a/Help/variable/CMAKE_SYSROOT_LINK.rst b/Help/variable/CMAKE_SYSROOT_LINK.rst new file mode 100644 index 0000000..9749b7b --- /dev/null +++ b/Help/variable/CMAKE_SYSROOT_LINK.rst @@ -0,0 +1,11 @@ +CMAKE_SYSROOT_LINK +------------------ + +.. versionadded:: 3.9 + +Path to pass to the compiler in the ``--sysroot`` flag when linking. This is +the same as :variable:`CMAKE_SYSROOT` but is used only for linking and not +compiling sources. + +This variable may only be set in a toolchain file specified by +the :variable:`CMAKE_TOOLCHAIN_FILE` variable. diff --git a/Help/variable/CMAKE_SYSTEM.rst b/Help/variable/CMAKE_SYSTEM.rst new file mode 100644 index 0000000..c7d0d8a --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM.rst @@ -0,0 +1,10 @@ +CMAKE_SYSTEM +------------ + +Composite name of operating system CMake is compiling for. + +This variable is the composite of :variable:`CMAKE_SYSTEM_NAME` and +:variable:`CMAKE_SYSTEM_VERSION`, e.g. +``${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_VERSION}``. If +:variable:`CMAKE_SYSTEM_VERSION` is not set, then this variable is +the same as :variable:`CMAKE_SYSTEM_NAME`. diff --git a/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst b/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst new file mode 100644 index 0000000..06a99a8 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst @@ -0,0 +1,9 @@ +CMAKE_SYSTEM_APPBUNDLE_PATH +--------------------------- + +.. versionadded:: 3.4 + +Search path for macOS application bundles used by the :command:`find_program`, +and :command:`find_package` commands. By default it contains the standard +directories for the current system. It is *not* intended to be modified by +the project, use :variable:`CMAKE_APPBUNDLE_PATH` for this. diff --git a/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst b/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst new file mode 100644 index 0000000..1a402c1 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst @@ -0,0 +1,10 @@ +CMAKE_SYSTEM_FRAMEWORK_PATH +--------------------------- + +.. versionadded:: 3.4 + +Search path for macOS frameworks used by the :command:`find_library`, +:command:`find_package`, :command:`find_path`, and :command:`find_file` +commands. By default it contains the standard directories for the +current system. It is *not* intended to be modified by the project, +use :variable:`CMAKE_FRAMEWORK_PATH` for this. diff --git a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst new file mode 100644 index 0000000..a6d8016 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst @@ -0,0 +1,18 @@ +CMAKE_SYSTEM_IGNORE_PATH +------------------------ + +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_SYSTEM_IGNORE_PATH`` +.. |CMAKE_IGNORE_PREFIX_VAR| replace:: :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` +.. |CMAKE_IGNORE_NONSYSTEM_VAR| replace:: :variable:`CMAKE_IGNORE_PATH` + +.. include:: IGNORE_SEARCH_PATH.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_SYSTEM.txt + +See also the following variables: + +- :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_LIBRARY_PATH` +- :variable:`CMAKE_SYSTEM_INCLUDE_PATH` +- :variable:`CMAKE_SYSTEM_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst new file mode 100644 index 0000000..48a2994 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst @@ -0,0 +1,20 @@ +CMAKE_SYSTEM_IGNORE_PREFIX_PATH +------------------------------- + +.. versionadded:: 3.23 + +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_SYSTEM_IGNORE_PREFIX_PATH`` +.. |CMAKE_IGNORE_NONPREFIX_VAR| replace:: :variable:`CMAKE_SYSTEM_IGNORE_PATH` +.. |CMAKE_IGNORE_NONSYSTEM_VAR| replace:: :variable:`CMAKE_IGNORE_PREFIX_PATH` + +.. include:: IGNORE_SEARCH_PREFIX.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_SYSTEM.txt + +See also the following variables: + +- :variable:`CMAKE_SYSTEM_IGNORE_PATH` +- :variable:`CMAKE_SYSTEM_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_LIBRARY_PATH` +- :variable:`CMAKE_SYSTEM_INCLUDE_PATH` +- :variable:`CMAKE_SYSTEM_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst new file mode 100644 index 0000000..680404e --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_INCLUDE_PATH +------------------------- + +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path +for the :command:`find_file` and :command:`find_path` commands. By default +this contains the standard directories for the current system. It is *not* +intended to be modified by the project; use :variable:`CMAKE_INCLUDE_PATH` for +this. See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst b/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst new file mode 100644 index 0000000..116832b --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_LIBRARY_PATH +------------------------- + +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path +for the :command:`find_library` command. By default this contains the +standard directories for the current system. It is *not* intended to be +modified by the project; use :variable:`CMAKE_LIBRARY_PATH` for this. +See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_SYSTEM_NAME.rst b/Help/variable/CMAKE_SYSTEM_NAME.rst new file mode 100644 index 0000000..fef53ee --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_NAME.rst @@ -0,0 +1,23 @@ +CMAKE_SYSTEM_NAME +----------------- + +The name of the operating system for which CMake is to build. +See the :variable:`CMAKE_SYSTEM_VERSION` variable for the OS version. + +Note that ``CMAKE_SYSTEM_NAME`` is not set to anything by default when running +in script mode, since it's not building anything. + +System Name for Host Builds +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CMAKE_SYSTEM_NAME`` is by default set to the same value as the +:variable:`CMAKE_HOST_SYSTEM_NAME` variable so that the build +targets the host system. + +System Name for Cross Compiling +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``CMAKE_SYSTEM_NAME`` may be set explicitly when first configuring a new build +tree in order to enable :ref:`cross compiling <Cross Compiling Toolchain>`. +In this case the :variable:`CMAKE_SYSTEM_VERSION` variable must also be +set explicitly. diff --git a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst new file mode 100644 index 0000000..c8b5815 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst @@ -0,0 +1,54 @@ +CMAKE_SYSTEM_PREFIX_PATH +------------------------ + +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying installation +*prefixes* to be searched by the :command:`find_package`, +:command:`find_program`, :command:`find_library`, :command:`find_file`, and +:command:`find_path` commands. Each command will add appropriate +subdirectories (like ``bin``, ``lib``, or ``include``) as specified in its own +documentation. + +By default this contains the system directories for the current system, the +:variable:`CMAKE_INSTALL_PREFIX`, and the :variable:`CMAKE_STAGING_PREFIX`. +The installation and staging prefixes may be excluded by setting +the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` variable before the +first :command:`project` invocation. + +The system directories that are contained in ``CMAKE_SYSTEM_PREFIX_PATH`` are +locations that typically include installed software. An example being +``/usr/local`` for UNIX based platforms. In addition to standard platform +locations, CMake will also add values to ``CMAKE_SYSTEM_PREFIX_PATH`` based on +environment variables. The environment variables and search locations that +CMake uses may evolve over time, as platforms and their conventions also +evolve. The following provides an indicative list of environment variables +and locations that CMake searches, but they are subject to change: + + +CrayLinuxEnvironment: + * ``ENV{SYSROOT_DIR}/`` + * ``ENV{SYSROOT_DIR}/usr`` + * ``ENV{SYSROOT_DIR}/usr/local`` + +Darwin: + * ``ENV{SDKROOT}/usr`` When ``CMAKE_OSX_SYSROOT`` is not explicitly specified. + +OpenBSD: + * ``ENV{LOCALBASE}`` + +Unix: + * ``ENV{CONDA_PREFIX}`` when using a conda compiler + +Windows: + * ``ENV{ProgramW6432}`` + * ``ENV{ProgramFiles}`` + * ``ENV{ProgramFiles(x86)}`` + * ``ENV{SystemDrive}/Program Files`` + * ``ENV{SystemDrive}/Program Files (x86)`` + + +``CMAKE_SYSTEM_PREFIX_PATH`` is *not* intended to be modified by the project; +use :variable:`CMAKE_PREFIX_PATH` for this. + +See also :variable:`CMAKE_SYSTEM_INCLUDE_PATH`, +:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_PROGRAM_PATH`, +and :variable:`CMAKE_SYSTEM_IGNORE_PATH`. diff --git a/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst new file mode 100644 index 0000000..ce16215 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst @@ -0,0 +1,13 @@ +CMAKE_SYSTEM_PROCESSOR +---------------------- + +When not cross-compiling, this variable has the same value as the +:variable:`CMAKE_HOST_SYSTEM_PROCESSOR` variable. In many cases, +this will correspond to the target architecture for the build, but +this is not guaranteed. (E.g. on Windows, the host may be ``AMD64`` +even when using a MSVC ``cl`` compiler with a 32-bit target.) + +When cross-compiling, a :variable:`CMAKE_TOOLCHAIN_FILE` should set +the ``CMAKE_SYSTEM_PROCESSOR`` variable to match target architecture +that it specifies (via :variable:`CMAKE_<LANG>_COMPILER` and perhaps +:variable:`CMAKE_<LANG>_COMPILER_TARGET`). diff --git a/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst new file mode 100644 index 0000000..9b70361 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_SYSTEM_PROGRAM_PATH +------------------------- + +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path +for the :command:`find_program` command. By default this contains the +standard directories for the current system. It is *not* intended to be +modified by the project; use :variable:`CMAKE_PROGRAM_PATH` for this. +See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_SYSTEM_VERSION.rst b/Help/variable/CMAKE_SYSTEM_VERSION.rst new file mode 100644 index 0000000..aba8ca3 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_VERSION.rst @@ -0,0 +1,28 @@ +CMAKE_SYSTEM_VERSION +-------------------- + +The version of the operating system for which CMake is to build. +See the :variable:`CMAKE_SYSTEM_NAME` variable for the OS name. + +System Version for Host Builds +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When the :variable:`CMAKE_SYSTEM_NAME` variable takes its default value +then ``CMAKE_SYSTEM_VERSION`` is by default set to the same value as the +:variable:`CMAKE_HOST_SYSTEM_VERSION` variable so that the build targets +the host system version. + +In the case of a host build then ``CMAKE_SYSTEM_VERSION`` may be set +explicitly when first configuring a new build tree in order to enable +targeting the build for a different version of the host operating system +than is actually running on the host. This is allowed and not considered +cross compiling so long as the binaries built for the specified OS version +can still run on the host. + +System Version for Cross Compiling +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When the :variable:`CMAKE_SYSTEM_NAME` variable is set explicitly to +enable :ref:`cross compiling <Cross Compiling Toolchain>` then the +value of ``CMAKE_SYSTEM_VERSION`` must also be set explicitly to specify +the target system version. diff --git a/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst b/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst new file mode 100644 index 0000000..fce6fa7 --- /dev/null +++ b/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst @@ -0,0 +1,11 @@ +CMAKE_Swift_LANGUAGE_VERSION +---------------------------- + +.. versionadded:: 3.7 + +Set to the Swift language version number. If not set, the oldest legacy +version known to be available in the host Xcode version is assumed: + +* Swift ``4.0`` for Xcode 10.2 and above. +* Swift ``3.0`` for Xcode 8.3 and above. +* Swift ``2.3`` for Xcode 8.2 and below. diff --git a/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst b/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst new file mode 100644 index 0000000..6036c04 --- /dev/null +++ b/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst @@ -0,0 +1,10 @@ +CMAKE_Swift_MODULE_DIRECTORY +---------------------------- + +.. versionadded:: 3.15 + +Swift module output directory. + +This variable is used to initialize the :prop_tgt:`Swift_MODULE_DIRECTORY` +property on all the targets. See the target property for additional +information. diff --git a/Help/variable/CMAKE_Swift_NUM_THREADS.rst b/Help/variable/CMAKE_Swift_NUM_THREADS.rst new file mode 100644 index 0000000..e1dafb0 --- /dev/null +++ b/Help/variable/CMAKE_Swift_NUM_THREADS.rst @@ -0,0 +1,10 @@ +CMAKE_Swift_NUM_THREADS +----------------------- + +.. versionadded:: 3.15.1 + +Number of threads for parallel compilation for Swift targets. + +This variable controls the number of parallel jobs that the swift driver creates +for building targets. If not specified, it will default to the number of +logical CPUs on the host. diff --git a/Help/variable/CMAKE_TASKING_TOOLSET.rst b/Help/variable/CMAKE_TASKING_TOOLSET.rst new file mode 100644 index 0000000..53b2c09 --- /dev/null +++ b/Help/variable/CMAKE_TASKING_TOOLSET.rst @@ -0,0 +1,34 @@ +CMAKE_TASKING_TOOLSET +--------------------- + +.. versionadded:: 3.25 + +Select the Tasking toolset which provides the compiler + +Architecture compilers are provided by different toolchains with +incompatible versioning schemes. Set this variable in a +:variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` so CMake can detect +the compiler features correctly. If no toolset is specified, +``Standalone`` is assumed. + +Due to the different versioning schemes, the compiler version +(:variable:`CMAKE_<LANG>_COMPILER_VERSION`) depends on the toolset and +architecture in use. If projects can be built with multiple toolsets or +architectures, the specified ``CMAKE_TASKING_TOOLSET`` and the +automatically determined :variable:`CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID` +must be taken into account when comparing against the +:variable:`CMAKE_<LANG>_COMPILER_VERSION`. + +``TriCore`` + Compilers are provided by the TriCore toolset. + +``SmartCode`` + Compilers are provided by the SmartCode toolset. + +``Standalone`` + Compilers are provided by the standalone toolsets. + + .. note:: + + For the TriCore architecture, the compiler from the TriCore toolset is + selected as standalone compiler. diff --git a/Help/variable/CMAKE_TLS_CAINFO.rst b/Help/variable/CMAKE_TLS_CAINFO.rst new file mode 100644 index 0000000..07f6366 --- /dev/null +++ b/Help/variable/CMAKE_TLS_CAINFO.rst @@ -0,0 +1,9 @@ +CMAKE_TLS_CAINFO +---------------- + +Specify the default value for the :command:`file(DOWNLOAD)` and +:command:`file(UPLOAD)` commands' ``TLS_CAINFO`` options. +It is unset by default. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. diff --git a/Help/variable/CMAKE_TLS_VERIFY.rst b/Help/variable/CMAKE_TLS_VERIFY.rst new file mode 100644 index 0000000..b22f1ce --- /dev/null +++ b/Help/variable/CMAKE_TLS_VERIFY.rst @@ -0,0 +1,17 @@ +CMAKE_TLS_VERIFY +---------------- + +Specify the default value for the :command:`file(DOWNLOAD)` and +:command:`file(UPLOAD)` commands' ``TLS_VERIFY`` options. +If not set, the default is *off*. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. + +TLS verification can help provide confidence that one is connecting +to the desired server. When downloading known content, one should +also use file hashes to verify it. + +.. code-block:: cmake + + set(CMAKE_TLS_VERIFY TRUE) diff --git a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst new file mode 100644 index 0000000..1117c1f --- /dev/null +++ b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst @@ -0,0 +1,18 @@ +CMAKE_TOOLCHAIN_FILE +-------------------- + +Path to toolchain file supplied to :manual:`cmake(1)`. + +This variable is specified on the command line when cross-compiling with CMake. +It is the path to a file which is read early in the CMake run and which +specifies locations for compilers and toolchain utilities, and other target +platform and compiler related information. + +Relative paths are allowed and are interpreted first as relative to the +build directory, and if not found, relative to the source directory. + +This is initialized by the :envvar:`CMAKE_TOOLCHAIN_FILE` environment +variable if it is set when a new build tree is first created. + +See the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable for setting +other things not directly related to the toolchain. diff --git a/Help/variable/CMAKE_TRY_COMPILE_CONFIGURATION.rst b/Help/variable/CMAKE_TRY_COMPILE_CONFIGURATION.rst new file mode 100644 index 0000000..d731f02 --- /dev/null +++ b/Help/variable/CMAKE_TRY_COMPILE_CONFIGURATION.rst @@ -0,0 +1,10 @@ +CMAKE_TRY_COMPILE_CONFIGURATION +------------------------------- + +Build configuration used for :command:`try_compile` and :command:`try_run` +projects. + +Projects built by :command:`try_compile` and :command:`try_run` are built +synchronously during the CMake configuration step. Therefore a specific build +configuration must be chosen even if the generated build system +supports multiple configurations. diff --git a/Help/variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES.rst b/Help/variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES.rst new file mode 100644 index 0000000..c68a36c --- /dev/null +++ b/Help/variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES.rst @@ -0,0 +1,12 @@ +CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES +--------------------------------------- + +.. versionadded:: 3.24 + +Set to a true value to tell the :command:`try_compile` command not +to propagate any platform variables into the test project. + +The :command:`try_compile` command normally passes some CMake variables +that configure the platform and toolchain behavior into test projects. +See policy :policy:`CMP0137`. This variable may be set to disable +that behavior. diff --git a/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst b/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst new file mode 100644 index 0000000..6b26d14 --- /dev/null +++ b/Help/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES.rst @@ -0,0 +1,37 @@ +CMAKE_TRY_COMPILE_PLATFORM_VARIABLES +------------------------------------ + +.. versionadded:: 3.6 + +List of variables that the :command:`try_compile` command source file signature +must propagate into the test project in order to target the same platform as +the host project. + +This variable should not be set by project code. It is meant to be set by +CMake's platform information modules for the current toolchain, or by a +toolchain file when used with :variable:`CMAKE_TOOLCHAIN_FILE`. + +Variables meaningful to CMake, such as :variable:`CMAKE_<LANG>_FLAGS`, are +propagated automatically. The ``CMAKE_TRY_COMPILE_PLATFORM_VARIABLES`` +variable may be set to pass custom variables meaningful to a toolchain file. +For example, a toolchain file may contain: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME ...) + set(CMAKE_TRY_COMPILE_PLATFORM_VARIABLES MY_CUSTOM_VARIABLE) + # ... use MY_CUSTOM_VARIABLE ... + +If a user passes ``-DMY_CUSTOM_VARIABLE=SomeValue`` to CMake then this +setting will be made visible to the toolchain file both for the main +project and for test projects generated by the :command:`try_compile` +command source file signature. + +.. versionchanged:: 3.24 + Listed variables are propagated to the :command:`try_compile` + :ref:`whole-project <Try Compiling Whole Projects>` signature too. + See :policy:`CMP0137`. + +.. versionadded:: 3.24 + The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be + set to disable passing platform variables into the test project. diff --git a/Help/variable/CMAKE_TRY_COMPILE_TARGET_TYPE.rst b/Help/variable/CMAKE_TRY_COMPILE_TARGET_TYPE.rst new file mode 100644 index 0000000..b60539f --- /dev/null +++ b/Help/variable/CMAKE_TRY_COMPILE_TARGET_TYPE.rst @@ -0,0 +1,17 @@ +CMAKE_TRY_COMPILE_TARGET_TYPE +----------------------------- + +.. versionadded:: 3.6 + +Type of target generated for :command:`try_compile` calls using the +source file signature. Valid values are: + +``EXECUTABLE`` + Use :command:`add_executable` to name the source file in the + generated project. This is the default if no value is given. + +``STATIC_LIBRARY`` + Use :command:`add_library` with the ``STATIC`` option to name the + source file in the generated project. This avoids running the + linker and is intended for use with cross-compiling toolchains + that cannot link without custom flags or linker scripts. diff --git a/Help/variable/CMAKE_TWEAK_VERSION.rst b/Help/variable/CMAKE_TWEAK_VERSION.rst new file mode 100644 index 0000000..be2e050 --- /dev/null +++ b/Help/variable/CMAKE_TWEAK_VERSION.rst @@ -0,0 +1,11 @@ +CMAKE_TWEAK_VERSION +------------------- + +Defined to ``0`` for compatibility with code written for older +CMake versions that may have defined higher values. + +.. note:: + + In CMake versions 2.8.2 through 2.8.12, this variable holds + the fourth version number component of the + :variable:`CMAKE_VERSION` variable. diff --git a/Help/variable/CMAKE_UNITY_BUILD.rst b/Help/variable/CMAKE_UNITY_BUILD.rst new file mode 100644 index 0000000..54a781a --- /dev/null +++ b/Help/variable/CMAKE_UNITY_BUILD.rst @@ -0,0 +1,22 @@ +CMAKE_UNITY_BUILD +----------------- + +.. versionadded:: 3.16 + +This variable is used to initialize the :prop_tgt:`UNITY_BUILD` +property of targets when they are created. Setting it to true +enables batch compilation of multiple sources within each target. +This feature is known as a *Unity* or *Jumbo* build. + +Projects should not set this variable, it is intended as a developer +control to be set on the :manual:`cmake(1)` command line or other +equivalent methods. The developer must have the ability to enable or +disable unity builds according to the capabilities of their own machine +and compiler. + +By default, this variable is not set, which will result in unity builds +being disabled. + +.. note:: + This option currently does not work well in combination with + the :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable. diff --git a/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst new file mode 100644 index 0000000..7733fe8 --- /dev/null +++ b/Help/variable/CMAKE_UNITY_BUILD_BATCH_SIZE.rst @@ -0,0 +1,9 @@ +CMAKE_UNITY_BUILD_BATCH_SIZE +---------------------------- + +.. versionadded:: 3.16 + +This variable is used to initialize the :prop_tgt:`UNITY_BUILD_BATCH_SIZE` +property of targets when they are created. It specifies the default upper +limit on the number of source files that may be combined in any one unity +source file when unity builds are enabled for a target. diff --git a/Help/variable/CMAKE_UNITY_BUILD_UNIQUE_ID.rst b/Help/variable/CMAKE_UNITY_BUILD_UNIQUE_ID.rst new file mode 100644 index 0000000..64ef18a --- /dev/null +++ b/Help/variable/CMAKE_UNITY_BUILD_UNIQUE_ID.rst @@ -0,0 +1,8 @@ +CMAKE_UNITY_BUILD_UNIQUE_ID +--------------------------- + +.. versionadded:: 3.20 + +This variable is used to initialize the :prop_tgt:`UNITY_BUILD_UNIQUE_ID` +property of targets when they are created. It specifies the name of the +unique identifier generated per file in a unity build. diff --git a/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst new file mode 100644 index 0000000..71c06cf --- /dev/null +++ b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst @@ -0,0 +1,27 @@ +CMAKE_USER_MAKE_RULES_OVERRIDE +------------------------------ + +Specify a CMake file that overrides platform information. + +CMake loads the specified file while enabling support for each +language from either the :command:`project` or :command:`enable_language` +commands. It is loaded after CMake's builtin compiler and platform information +modules have been loaded but before the information is used. The file +may set platform information variables to override CMake's defaults. +See :variable:`CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG>` for the language-specific +version of this variable. + +This feature is intended for use only in overriding information +variables that must be set before CMake builds its first test project +to check that the compiler for a language works. It should not be +used to load a file in cases that a normal :command:`include` will work. Use +it only as a last resort for behavior that cannot be achieved any +other way. For example, one may set the +:variable:`CMAKE_C_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>` variable +to change the default value used to initialize the +:variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` variable +before it is cached. The override file should NOT be used to set anything +that could be set after languages are enabled, such as variables like +:variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY` that affect the placement of +binaries. Information set in the file will be used for :command:`try_compile` +and :command:`try_run` builds too. diff --git a/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG.rst b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG.rst new file mode 100644 index 0000000..e7139ac --- /dev/null +++ b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG.rst @@ -0,0 +1,8 @@ +CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG> +------------------------------------- + +Specify a CMake file that overrides platform information for ``<LANG>``. + +This is a language-specific version of +:variable:`CMAKE_USER_MAKE_RULES_OVERRIDE` loaded only when enabling language +``<LANG>``. diff --git a/Help/variable/CMAKE_USE_RELATIVE_PATHS.rst b/Help/variable/CMAKE_USE_RELATIVE_PATHS.rst new file mode 100644 index 0000000..06fe0fb --- /dev/null +++ b/Help/variable/CMAKE_USE_RELATIVE_PATHS.rst @@ -0,0 +1,5 @@ +CMAKE_USE_RELATIVE_PATHS +------------------------ + +This variable has no effect. The partially implemented effect it +had in previous releases was removed in CMake 3.4. diff --git a/Help/variable/CMAKE_VERBOSE_MAKEFILE.rst b/Help/variable/CMAKE_VERBOSE_MAKEFILE.rst new file mode 100644 index 0000000..232a2fd --- /dev/null +++ b/Help/variable/CMAKE_VERBOSE_MAKEFILE.rst @@ -0,0 +1,9 @@ +CMAKE_VERBOSE_MAKEFILE +---------------------- + +Enable verbose output from Makefile builds. + +This variable is a cache entry initialized (to ``FALSE``) by +the :command:`project` command. Users may enable the option +in their local build tree to get more verbose output from +Makefile builds and show each command line as it is launched. diff --git a/Help/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS.rst b/Help/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS.rst new file mode 100644 index 0000000..3fb8817 --- /dev/null +++ b/Help/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS.rst @@ -0,0 +1,39 @@ +CMAKE_VERIFY_INTERFACE_HEADER_SETS +---------------------------------- + +.. versionadded:: 3.24 + +This variable is used to initialize the +:prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` property of targets when they are +created. Setting it to true enables header set verification. + +Projects should not normally set this variable, it is intended as a developer +control to be set on the :manual:`cmake(1)` command line or other +equivalent methods. The developer must have the ability to enable or +disable header set verification according to the capabilities of their own +machine and compiler. + +Verification of a dependency's header sets is not typically of interest +to developers. Therefore, :command:`FetchContent_MakeAvailable` explicitly +sets ``CMAKE_VERIFY_INTERFACE_HEADER_SETS`` to false for the duration of its +call, but restores its original value before returning. If a project brings +a dependency directly into the main build (e.g. calling +:command:`add_subdirectory` on a vendored project from a git submodule), it +should also do likewise. For example: + +.. code:: cmake + + # Save original setting so we can restore it later + set(want_header_set_verification ${CMAKE_VERIFY_INTERFACE_HEADER_SETS}) + + # Include the vendored dependency with header set verification disabled + set(CMAKE_VERIFY_INTERFACE_HEADER_SETS OFF) + add_subdirectory(...) # Vendored sources, e.g. from git submodules + + # Add the project's own sources. Restore the developer's original choice + # for whether to enable header set verification. + set(CMAKE_VERIFY_INTERFACE_HEADER_SETS ${want_header_set_verification}) + add_subdirectory(src) + +By default, this variable is not set, which will result in header set +verification being disabled. diff --git a/Help/variable/CMAKE_VERSION.rst b/Help/variable/CMAKE_VERSION.rst new file mode 100644 index 0000000..872e2fa --- /dev/null +++ b/Help/variable/CMAKE_VERSION.rst @@ -0,0 +1,51 @@ +CMAKE_VERSION +------------- + +The CMake version string as three non-negative integer components +separated by ``.`` and possibly followed by ``-`` and other information. +The first two components represent the feature level and the third +component represents either a bug-fix level or development date. + +Release versions and release candidate versions of CMake use the format:: + + <major>.<minor>.<patch>[-rc<n>] + +where the ``<patch>`` component is less than ``20000000``. Development +versions of CMake use the format:: + + <major>.<minor>.<date>[-<id>] + +where the ``<date>`` component is of format ``CCYYMMDD`` and ``<id>`` +may contain arbitrary text. This represents development as of a +particular date following the ``<major>.<minor>`` feature release. + +Individual component values are also available in variables: + +* :variable:`CMAKE_MAJOR_VERSION` +* :variable:`CMAKE_MINOR_VERSION` +* :variable:`CMAKE_PATCH_VERSION` +* :variable:`CMAKE_TWEAK_VERSION` + +Use the :command:`if` command ``VERSION_LESS``, ``VERSION_GREATER``, +``VERSION_EQUAL``, ``VERSION_LESS_EQUAL``, or ``VERSION_GREATER_EQUAL`` +operators to compare version string values against ``CMAKE_VERSION`` using a +component-wise test. Version component values may be 10 or larger so do not +attempt to compare version strings as floating-point numbers. + +.. note:: + + CMake versions 2.8.2 through 2.8.12 used three components for the + feature level. Release versions represented the bug-fix level in a + fourth component, i.e. ``<major>.<minor>.<patch>[.<tweak>][-rc<n>]``. + Development versions represented the development date in the fourth + component, i.e. ``<major>.<minor>.<patch>.<date>[-<id>]``. + + CMake versions prior to 2.8.2 used three components for the + feature level and had no bug-fix component. Release versions + used an even-valued second component, i.e. + ``<major>.<even-minor>.<patch>[-rc<n>]``. Development versions + used an odd-valued second component with the development date as + the third component, i.e. ``<major>.<odd-minor>.<date>``. + + The ``CMAKE_VERSION`` variable is defined by CMake 2.6.3 and higher. + Earlier versions defined only the individual component variables. diff --git a/Help/variable/CMAKE_VISIBILITY_INLINES_HIDDEN.rst b/Help/variable/CMAKE_VISIBILITY_INLINES_HIDDEN.rst new file mode 100644 index 0000000..150bacc --- /dev/null +++ b/Help/variable/CMAKE_VISIBILITY_INLINES_HIDDEN.rst @@ -0,0 +1,5 @@ +CMAKE_VISIBILITY_INLINES_HIDDEN +------------------------------- + +Default value for the :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target +property when a target is created. diff --git a/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst b/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst new file mode 100644 index 0000000..2bb97c4 --- /dev/null +++ b/Help/variable/CMAKE_VS_DEVENV_COMMAND.rst @@ -0,0 +1,14 @@ +CMAKE_VS_DEVENV_COMMAND +----------------------- + +The generators for :generator:`Visual Studio 9 2008` and above set this +variable to the ``devenv.com`` command installed with the corresponding +Visual Studio version. Note that this variable may be empty on +Visual Studio Express editions because they do not provide this tool. + +This variable is not defined by other generators even if ``devenv.com`` +is installed on the computer. + +The :variable:`CMAKE_VS_MSBUILD_COMMAND` is also provided for +:generator:`Visual Studio 11 2012` and above. +See also the :variable:`CMAKE_MAKE_PROGRAM` variable. diff --git a/Help/variable/CMAKE_VS_GLOBALS.rst b/Help/variable/CMAKE_VS_GLOBALS.rst new file mode 100644 index 0000000..d4514fe --- /dev/null +++ b/Help/variable/CMAKE_VS_GLOBALS.rst @@ -0,0 +1,23 @@ +CMAKE_VS_GLOBALS +---------------- + +.. versionadded:: 3.13 + +List of ``Key=Value`` records to be set per target as target properties +:prop_tgt:`VS_GLOBAL_<variable>` with ``variable=Key`` and value ``Value``. + +For example: + +.. code-block:: cmake + + set(CMAKE_VS_GLOBALS + "DefaultLanguage=en-US" + "MinimumVisualStudioVersion=14.0" + ) + +will set properties ``VS_GLOBAL_DefaultLanguage`` to ``en-US`` and +``VS_GLOBAL_MinimumVisualStudioVersion`` to ``14.0`` for all targets +(except for ``INTERFACE`` libraries). + +This variable is meant to be set by a +:variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>`. diff --git a/Help/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD.rst b/Help/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD.rst new file mode 100644 index 0000000..ace94e4 --- /dev/null +++ b/Help/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD.rst @@ -0,0 +1,10 @@ +CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD +----------------------------------------- + +.. versionadded:: 3.3 + +Include ``INSTALL`` target to default build. + +In Visual Studio solution, by default the ``INSTALL`` target will not be part +of the default build. Setting this variable will enable the ``INSTALL`` target +to be part of the default build. diff --git a/Help/variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD.rst b/Help/variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD.rst new file mode 100644 index 0000000..ab4d0fa --- /dev/null +++ b/Help/variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD.rst @@ -0,0 +1,10 @@ +CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD +----------------------------------------- + +.. versionadded:: 3.8 + +Include ``PACKAGE`` target to default build. + +In Visual Studio solution, by default the ``PACKAGE`` target will not be part +of the default build. Setting this variable will enable the ``PACKAGE`` target +to be part of the default build. diff --git a/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst b/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst new file mode 100644 index 0000000..ceedf28 --- /dev/null +++ b/Help/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION.rst @@ -0,0 +1,7 @@ +CMAKE_VS_INTEL_Fortran_PROJECT_VERSION +-------------------------------------- + +When generating for :generator:`Visual Studio 9 2008` or greater with the Intel +Fortran plugin installed, this specifies the ``.vfproj`` project file format +version. This is intended for internal use by CMake and should not be +used by project code. diff --git a/Help/variable/CMAKE_VS_JUST_MY_CODE_DEBUGGING.rst b/Help/variable/CMAKE_VS_JUST_MY_CODE_DEBUGGING.rst new file mode 100644 index 0000000..0a02a32 --- /dev/null +++ b/Help/variable/CMAKE_VS_JUST_MY_CODE_DEBUGGING.rst @@ -0,0 +1,10 @@ +CMAKE_VS_JUST_MY_CODE_DEBUGGING +------------------------------- + +.. versionadded:: 3.15 + +Enable Just My Code with Visual Studio debugger. + +This variable is used to initialize the :prop_tgt:`VS_JUST_MY_CODE_DEBUGGING` +property on all targets when they are created. See that target property for +additional information. diff --git a/Help/variable/CMAKE_VS_MSBUILD_COMMAND.rst b/Help/variable/CMAKE_VS_MSBUILD_COMMAND.rst new file mode 100644 index 0000000..8a521a3 --- /dev/null +++ b/Help/variable/CMAKE_VS_MSBUILD_COMMAND.rst @@ -0,0 +1,13 @@ +CMAKE_VS_MSBUILD_COMMAND +------------------------ + +The generators for :generator:`Visual Studio 11 2012` and above set this +variable to the ``MSBuild.exe`` command installed with the corresponding +Visual Studio version. + +This variable is not defined by other generators even if ``MSBuild.exe`` +is installed on the computer. + +The :variable:`CMAKE_VS_DEVENV_COMMAND` is also provided for the +non-Express editions of Visual Studio. +See also the :variable:`CMAKE_MAKE_PROGRAM` variable. diff --git a/Help/variable/CMAKE_VS_NO_COMPILE_BATCHING.rst b/Help/variable/CMAKE_VS_NO_COMPILE_BATCHING.rst new file mode 100644 index 0000000..2fb163e --- /dev/null +++ b/Help/variable/CMAKE_VS_NO_COMPILE_BATCHING.rst @@ -0,0 +1,20 @@ +CMAKE_VS_NO_COMPILE_BATCHING +---------------------------- + +.. versionadded:: 3.24 + +Turn off compile batching when using :ref:`Visual Studio Generators`. + +This variable is used to initialize the :prop_tgt:`VS_NO_COMPILE_BATCHING` +property on all targets when they are created. See that target property for +additional information. + +Example +^^^^^^^ + +This shows setting the property for the target ``foo`` using the variable. + +.. code-block:: cmake + + set(CMAKE_VS_NO_COMPILE_BATCHING ON) + add_library(foo SHARED foo.cpp) diff --git a/Help/variable/CMAKE_VS_NUGET_PACKAGE_RESTORE.rst b/Help/variable/CMAKE_VS_NUGET_PACKAGE_RESTORE.rst new file mode 100644 index 0000000..7160726 --- /dev/null +++ b/Help/variable/CMAKE_VS_NUGET_PACKAGE_RESTORE.rst @@ -0,0 +1,22 @@ +CMAKE_VS_NUGET_PACKAGE_RESTORE +------------------------------ + +.. versionadded:: 3.23 + +When using a Visual Studio generator, this cache variable controls +if msbuild should automatically attempt to restore NuGet packages +prior to a build. NuGet packages can be defined using the +:prop_tgt:`VS_PACKAGE_REFERENCES` property on a target. If no +package references are defined, this setting will do nothing. + +The command line option ``--resolve-package-references`` can be used +alternatively to control the resolve behavior globally. This option +will take precedence over the cache variable. + +Targets that use the :prop_tgt:`DOTNET_SDK` are required to run a +restore before building. Disabling this option may cause the build +to fail in such projects. + +This setting is stored as a cache entry. Default value is ``ON``. + +See also the :prop_tgt:`VS_PACKAGE_REFERENCES` property. diff --git a/Help/variable/CMAKE_VS_NsightTegra_VERSION.rst b/Help/variable/CMAKE_VS_NsightTegra_VERSION.rst new file mode 100644 index 0000000..2982b39 --- /dev/null +++ b/Help/variable/CMAKE_VS_NsightTegra_VERSION.rst @@ -0,0 +1,9 @@ +CMAKE_VS_NsightTegra_VERSION +---------------------------- + +.. versionadded:: 3.1 + +When using a Visual Studio generator with the +:variable:`CMAKE_SYSTEM_NAME` variable set to ``Android``, +this variable contains the version number of the +installed NVIDIA Nsight Tegra Visual Studio Edition. diff --git a/Help/variable/CMAKE_VS_PLATFORM_NAME.rst b/Help/variable/CMAKE_VS_PLATFORM_NAME.rst new file mode 100644 index 0000000..7d08add --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_NAME.rst @@ -0,0 +1,12 @@ +CMAKE_VS_PLATFORM_NAME +---------------------- + +.. versionadded:: 3.1 + +Visual Studio target platform name used by the current generator. + +VS 8 and above allow project files to specify a target platform. +CMake provides the name of the chosen platform in this variable. +See the :variable:`CMAKE_GENERATOR_PLATFORM` variable for details. + +See also the :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable. diff --git a/Help/variable/CMAKE_VS_PLATFORM_NAME_DEFAULT.rst b/Help/variable/CMAKE_VS_PLATFORM_NAME_DEFAULT.rst new file mode 100644 index 0000000..6440174 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_NAME_DEFAULT.rst @@ -0,0 +1,11 @@ +CMAKE_VS_PLATFORM_NAME_DEFAULT +------------------------------ + +.. versionadded:: 3.14.3 + +Default for the Visual Studio target platform name for the current generator +without considering the value of the :variable:`CMAKE_GENERATOR_PLATFORM` +variable. For :ref:`Visual Studio Generators` for VS 2017 and below this is +always ``Win32``. For VS 2019 and above this is based on the host platform. + +See also the :variable:`CMAKE_VS_PLATFORM_NAME` variable. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst new file mode 100644 index 0000000..ed2d3f3 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst @@ -0,0 +1,12 @@ +CMAKE_VS_PLATFORM_TOOLSET +------------------------- + +Visual Studio Platform Toolset name. + +VS 10 and above use MSBuild under the hood and support multiple +compiler toolchains. CMake may specify a toolset explicitly, such as +``v110`` for VS 11 or ``Windows7.1SDK`` for 64-bit support in VS 10 +Express. CMake provides the name of the chosen toolset in this +variable. + +See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst new file mode 100644 index 0000000..e66378d --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst @@ -0,0 +1,16 @@ +CMAKE_VS_PLATFORM_TOOLSET_CUDA +------------------------------ + +.. versionadded:: 3.9 + +NVIDIA CUDA Toolkit version whose Visual Studio toolset to use. + +The :ref:`Visual Studio Generators` for VS 2010 and above support using +a CUDA toolset provided by a CUDA Toolkit. The toolset version number +may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of +the form ``cuda=8.0``. Or it is automatically detected if a path to +a standalone CUDA directory is specified in the form ``cuda=C:\path\to\cuda``. +If none is specified CMake will choose a default version. +CMake provides the selected CUDA toolset version in this variable. +The value may be empty if no CUDA Toolkit with Visual Studio integration +is installed. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst new file mode 100644 index 0000000..a19e7e1 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst @@ -0,0 +1,17 @@ +CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR +----------------------------------------- + +.. versionadded:: 3.16 + +Path to standalone NVIDIA CUDA Toolkit (eg. extracted from installer). + +The :ref:`Visual Studio Generators` for VS 2010 and above support using +a standalone (non-installed) NVIDIA CUDA toolkit. The path +may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of +the form ``cuda=C:\path\to\cuda``. The given directory must at least +contain the nvcc compiler in path ``.\bin`` and must provide Visual Studio +integration files in path ``.\extras\visual_studio_integration\ +MSBuildExtensions\``. One can create a standalone CUDA toolkit directory by +either opening a installer with 7zip or copying the files that are extracted +by the running installer. The value may be empty if no path to a standalone +CUDA Toolkit was specified. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst new file mode 100644 index 0000000..5c13bb7 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst @@ -0,0 +1,12 @@ +CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE +------------------------------------------- + +.. versionadded:: 3.8 + +Visual Studio preferred tool architecture. + +The :ref:`Visual Studio Generators` for VS 2013 and above support using +either the 32-bit or 64-bit host toolchains by specifying a ``host=x86`` +or ``host=x64`` value in the :variable:`CMAKE_GENERATOR_TOOLSET` option. +CMake provides the selected toolchain architecture preference in this +variable (``x86``, ``x64``, ``ARM64`` or empty). diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION.rst new file mode 100644 index 0000000..c4369ee --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION.rst @@ -0,0 +1,33 @@ +CMAKE_VS_PLATFORM_TOOLSET_VERSION +--------------------------------- + +.. versionadded:: 3.12 + +Visual Studio Platform Toolset version. + +The :ref:`Visual Studio Generators` for VS 2017 and above allow to +select minor versions of the same toolset. The toolset version number +may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of +the form ``version=14.11``. If none is specified CMake will choose a default +toolset. The value may be empty if no minor version was selected and the +default is used. + +If the value is not empty, it is the version number that MSBuild uses in +its ``Microsoft.VCToolsVersion.*.props`` file names. + +.. versionadded:: 3.19.7 + + VS 16.9's toolset may also be specified as ``14.28.16.9`` because + VS 16.10 uses the file name ``Microsoft.VCToolsVersion.14.28.16.9.props``. + +Three-Component MSVC Toolset Versions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.19.7 + +The ``version=`` field may be given a three-component toolset version +such as ``14.28.29910``, and CMake will convert it to the name used by +MSBuild ``Microsoft.VCToolsVersion.*.props`` files. This is useful +to distinguish between VS 16.8's ``14.28.29333`` toolset and VS 16.9's +``14.28.29910`` toolset. It also matches ``vcvarsall``'s ``-vcvars_ver=`` +behavior. diff --git a/Help/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..969f328 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES.rst @@ -0,0 +1,6 @@ +CMAKE_VS_SDK_EXCLUDE_DIRECTORIES +-------------------------------- + +.. versionadded:: 3.12 + +This variable allows to override Visual Studio default Exclude Directories. diff --git a/Help/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES.rst new file mode 100644 index 0000000..7455e10 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES.rst @@ -0,0 +1,6 @@ +CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES +----------------------------------- + +.. versionadded:: 3.12 + +This variable allows to override Visual Studio default Executable Directories. diff --git a/Help/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..3f27aea --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,6 @@ +CMAKE_VS_SDK_INCLUDE_DIRECTORIES +-------------------------------- + +.. versionadded:: 3.12 + +This variable allows to override Visual Studio default Include Directories. diff --git a/Help/variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES.rst new file mode 100644 index 0000000..35e45a3 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES.rst @@ -0,0 +1,6 @@ +CMAKE_VS_SDK_LIBRARY_DIRECTORIES +-------------------------------- + +.. versionadded:: 3.12 + +This variable allows to override Visual Studio default Library Directories. diff --git a/Help/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES.rst new file mode 100644 index 0000000..24b90b6 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES.rst @@ -0,0 +1,7 @@ +CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES +-------------------------------------- + +.. versionadded:: 3.12 + +This variable allows to override Visual Studio default Library WinRT +Directories. diff --git a/Help/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES.rst new file mode 100644 index 0000000..00382fe --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES.rst @@ -0,0 +1,6 @@ +CMAKE_VS_SDK_REFERENCE_DIRECTORIES +---------------------------------- + +.. versionadded:: 3.12 + +This variable allows to override Visual Studio default Reference Directories. diff --git a/Help/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES.rst b/Help/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES.rst new file mode 100644 index 0000000..b98c999 --- /dev/null +++ b/Help/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES.rst @@ -0,0 +1,6 @@ +CMAKE_VS_SDK_SOURCE_DIRECTORIES +------------------------------- + +.. versionadded:: 3.12 + +This variable allows to override Visual Studio default Source Directories. diff --git a/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.rst b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.rst new file mode 100644 index 0000000..5ad5897 --- /dev/null +++ b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.rst @@ -0,0 +1,13 @@ +CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER +------------------------------------ + +.. versionadded:: 3.22 + +Visual Studio target framework identifier. + +In some cases, the :ref:`Visual Studio Generators` may use an explicit value +for the MSBuild ``TargetFrameworkIdentifier`` setting in ``.csproj`` files. +CMake provides the chosen value in this variable. + +See also :variable:`CMAKE_VS_TARGET_FRAMEWORK_VERSION` and +:variable:`CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION`. diff --git a/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.rst b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.rst new file mode 100644 index 0000000..8dcb3a7 --- /dev/null +++ b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.rst @@ -0,0 +1,13 @@ +CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION +----------------------------------------- + +.. versionadded:: 3.22 + +Visual Studio target framework targets version. + +In some cases, the :ref:`Visual Studio Generators` may use an explicit value +for the MSBuild ``TargetFrameworkTargetsVersion`` setting in ``.csproj`` files. +CMake provides the chosen value in this variable. + +See also :variable:`CMAKE_VS_TARGET_FRAMEWORK_VERSION` and +:variable:`CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER`. diff --git a/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION.rst b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION.rst new file mode 100644 index 0000000..5489f79 --- /dev/null +++ b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,17 @@ +CMAKE_VS_TARGET_FRAMEWORK_VERSION +--------------------------------- + +.. versionadded:: 3.22 + +Visual Studio target framework version. + +In some cases, the :ref:`Visual Studio Generators` may use an explicit value +for the MSBuild ``TargetFrameworkVersion`` setting in ``.csproj`` files. +CMake provides the chosen value in this variable. + +See the :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION` variable +and :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target property to +specify custom ``TargetFrameworkVersion`` values for project targets. + +See also :variable:`CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER` and +:variable:`CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION`. diff --git a/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER.rst b/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER.rst new file mode 100644 index 0000000..f86ed7c --- /dev/null +++ b/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER.rst @@ -0,0 +1,14 @@ +CMAKE_VS_VERSION_BUILD_NUMBER +----------------------------- + +.. versionadded:: 3.26 + +Visual Studio version. + +:ref:`Visual Studio Generators` for VS 2017 and above set this +variable to the Visual Studio version build number in the format +``<major>.<minor>.<date>.<build>``. + +.. include:: CMAKE_VS_VERSION_BUILD_NUMBER_COMPONENTS.txt + +See also the :variable:`CMAKE_GENERATOR_INSTANCE` variable. diff --git a/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER_COMPONENTS.txt b/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER_COMPONENTS.txt new file mode 100644 index 0000000..6bdede7 --- /dev/null +++ b/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER_COMPONENTS.txt @@ -0,0 +1,18 @@ +The components are: + +``<major>.<minor>`` + + The VS major and minor version numbers. + These are the same as the release version numbers. + +``<date>`` + + A build date in the format ``MMMDD``, where ``MMM`` is a month index + since an epoch used by Microsoft, and ``DD`` is a day in that month. + +``<build>`` + + A build index on the day represented by ``<date>``. + +The build number is reported by ``vswhere`` as ``installationVersion``. +For example, VS 16.11.10 has build number ``16.11.32126.315``. diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst new file mode 100644 index 0000000..eb71049 --- /dev/null +++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst @@ -0,0 +1,21 @@ +CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION +---------------------------------------- + +.. versionadded:: 3.4 + +Visual Studio Windows Target Platform Version. + +When targeting Windows 10 and above Visual Studio 2015 and above support +specification of a target Windows version to select a corresponding SDK. +The :variable:`CMAKE_SYSTEM_VERSION` variable may be set to specify a +version. Otherwise CMake computes a default version based on the Windows +SDK versions available. The chosen Windows target version number is provided +in ``CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION``. If no Windows 10 SDK +is available this value will be empty. + +One may set a ``CMAKE_WINDOWS_KITS_10_DIR`` *environment variable* +to an absolute path to tell CMake to look for Windows 10 SDKs in +a custom location. The specified directory is expected to contain +``Include/10.0.*`` directories. + +See also :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM`. diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst new file mode 100644 index 0000000..f1a1977 --- /dev/null +++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst @@ -0,0 +1,14 @@ +CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM +------------------------------------------------ + +.. versionadded:: 3.19 + +Override the :ref:`Windows 10 SDK Maximum Version for VS 2015` and beyond. + +The ``CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM`` variable may +be set to a false value (e.g. ``OFF``, ``FALSE``, or ``0``) or the SDK version +to use as the maximum (e.g. ``10.0.14393.0``). If unset, the default depends +on which version of Visual Studio is targeted by the current generator. + +This can be used in conjunction with :variable:`CMAKE_SYSTEM_VERSION`, which +CMake uses to select :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION`. diff --git a/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst b/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst new file mode 100644 index 0000000..9ded85f --- /dev/null +++ b/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst @@ -0,0 +1,20 @@ +CMAKE_VS_WINRT_BY_DEFAULT +------------------------- + +.. versionadded:: 3.13 + +Inform :ref:`Visual Studio Generators` for VS 2010 and above that the +target platform enables WinRT compilation by default and it needs to +be explicitly disabled if ``/ZW`` or :prop_tgt:`VS_WINRT_COMPONENT` is +omitted (as opposed to enabling it when either of those options is +present) + +This makes cmake configuration consistent in terms of WinRT among +platforms - if you did not enable the WinRT compilation explicitly, it +will be disabled (by either not enabling it or explicitly disabling it) + +Note: WinRT compilation is always explicitly disabled for C language +source files, even if it is expliclty enabled for a project + +This variable is meant to be set by a +:variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` for such platforms. diff --git a/Help/variable/CMAKE_WARN_DEPRECATED.rst b/Help/variable/CMAKE_WARN_DEPRECATED.rst new file mode 100644 index 0000000..c7b6159 --- /dev/null +++ b/Help/variable/CMAKE_WARN_DEPRECATED.rst @@ -0,0 +1,11 @@ +CMAKE_WARN_DEPRECATED +--------------------- + +Whether to issue warnings for deprecated functionality. + +If not ``FALSE``, use of deprecated functionality will issue warnings. +If this variable is not set, CMake behaves as if it were set to ``TRUE``. + +When running :manual:`cmake(1)`, this option can be enabled with the +:option:`-Wdeprecated <cmake -Wdeprecated>` option, or disabled with the +:option:`-Wno-deprecated <cmake -Wno-deprecated>` option. diff --git a/Help/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst b/Help/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst new file mode 100644 index 0000000..81c1158 --- /dev/null +++ b/Help/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst @@ -0,0 +1,9 @@ +CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION +------------------------------------------ + +Ask ``cmake_install.cmake`` script to warn each time a file with absolute +``INSTALL DESTINATION`` is encountered. + +This variable is used by CMake-generated ``cmake_install.cmake`` scripts. +If one sets this variable to ``ON`` while running the script, it may get +warning messages from the script. diff --git a/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst b/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst new file mode 100644 index 0000000..feb2a60 --- /dev/null +++ b/Help/variable/CMAKE_WATCOM_RUNTIME_LIBRARY.rst @@ -0,0 +1,36 @@ +CMAKE_WATCOM_RUNTIME_LIBRARY +---------------------------- + +.. versionadded:: 3.24 + +Select the Watcom runtime library for use by compilers targeting the Watcom ABI. +This variable is used to initialize the :prop_tgt:`WATCOM_RUNTIME_LIBRARY` +property on all targets as they are created. It is also propagated by +calls to the :command:`try_compile` command into the test project. + +The allowed values are: + +.. include:: ../prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to +support per-configuration specification. + +For example, the code: + +.. code-block:: cmake + + set(CMAKE_WATCOM_RUNTIME_LIBRARY "MultiThreaded") + +selects for all following targets a multi-threaded statically-linked runtime +library. + +If this variable is not set then the :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target +property will not be set automatically. If that property is not set then +CMake uses the default value ``MultiThreadedDLL`` on Windows and +``SingleThreaded`` on other platforms to select a Watcom runtime library. + +.. note:: + + This variable has effect only when policy :policy:`CMP0136` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables a language using a compiler targeting the Watcom ABI. diff --git a/Help/variable/CMAKE_WIN32_EXECUTABLE.rst b/Help/variable/CMAKE_WIN32_EXECUTABLE.rst new file mode 100644 index 0000000..b96abba --- /dev/null +++ b/Help/variable/CMAKE_WIN32_EXECUTABLE.rst @@ -0,0 +1,7 @@ +CMAKE_WIN32_EXECUTABLE +---------------------- + +Default value for :prop_tgt:`WIN32_EXECUTABLE` of targets. + +This variable is used to initialize the :prop_tgt:`WIN32_EXECUTABLE` property +on all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS.rst b/Help/variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS.rst new file mode 100644 index 0000000..7b01185 --- /dev/null +++ b/Help/variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS.rst @@ -0,0 +1,8 @@ +CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS +-------------------------------- + +.. versionadded:: 3.4 + +Default value for :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property. +This variable is used to initialize the property on each target as it is +created. diff --git a/Help/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute.rst b/Help/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute.rst new file mode 100644 index 0000000..ffa0a4c --- /dev/null +++ b/Help/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute.rst @@ -0,0 +1,24 @@ +CMAKE_XCODE_ATTRIBUTE_<an-attribute> +------------------------------------ + +.. versionadded:: 3.1 + +Set Xcode target attributes directly. + +Tell the :generator:`Xcode` generator to set ``<an-attribute>`` to a given +value in the generated Xcode project. Ignored on other generators. + +This offers low-level control over the generated Xcode project file. +It is meant as a last resort for specifying settings that CMake does +not otherwise have a way to control. Although this can override a +setting CMake normally produces on its own, doing so bypasses CMake's +model of the project and can break things. + +See the :prop_tgt:`XCODE_ATTRIBUTE_<an-attribute>` target property +to set attributes on a specific target. + +Contents of ``CMAKE_XCODE_ATTRIBUTE_<an-attribute>`` may use +"generator expressions" with the syntax ``$<...>``. See the +:manual:`cmake-generator-expressions(7)` manual for available +expressions. See the :manual:`cmake-buildsystem(7)` manual +for more on defining buildsystem properties. diff --git a/Help/variable/CMAKE_XCODE_BUILD_SYSTEM.rst b/Help/variable/CMAKE_XCODE_BUILD_SYSTEM.rst new file mode 100644 index 0000000..d153061 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_BUILD_SYSTEM.rst @@ -0,0 +1,24 @@ +CMAKE_XCODE_BUILD_SYSTEM +------------------------ + +.. versionadded:: 3.19 + +Xcode build system selection. + +The :generator:`Xcode` generator defines this variable to indicate which +variant of the Xcode build system will be used. The value is the +version of Xcode in which the corresponding build system first became +mature enough for use by CMake. The possible values are: + +``1`` + The original Xcode build system. + This is the default when using Xcode 11.x or below. + +``12`` + The Xcode "new build system" introduced by Xcode 10. + It became mature enough for use by CMake in Xcode 12. + This is the default when using Xcode 12.x or above. + +The ``CMAKE_XCODE_BUILD_SYSTEM`` variable is informational and should not +be modified by project code. See the :ref:`Xcode Build System Selection` +documentation section to select the Xcode build system. diff --git a/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst new file mode 100644 index 0000000..40070e1 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_GENERATE_SCHEME +--------------------------- + +.. versionadded:: 3.9 + +If enabled, the :generator:`Xcode` generator will generate schema files. These +are useful to invoke analyze, archive, build-for-testing and test +actions from the command line. + +This variable initializes the +:prop_tgt:`XCODE_GENERATE_SCHEME` +target property on all targets. diff --git a/Help/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY.rst b/Help/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY.rst new file mode 100644 index 0000000..38d043c --- /dev/null +++ b/Help/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY.rst @@ -0,0 +1,11 @@ +CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY +------------------------------------------- + +.. versionadded:: 3.11 + +If enabled, the :generator:`Xcode` generator will generate only a +single Xcode project file for the topmost :command:`project()` command +instead of generating one for every ``project()`` command. + +This could be useful to speed up the CMake generation step for +large projects and to work-around a bug in the ``ZERO_CHECK`` logic. diff --git a/Help/variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE.rst b/Help/variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE.rst new file mode 100644 index 0000000..17189c0 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE.rst @@ -0,0 +1,9 @@ +CMAKE_XCODE_LINK_BUILD_PHASE_MODE +--------------------------------- + +.. versionadded:: 3.19 + +This variable is used to initialize the +:prop_tgt:`XCODE_LINK_BUILD_PHASE_MODE` property on targets. +It affects the methods that the :generator:`Xcode` generator uses to link +different kinds of libraries. Its default value is ``NONE``. diff --git a/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst b/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst new file mode 100644 index 0000000..6d72d14 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_PLATFORM_TOOLSET.rst @@ -0,0 +1,9 @@ +CMAKE_XCODE_PLATFORM_TOOLSET +---------------------------- + +Xcode compiler selection. + +:generator:`Xcode` supports selection of a compiler from one of the installed +toolsets. CMake provides the name of the chosen toolset in this +variable, if any is explicitly selected (e.g. via the :option:`cmake -T` +option). diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER.rst b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER.rst new file mode 100644 index 0000000..b3fa93b --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER +------------------------------------ + +.. versionadded:: 3.13 + +Whether to enable ``Address Sanitizer`` in the Diagnostics +section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ADDRESS_SANITIZER` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst new file mode 100644 index 0000000..1a0a17a --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN +----------------------------------------------------- + +.. versionadded:: 3.13 + +Whether to enable ``Detect use of stack after return`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst b/Help/variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst new file mode 100644 index 0000000..917fc7f --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING.rst @@ -0,0 +1,15 @@ +CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING +-------------------------------------------- + +.. versionadded:: 3.16 + +Whether to enable +``Allow debugging when using document Versions Browser`` +in the Options section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst b/Help/variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst new file mode 100644 index 0000000..b604598 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER +---------------------------------------------- + +.. versionadded:: 3.13 + +Whether to disable the ``Main Thread Checker`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst new file mode 100644 index 0000000..070ddfc --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS +---------------------------------------- + +.. versionadded:: 3.13 + +Whether to enable ``Dynamic Library Loads`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst new file mode 100644 index 0000000..4291816 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE +------------------------------------------- + +.. versionadded:: 3.13 + +Whether to enable ``Dynamic Linker API usage`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION.rst b/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION.rst new file mode 100644 index 0000000..ce5c4b3 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION.rst @@ -0,0 +1,13 @@ +CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION +-------------------------------------------- + +.. versionadded:: 3.25 + +Property value for ``Metal: API Validation`` in the Options section of +the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ENABLE_GPU_API_VALIDATION` property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst b/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst new file mode 100644 index 0000000..3a3c847 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst @@ -0,0 +1,15 @@ +CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE +------------------------------------------------ + +.. versionadded:: 3.23 + +Property value for ``GPU Frame Capture`` in the Options section of +the generated Xcode scheme. Example values are `Metal` and +`Disabled`. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION.rst b/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION.rst new file mode 100644 index 0000000..073a6c9 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION.rst @@ -0,0 +1,13 @@ +CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION +----------------------------------------------- + +.. versionadded:: 3.25 + +Property value for ``Metal: Shader Validation`` in the Options section of +the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION` property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst b/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst new file mode 100644 index 0000000..62b698d --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ENVIRONMENT.rst @@ -0,0 +1,17 @@ +CMAKE_XCODE_SCHEME_ENVIRONMENT +------------------------------ + +.. versionadded:: 3.17 + +Specify environment variables that should be added to the Arguments +section of the generated Xcode scheme. + +If set to a list of environment variables and values of the form +``MYVAR=value`` those environment variables will be added to the +scheme. + +This variable initializes the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC.rst b/Help/variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC.rst new file mode 100644 index 0000000..48b481e --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_GUARD_MALLOC +------------------------------- + +.. versionadded:: 3.13 + +Whether to enable ``Guard Malloc`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_GUARD_MALLOC` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION.rst b/Help/variable/CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION.rst new file mode 100644 index 0000000..e5b4d18 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION +--------------------------------------- + +.. versionadded:: 3.25 + +Set the build configuration to run the target. + +This variable initializes the :prop_tgt:`XCODE_SCHEME_LAUNCH_CONFIGURATION` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_LAUNCH_MODE.rst b/Help/variable/CMAKE_XCODE_SCHEME_LAUNCH_MODE.rst new file mode 100644 index 0000000..c15b1ea --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_LAUNCH_MODE.rst @@ -0,0 +1,13 @@ +CMAKE_XCODE_SCHEME_LAUNCH_MODE +------------------------------ + +.. versionadded:: 3.25 + +Property value for ``Launch`` in the Info section of the generated Xcode +scheme. + +This variable initializes the :prop_tgt:`XCODE_SCHEME_LAUNCH_MODE` property on +all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst b/Help/variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst new file mode 100644 index 0000000..ef8ed9b --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst @@ -0,0 +1,15 @@ +CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP +------------------------------------------- + +.. versionadded:: 3.13 + +Whether to enable the ``Main Thread Checker`` option +``Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES.rst b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES.rst new file mode 100644 index 0000000..d4ae9eb --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES +------------------------------------- + +.. versionadded:: 3.13 + +Whether to enable ``Malloc Guard Edges`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MALLOC_GUARD_EDGES` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE.rst b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE.rst new file mode 100644 index 0000000..e28f6a1 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE +---------------------------------- + +.. versionadded:: 3.13 + +Whether to enable ``Malloc Scribble`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MALLOC_SCRIBBLE` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_STACK.rst b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_STACK.rst new file mode 100644 index 0000000..59fcfd3 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_STACK.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_MALLOC_STACK +------------------------------- + +.. versionadded:: 3.13 + +Whether to enable ``Malloc Stack`` in the Diagnostics +section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MALLOC_STACK` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER.rst b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER.rst new file mode 100644 index 0000000..511eb04 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_THREAD_SANITIZER +----------------------------------- + +.. versionadded:: 3.13 + +Whether to enable ``Thread Sanitizer`` in the Diagnostics +section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_THREAD_SANITIZER` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP.rst b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP.rst new file mode 100644 index 0000000..6f3b8ce --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP +---------------------------------------- + +.. versionadded:: 3.13 + +Whether to enable ``Thread Sanitizer - Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_THREAD_SANITIZER_STOP` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst new file mode 100644 index 0000000..46d3ccf --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER +------------------------------------------------ + +.. versionadded:: 3.13 + +Whether to enable ``Undefined Behavior Sanitizer`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst new file mode 100644 index 0000000..8fa5ece --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst @@ -0,0 +1,15 @@ +CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP +----------------------------------------------------- + +.. versionadded:: 3.13 + +Whether to enable ``Undefined Behavior Sanitizer`` option +``Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst b/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst new file mode 100644 index 0000000..4221e48 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_WORKING_DIRECTORY +------------------------------------ + +.. versionadded:: 3.17 + +Specify the ``Working Directory`` of the *Run* and *Profile* +actions in the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS.rst b/Help/variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS.rst new file mode 100644 index 0000000..fd9488e --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS +--------------------------------- + +.. versionadded:: 3.13 + +Whether to enable ``Zombie Objects`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ZOMBIE_OBJECTS` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_XCCONFIG.rst b/Help/variable/CMAKE_XCODE_XCCONFIG.rst new file mode 100644 index 0000000..6b1ef30 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_XCCONFIG.rst @@ -0,0 +1,14 @@ +CMAKE_XCODE_XCCONFIG +-------------------- + +.. versionadded:: 3.24 + +If set, the :generator:`Xcode` generator will register the specified +file as a global XCConfig file. For target-level XCConfig files see +the :prop_tgt:`XCODE_XCCONFIG` target property. + +This feature is intended to ease migration from native Xcode projects +to CMake projects. + +Contents of ``CMAKE_XCODE_XCCONFIG`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/variable/CPACK_ABSOLUTE_DESTINATION_FILES.rst b/Help/variable/CPACK_ABSOLUTE_DESTINATION_FILES.rst new file mode 100644 index 0000000..928fe45 --- /dev/null +++ b/Help/variable/CPACK_ABSOLUTE_DESTINATION_FILES.rst @@ -0,0 +1,10 @@ +CPACK_ABSOLUTE_DESTINATION_FILES +-------------------------------- + +List of files which have been installed using an ``ABSOLUTE DESTINATION`` path. + +This variable is a Read-Only variable which is set internally by CPack +during installation and before packaging using +:variable:`CMAKE_ABSOLUTE_DESTINATION_FILES` defined in ``cmake_install.cmake`` +scripts. The value can be used within CPack project configuration +file and/or ``CPack<GEN>.cmake`` file of ``<GEN>`` generator. diff --git a/Help/variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY.rst b/Help/variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY.rst new file mode 100644 index 0000000..6cf75e4 --- /dev/null +++ b/Help/variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY.rst @@ -0,0 +1,8 @@ +CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY +------------------------------------------ + +Boolean toggle to include/exclude top level directory (component case). + +Similar usage as :variable:`CPACK_INCLUDE_TOPLEVEL_DIRECTORY` but for the +component case. See :variable:`CPACK_INCLUDE_TOPLEVEL_DIRECTORY` +documentation for the detail. diff --git a/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst b/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst new file mode 100644 index 0000000..9bd50db --- /dev/null +++ b/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst @@ -0,0 +1,44 @@ +CPACK_CUSTOM_INSTALL_VARIABLES +------------------------------ + +.. versionadded:: 3.21 + +CPack variables (set via e.g. :option:`cpack -D`, ``CPackConfig.cmake`` or +:variable:`CPACK_PROJECT_CONFIG_FILE` scripts) are not directly visible in +installation scripts. Instead, one can pass a list of ``varName=value`` +pairs in the ``CPACK_CUSTOM_INSTALL_VARIABLES`` variable. At install time, +each list item will result in a variable of the specified name (``varName``) +being set to the given ``value``. The ``=`` can be omitted for an empty +``value``. + +``CPACK_CUSTOM_INSTALL_VARIABLES`` allows the packaging installation to be +influenced by the user or driving script at CPack runtime without having to +regenerate the install scripts. + +Example +""""""" + +.. code-block:: cmake + + install(FILES large.txt DESTINATION data) + + install(CODE [[ + if(ENABLE_COMPRESSION) + # "run-compressor" is a fictional tool that produces + # large.txt.xz from large.txt and then removes the input file + execute_process(COMMAND run-compressor $ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}/large.txt) + endif() + ]]) + +With the above example snippet, :manual:`cpack <cpack(1)>` will by default +run the installation script with ``ENABLE_COMPRESSION`` unset, resulting in +a package containing the uncompressed ``large.txt``. This can be overridden +when invoking :manual:`cpack <cpack(1)>` like so: + +.. code-block:: shell + + cpack -D "CPACK_CUSTOM_INSTALL_VARIABLES=ENABLE_COMPRESSION=TRUE" + +The installation script will then run with ``ENABLE_COMPRESSION`` set to +``TRUE``, resulting in a package containing the compressed ``large.txt.xz`` +instead. diff --git a/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst b/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst new file mode 100644 index 0000000..30ae236 --- /dev/null +++ b/Help/variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst @@ -0,0 +1,11 @@ +CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION +------------------------------------------- + +Ask CPack to error out as soon as a file with absolute ``INSTALL DESTINATION`` +is encountered. + +The fatal error is emitted before the installation of the offending +file takes place. Some CPack generators, like ``NSIS``, enforce this +internally. This variable triggers the definition +of :variable:`CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION` when CPack +runs. diff --git a/Help/variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY.rst b/Help/variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY.rst new file mode 100644 index 0000000..b8e9105 --- /dev/null +++ b/Help/variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY.rst @@ -0,0 +1,20 @@ +CPACK_INCLUDE_TOPLEVEL_DIRECTORY +-------------------------------- + +Boolean toggle to include/exclude top level directory. + +When preparing a package CPack installs the item under the so-called +top level directory. The purpose of is to include (set to ``1`` or ``ON`` or +``TRUE``) the top level directory in the package or not (set to ``0`` or +``OFF`` or ``FALSE``). + +Each CPack generator has a built-in default value for this variable. +E.g. Archive generators (ZIP, TGZ, ...) includes the top level +whereas RPM or DEB don't. The user may override the default value by +setting this variable. + +There is a similar variable +:variable:`CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY` which may be used +to override the behavior for the component packaging +case which may have different default value for historical (now +backward compatibility) reason. diff --git a/Help/variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst b/Help/variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst new file mode 100644 index 0000000..01fb189 --- /dev/null +++ b/Help/variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst @@ -0,0 +1,13 @@ +CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS +------------------------------------------- + +.. versionadded:: 3.11 + +Default permissions for implicitly created directories during packaging. + +This variable serves the same purpose during packaging as the +:variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable +serves during installation (e.g. ``make install``). + +If `include(CPack)` is used then by default this variable is set to the content +of :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`. diff --git a/Help/variable/CPACK_PACKAGING_INSTALL_PREFIX.rst b/Help/variable/CPACK_PACKAGING_INSTALL_PREFIX.rst new file mode 100644 index 0000000..f423e2e --- /dev/null +++ b/Help/variable/CPACK_PACKAGING_INSTALL_PREFIX.rst @@ -0,0 +1,15 @@ +CPACK_PACKAGING_INSTALL_PREFIX +------------------------------ + +The prefix used in the built package. + +Each CPack generator has a default value (like ``/usr``). This default +value may be overwritten from the ``CMakeLists.txt`` or the :manual:`cpack(1)` +command line by setting an alternative value. Example: + +:: + + set(CPACK_PACKAGING_INSTALL_PREFIX "/opt") + +This is not the same purpose as :variable:`CMAKE_INSTALL_PREFIX` which is used +when installing from the build tree without building a package. diff --git a/Help/variable/CPACK_SET_DESTDIR.rst b/Help/variable/CPACK_SET_DESTDIR.rst new file mode 100644 index 0000000..27fd355 --- /dev/null +++ b/Help/variable/CPACK_SET_DESTDIR.rst @@ -0,0 +1,31 @@ +CPACK_SET_DESTDIR +----------------- + +Boolean toggle to make CPack use ``DESTDIR`` mechanism when packaging. + +``DESTDIR`` means DESTination DIRectory. It is commonly used by makefile +users in order to install software at non-default location. It is a +basic relocation mechanism that should not be used on Windows (see +:variable:`CMAKE_INSTALL_PREFIX` documentation). It is usually invoked like +this: + +:: + + make DESTDIR=/home/john install + +which will install the concerned software using the installation +prefix, e.g. ``/usr/local`` prepended with the ``DESTDIR`` value which +finally gives ``/home/john/usr/local``. When preparing a package, CPack +first installs the items to be packaged in a local (to the build tree) +directory by using the same ``DESTDIR`` mechanism. Nevertheless, if +``CPACK_SET_DESTDIR`` is set then CPack will set ``DESTDIR`` before doing the +local install. The most noticeable difference is that without +``CPACK_SET_DESTDIR``, CPack uses :variable:`CPACK_PACKAGING_INSTALL_PREFIX` +as a prefix whereas with ``CPACK_SET_DESTDIR`` set, CPack will use +:variable:`CMAKE_INSTALL_PREFIX` as a prefix. + +Manually setting ``CPACK_SET_DESTDIR`` may help (or simply be necessary) +if some install rules uses absolute ``DESTINATION`` (see CMake +:command:`install` command). However, starting with CPack/CMake 2.8.3 RPM +and DEB installers tries to handle ``DESTDIR`` automatically so that it is +seldom necessary for the user to set it. diff --git a/Help/variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst b/Help/variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst new file mode 100644 index 0000000..3fc5cca --- /dev/null +++ b/Help/variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst @@ -0,0 +1,9 @@ +CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION +------------------------------------------ + +Ask CPack to warn each time a file with absolute ``INSTALL DESTINATION`` is +encountered. + +This variable triggers the definition of +:variable:`CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION` when CPack runs +``cmake_install.cmake`` scripts. diff --git a/Help/variable/CTEST_BINARY_DIRECTORY.rst b/Help/variable/CTEST_BINARY_DIRECTORY.rst new file mode 100644 index 0000000..8413e37 --- /dev/null +++ b/Help/variable/CTEST_BINARY_DIRECTORY.rst @@ -0,0 +1,7 @@ +CTEST_BINARY_DIRECTORY +---------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``BuildDirectory`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_BUILD_COMMAND.rst b/Help/variable/CTEST_BUILD_COMMAND.rst new file mode 100644 index 0000000..31c44e2 --- /dev/null +++ b/Help/variable/CTEST_BUILD_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_BUILD_COMMAND +------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``MakeCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_BUILD_NAME.rst b/Help/variable/CTEST_BUILD_NAME.rst new file mode 100644 index 0000000..3d08397 --- /dev/null +++ b/Help/variable/CTEST_BUILD_NAME.rst @@ -0,0 +1,7 @@ +CTEST_BUILD_NAME +---------------- + +.. versionadded:: 3.1 + +Specify the CTest ``BuildName`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_BZR_COMMAND.rst b/Help/variable/CTEST_BZR_COMMAND.rst new file mode 100644 index 0000000..0c05d1a --- /dev/null +++ b/Help/variable/CTEST_BZR_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_BZR_COMMAND +----------------- + +.. versionadded:: 3.1 + +Specify the CTest ``BZRCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_BZR_UPDATE_OPTIONS.rst b/Help/variable/CTEST_BZR_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..4dd5e5b --- /dev/null +++ b/Help/variable/CTEST_BZR_UPDATE_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_BZR_UPDATE_OPTIONS +------------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``BZRUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CHANGE_ID.rst b/Help/variable/CTEST_CHANGE_ID.rst new file mode 100644 index 0000000..a6d15f7 --- /dev/null +++ b/Help/variable/CTEST_CHANGE_ID.rst @@ -0,0 +1,11 @@ +CTEST_CHANGE_ID +--------------- + +.. versionadded:: 3.4 + +Specify the CTest ``ChangeId`` setting +in a :manual:`ctest(1)` dashboard client script. + +This setting allows CTest to pass arbitrary information about this +build up to CDash. One use of this feature is to allow CDash to +post comments on your pull request if anything goes wrong with your build. diff --git a/Help/variable/CTEST_CHECKOUT_COMMAND.rst b/Help/variable/CTEST_CHECKOUT_COMMAND.rst new file mode 100644 index 0000000..852c28e --- /dev/null +++ b/Help/variable/CTEST_CHECKOUT_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_CHECKOUT_COMMAND +---------------------- + +.. versionadded:: 3.1 + +Tell the :command:`ctest_start` command how to checkout or initialize +the source directory in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CONFIGURATION_TYPE.rst b/Help/variable/CTEST_CONFIGURATION_TYPE.rst new file mode 100644 index 0000000..932f81d --- /dev/null +++ b/Help/variable/CTEST_CONFIGURATION_TYPE.rst @@ -0,0 +1,10 @@ +CTEST_CONFIGURATION_TYPE +------------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``DefaultCTestConfigurationType`` setting +in a :manual:`ctest(1)` dashboard client script. + +If the configuration type is set via :option:`-C \<cfg\> <ctest -C>` from the command line +then this variable is populated accordingly. diff --git a/Help/variable/CTEST_CONFIGURE_COMMAND.rst b/Help/variable/CTEST_CONFIGURE_COMMAND.rst new file mode 100644 index 0000000..992ef47 --- /dev/null +++ b/Help/variable/CTEST_CONFIGURE_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_CONFIGURE_COMMAND +----------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``ConfigureCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_COVERAGE_COMMAND.rst b/Help/variable/CTEST_COVERAGE_COMMAND.rst new file mode 100644 index 0000000..f5425cb --- /dev/null +++ b/Help/variable/CTEST_COVERAGE_COMMAND.rst @@ -0,0 +1,62 @@ +CTEST_COVERAGE_COMMAND +---------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``CoverageCommand`` setting +in a :manual:`ctest(1)` dashboard client script. + +Cobertura +''''''''' + +Using `Cobertura`_ as the coverage generation within your multi-module +Java project can generate a series of XML files. + +The Cobertura Coverage parser expects to read the coverage data from a +single XML file which contains the coverage data for all modules. +Cobertura has a program with the ability to merge given ``cobertura.ser`` files +and then another program to generate a combined XML file from the previous +merged file. For command line testing, this can be done by hand prior to +CTest looking for the coverage files. For script builds, +set the ``CTEST_COVERAGE_COMMAND`` variable to point to a file which will +perform these same steps, such as a ``.sh`` or ``.bat`` file. + +.. code-block:: cmake + + set(CTEST_COVERAGE_COMMAND .../run-coverage-and-consolidate.sh) + +where the ``run-coverage-and-consolidate.sh`` script is perhaps created by +the :command:`configure_file` command and might contain the following code: + +.. code-block:: bash + + #!/usr/bin/env bash + CoberturaFiles="$(find "/path/to/source" -name "cobertura.ser")" + SourceDirs="$(find "/path/to/source" -name "java" -type d)" + cobertura-merge --datafile coberturamerge.ser $CoberturaFiles + cobertura-report --datafile coberturamerge.ser --destination . \ + --format xml $SourceDirs + +The script uses ``find`` to capture the paths to all of the ``cobertura.ser`` +files found below the project's source directory. It keeps the list of files +and supplies it as an argument to the ``cobertura-merge`` program. The +``--datafile`` argument signifies where the result of the merge will be kept. + +The combined ``coberturamerge.ser`` file is then used to generate the XML report +using the ``cobertura-report`` program. The call to the cobertura-report +program requires some named arguments. + +``--datafila`` + path to the merged ``.ser`` file + +``--destination`` + path to put the output files(s) + +``--format`` + file format to write output in: xml or html + +The rest of the supplied arguments consist of the full paths to the +``/src/main/java`` directories of each module within the source tree. These +directories are needed and should not be forgotten. + +.. _`Cobertura`: http://cobertura.github.io/cobertura/ diff --git a/Help/variable/CTEST_COVERAGE_EXTRA_FLAGS.rst b/Help/variable/CTEST_COVERAGE_EXTRA_FLAGS.rst new file mode 100644 index 0000000..39d9b5d --- /dev/null +++ b/Help/variable/CTEST_COVERAGE_EXTRA_FLAGS.rst @@ -0,0 +1,7 @@ +CTEST_COVERAGE_EXTRA_FLAGS +-------------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``CoverageExtraFlags`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CURL_OPTIONS.rst b/Help/variable/CTEST_CURL_OPTIONS.rst new file mode 100644 index 0000000..14af4e4 --- /dev/null +++ b/Help/variable/CTEST_CURL_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_CURL_OPTIONS +------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``CurlOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CUSTOM_COVERAGE_EXCLUDE.rst b/Help/variable/CTEST_CUSTOM_COVERAGE_EXCLUDE.rst new file mode 100644 index 0000000..d5893c9 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_COVERAGE_EXCLUDE.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_COVERAGE_EXCLUDE +----------------------------- + +A list of regular expressions which will be used to exclude files by their +path from coverage output by the :command:`ctest_coverage` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_ERROR_EXCEPTION.rst b/Help/variable/CTEST_CUSTOM_ERROR_EXCEPTION.rst new file mode 100644 index 0000000..b8ea1e9 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_ERROR_EXCEPTION.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_ERROR_EXCEPTION +---------------------------- + +A list of regular expressions which will be used to exclude when detecting +error messages in build outputs by the :command:`ctest_build` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_ERROR_MATCH.rst b/Help/variable/CTEST_CUSTOM_ERROR_MATCH.rst new file mode 100644 index 0000000..e8f4ad4 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_ERROR_MATCH.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_ERROR_MATCH +------------------------ + +A list of regular expressions which will be used to detect error messages in +build outputs by the :command:`ctest_build` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_ERROR_POST_CONTEXT.rst b/Help/variable/CTEST_CUSTOM_ERROR_POST_CONTEXT.rst new file mode 100644 index 0000000..31c99e7 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_ERROR_POST_CONTEXT.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_ERROR_POST_CONTEXT +------------------------------- + +The number of lines to include as context which follow an error message by the +:command:`ctest_build` command. The default is 10. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT.rst b/Help/variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT.rst new file mode 100644 index 0000000..ae03a5c --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_ERROR_PRE_CONTEXT +------------------------------ + +The number of lines to include as context which precede an error message by +the :command:`ctest_build` command. The default is 10. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst new file mode 100644 index 0000000..007cfe0 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst @@ -0,0 +1,15 @@ +CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE +-------------------------------------------- + +When saving a failing test's output, this is the maximum size, in bytes, that +will be collected by the :command:`ctest_test` command. Defaults to 307200 +(300 KiB). See :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` for possible +truncation modes. + +If a test's output contains the literal string "CTEST_FULL_OUTPUT", +the output will not be truncated and may exceed the maximum size. + +.. include:: CTEST_CUSTOM_XXX.txt + +For controlling the output collection of passing tests, see +:variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`. diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS.rst new file mode 100644 index 0000000..920cb04 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS.rst @@ -0,0 +1,8 @@ +CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS +------------------------------------- + +The maximum number of errors in a single build step which will be detected. +After this, the :command:`ctest_test` command will truncate the output. +Defaults to 50. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS.rst new file mode 100644 index 0000000..a1f1cc1 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS.rst @@ -0,0 +1,8 @@ +CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS +--------------------------------------- + +The maximum number of warnings in a single build step which will be detected. +After this, the :command:`ctest_test` command will truncate the output. +Defaults to 50. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst new file mode 100644 index 0000000..8545fc4 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst @@ -0,0 +1,15 @@ +CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE +-------------------------------------------- + +When saving a passing test's output, this is the maximum size, in bytes, that +will be collected by the :command:`ctest_test` command. Defaults to 1024 +(1 KiB). See :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` for possible +truncation modes. + +If a test's output contains the literal string "CTEST_FULL_OUTPUT", +the output will not be truncated and may exceed the maximum size. + +.. include:: CTEST_CUSTOM_XXX.txt + +For controlling the output collection of failing tests, see +:variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE`. diff --git a/Help/variable/CTEST_CUSTOM_MEMCHECK_IGNORE.rst b/Help/variable/CTEST_CUSTOM_MEMCHECK_IGNORE.rst new file mode 100644 index 0000000..578576c --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_MEMCHECK_IGNORE.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_MEMCHECK_IGNORE +---------------------------- + +A list of regular expressions to use to exclude tests during the +:command:`ctest_memcheck` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_POST_MEMCHECK.rst b/Help/variable/CTEST_CUSTOM_POST_MEMCHECK.rst new file mode 100644 index 0000000..40291fe --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_POST_MEMCHECK.rst @@ -0,0 +1,6 @@ +CTEST_CUSTOM_POST_MEMCHECK +-------------------------- + +A list of commands to run at the end of the :command:`ctest_memcheck` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_POST_TEST.rst b/Help/variable/CTEST_CUSTOM_POST_TEST.rst new file mode 100644 index 0000000..791292c --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_POST_TEST.rst @@ -0,0 +1,6 @@ +CTEST_CUSTOM_POST_TEST +---------------------- + +A list of commands to run at the end of the :command:`ctest_test` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_PRE_MEMCHECK.rst b/Help/variable/CTEST_CUSTOM_PRE_MEMCHECK.rst new file mode 100644 index 0000000..00de8aa --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_PRE_MEMCHECK.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_PRE_MEMCHECK +------------------------- + +A list of commands to run at the start of the :command:`ctest_memcheck` +command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_PRE_TEST.rst b/Help/variable/CTEST_CUSTOM_PRE_TEST.rst new file mode 100644 index 0000000..6af7152 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_PRE_TEST.rst @@ -0,0 +1,6 @@ +CTEST_CUSTOM_PRE_TEST +---------------------- + +A list of commands to run at the start of the :command:`ctest_test` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst b/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst new file mode 100644 index 0000000..7b1a4b8 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_TESTS_IGNORE +------------------------- + +A list of test names to be excluded from the set of tests run by the +:command:`ctest_test` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION.rst b/Help/variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION.rst new file mode 100644 index 0000000..2d4219e --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION.rst @@ -0,0 +1,12 @@ +CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION +----------------------------------- + +.. versionadded:: 3.24 + +Set the test output truncation mode in case a maximum size is configured +via the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE` or +:variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` variables. +By default the ``tail`` of the output will be truncated. Other possible +values are ``middle`` and ``head``. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst b/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst new file mode 100644 index 0000000..a03d473 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_WARNING_EXCEPTION +------------------------------ + +A list of regular expressions which will be used to exclude when detecting +warning messages in build outputs by the :command:`ctest_build` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst b/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst new file mode 100644 index 0000000..18aa6b3 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst @@ -0,0 +1,7 @@ +CTEST_CUSTOM_WARNING_MATCH +-------------------------- + +A list of regular expressions which will be used to detect warning messages in +build outputs by the :command:`ctest_build` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_XXX.txt b/Help/variable/CTEST_CUSTOM_XXX.txt new file mode 100644 index 0000000..02d1547 --- /dev/null +++ b/Help/variable/CTEST_CUSTOM_XXX.txt @@ -0,0 +1,2 @@ +It is initialized by :manual:`ctest(1)`, but may be edited in a ``CTestCustom`` +file. See :command:`ctest_read_custom_files` documentation. diff --git a/Help/variable/CTEST_CVS_CHECKOUT.rst b/Help/variable/CTEST_CVS_CHECKOUT.rst new file mode 100644 index 0000000..32cf9eb --- /dev/null +++ b/Help/variable/CTEST_CVS_CHECKOUT.rst @@ -0,0 +1,6 @@ +CTEST_CVS_CHECKOUT +------------------ + +.. versionadded:: 3.1 + +Deprecated. Use :variable:`CTEST_CHECKOUT_COMMAND` instead. diff --git a/Help/variable/CTEST_CVS_COMMAND.rst b/Help/variable/CTEST_CVS_COMMAND.rst new file mode 100644 index 0000000..7932070 --- /dev/null +++ b/Help/variable/CTEST_CVS_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_CVS_COMMAND +----------------- + +.. versionadded:: 3.1 + +Specify the CTest ``CVSCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CVS_UPDATE_OPTIONS.rst b/Help/variable/CTEST_CVS_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..359e708 --- /dev/null +++ b/Help/variable/CTEST_CVS_UPDATE_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_CVS_UPDATE_OPTIONS +------------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``CVSUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_LOCATION.rst b/Help/variable/CTEST_DROP_LOCATION.rst new file mode 100644 index 0000000..f66793b --- /dev/null +++ b/Help/variable/CTEST_DROP_LOCATION.rst @@ -0,0 +1,7 @@ +CTEST_DROP_LOCATION +------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``DropLocation`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_METHOD.rst b/Help/variable/CTEST_DROP_METHOD.rst new file mode 100644 index 0000000..3a84658 --- /dev/null +++ b/Help/variable/CTEST_DROP_METHOD.rst @@ -0,0 +1,7 @@ +CTEST_DROP_METHOD +----------------- + +.. versionadded:: 3.1 + +Specify the CTest ``DropMethod`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_SITE.rst b/Help/variable/CTEST_DROP_SITE.rst new file mode 100644 index 0000000..9c871e3 --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE.rst @@ -0,0 +1,7 @@ +CTEST_DROP_SITE +--------------- + +.. versionadded:: 3.1 + +Specify the CTest ``DropSite`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_SITE_CDASH.rst b/Help/variable/CTEST_DROP_SITE_CDASH.rst new file mode 100644 index 0000000..dcdb286 --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE_CDASH.rst @@ -0,0 +1,7 @@ +CTEST_DROP_SITE_CDASH +--------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``IsCDash`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_SITE_PASSWORD.rst b/Help/variable/CTEST_DROP_SITE_PASSWORD.rst new file mode 100644 index 0000000..8259651 --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE_PASSWORD.rst @@ -0,0 +1,7 @@ +CTEST_DROP_SITE_PASSWORD +------------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``DropSitePassword`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_SITE_USER.rst b/Help/variable/CTEST_DROP_SITE_USER.rst new file mode 100644 index 0000000..8d2e3a3 --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE_USER.rst @@ -0,0 +1,7 @@ +CTEST_DROP_SITE_USER +-------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``DropSiteUser`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_EXTRA_COVERAGE_GLOB.rst b/Help/variable/CTEST_EXTRA_COVERAGE_GLOB.rst new file mode 100644 index 0000000..1d7e8d4 --- /dev/null +++ b/Help/variable/CTEST_EXTRA_COVERAGE_GLOB.rst @@ -0,0 +1,9 @@ +CTEST_EXTRA_COVERAGE_GLOB +------------------------- + +.. versionadded:: 3.4 + +A list of regular expressions which will be used to find files which should be +covered by the :command:`ctest_coverage` command. + +.. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_GIT_COMMAND.rst b/Help/variable/CTEST_GIT_COMMAND.rst new file mode 100644 index 0000000..eb9b440 --- /dev/null +++ b/Help/variable/CTEST_GIT_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_GIT_COMMAND +----------------- + +.. versionadded:: 3.1 + +Specify the CTest ``GITCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_GIT_INIT_SUBMODULES.rst b/Help/variable/CTEST_GIT_INIT_SUBMODULES.rst new file mode 100644 index 0000000..529bfc7 --- /dev/null +++ b/Help/variable/CTEST_GIT_INIT_SUBMODULES.rst @@ -0,0 +1,7 @@ +CTEST_GIT_INIT_SUBMODULES +------------------------- + +.. versionadded:: 3.6 + +Specify the CTest ``GITInitSubmodules`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst b/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst new file mode 100644 index 0000000..82a8a6a --- /dev/null +++ b/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst @@ -0,0 +1,7 @@ +CTEST_GIT_UPDATE_CUSTOM +----------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``GITUpdateCustom`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_GIT_UPDATE_OPTIONS.rst b/Help/variable/CTEST_GIT_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..1568239 --- /dev/null +++ b/Help/variable/CTEST_GIT_UPDATE_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_GIT_UPDATE_OPTIONS +------------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``GITUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_HG_COMMAND.rst b/Help/variable/CTEST_HG_COMMAND.rst new file mode 100644 index 0000000..3372fe4 --- /dev/null +++ b/Help/variable/CTEST_HG_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_HG_COMMAND +---------------- + +.. versionadded:: 3.1 + +Specify the CTest ``HGCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_HG_UPDATE_OPTIONS.rst b/Help/variable/CTEST_HG_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..85c6b03 --- /dev/null +++ b/Help/variable/CTEST_HG_UPDATE_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_HG_UPDATE_OPTIONS +----------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``HGUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst b/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst new file mode 100644 index 0000000..dd6d125 --- /dev/null +++ b/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst @@ -0,0 +1,7 @@ +CTEST_LABELS_FOR_SUBPROJECTS +---------------------------- + +.. versionadded:: 3.10 + +Specify the CTest ``LabelsForSubprojects`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst b/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst new file mode 100644 index 0000000..25f1bd9 --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_MEMORYCHECK_COMMAND +------------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``MemoryCheckCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS.rst b/Help/variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS.rst new file mode 100644 index 0000000..51830d5 --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_MEMORYCHECK_COMMAND_OPTIONS +--------------------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``MemoryCheckCommandOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS.rst b/Help/variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS.rst new file mode 100644 index 0000000..b6fee2e --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS.rst @@ -0,0 +1,12 @@ +CTEST_MEMORYCHECK_SANITIZER_OPTIONS +----------------------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``MemoryCheckSanitizerOptions`` setting +in a :manual:`ctest(1)` dashboard client script. + +CTest prepends correct sanitizer options ``*_OPTIONS`` +environment variable to executed command. CTests adds +its own ``log_path`` to sanitizer options, don't provide your +own ``log_path``. diff --git a/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst b/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst new file mode 100644 index 0000000..a61a3ef --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst @@ -0,0 +1,7 @@ +CTEST_MEMORYCHECK_SUPPRESSIONS_FILE +----------------------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``MemoryCheckSuppressionFile`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_MEMORYCHECK_TYPE.rst b/Help/variable/CTEST_MEMORYCHECK_TYPE.rst new file mode 100644 index 0000000..80353a4 --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_TYPE.rst @@ -0,0 +1,10 @@ +CTEST_MEMORYCHECK_TYPE +---------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``MemoryCheckType`` setting +in a :manual:`ctest(1)` dashboard client script. +Valid values are ``Valgrind``, ``Purify``, ``BoundsChecker``, ``DrMemory``, +``CudaSanitizer``, ``ThreadSanitizer``, ``AddressSanitizer``, ``LeakSanitizer``, +``MemorySanitizer`` and ``UndefinedBehaviorSanitizer``. diff --git a/Help/variable/CTEST_NIGHTLY_START_TIME.rst b/Help/variable/CTEST_NIGHTLY_START_TIME.rst new file mode 100644 index 0000000..2d707d5 --- /dev/null +++ b/Help/variable/CTEST_NIGHTLY_START_TIME.rst @@ -0,0 +1,11 @@ +CTEST_NIGHTLY_START_TIME +------------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``NightlyStartTime`` setting in a :manual:`ctest(1)` +dashboard client script. + +Note that this variable must always be set for a nightly build in a +dashboard script. It is needed so that nightly builds can be properly grouped +together in CDash. diff --git a/Help/variable/CTEST_P4_CLIENT.rst b/Help/variable/CTEST_P4_CLIENT.rst new file mode 100644 index 0000000..0778c5b --- /dev/null +++ b/Help/variable/CTEST_P4_CLIENT.rst @@ -0,0 +1,7 @@ +CTEST_P4_CLIENT +--------------- + +.. versionadded:: 3.1 + +Specify the CTest ``P4Client`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_P4_COMMAND.rst b/Help/variable/CTEST_P4_COMMAND.rst new file mode 100644 index 0000000..5cc2a81 --- /dev/null +++ b/Help/variable/CTEST_P4_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_P4_COMMAND +---------------- + +.. versionadded:: 3.1 + +Specify the CTest ``P4Command`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_P4_OPTIONS.rst b/Help/variable/CTEST_P4_OPTIONS.rst new file mode 100644 index 0000000..01b6534 --- /dev/null +++ b/Help/variable/CTEST_P4_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_P4_OPTIONS +---------------- + +.. versionadded:: 3.1 + +Specify the CTest ``P4Options`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_P4_UPDATE_OPTIONS.rst b/Help/variable/CTEST_P4_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..365aa3f --- /dev/null +++ b/Help/variable/CTEST_P4_UPDATE_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_P4_UPDATE_OPTIONS +----------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``P4UpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_RESOURCE_SPEC_FILE.rst b/Help/variable/CTEST_RESOURCE_SPEC_FILE.rst new file mode 100644 index 0000000..8e9bf01 --- /dev/null +++ b/Help/variable/CTEST_RESOURCE_SPEC_FILE.rst @@ -0,0 +1,12 @@ +CTEST_RESOURCE_SPEC_FILE +------------------------ + +.. versionadded:: 3.18 + +Specify the CTest ``ResourceSpecFile`` setting in a :manual:`ctest(1)` +dashboard client script. + +This can also be used to specify the resource spec file from a CMake build. If +no ``RESOURCE_SPEC_FILE`` is passed to :command:`ctest_test`, and +``CTEST_RESOURCE_SPEC_FILE`` is not specified in the dashboard script, the +value of this variable from the build is used. diff --git a/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst b/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst new file mode 100644 index 0000000..8cb6eaa --- /dev/null +++ b/Help/variable/CTEST_RUN_CURRENT_SCRIPT.rst @@ -0,0 +1,7 @@ +CTEST_RUN_CURRENT_SCRIPT +------------------------ + +.. versionadded:: 3.11 + +Setting this to 0 prevents :manual:`ctest(1)` from being run again when it +reaches the end of a script run by calling :option:`ctest -S`. diff --git a/Help/variable/CTEST_SCP_COMMAND.rst b/Help/variable/CTEST_SCP_COMMAND.rst new file mode 100644 index 0000000..155b058 --- /dev/null +++ b/Help/variable/CTEST_SCP_COMMAND.rst @@ -0,0 +1,6 @@ +CTEST_SCP_COMMAND +----------------- + +.. versionadded:: 3.1 + +Legacy option. Not used. diff --git a/Help/variable/CTEST_SCRIPT_DIRECTORY.rst b/Help/variable/CTEST_SCRIPT_DIRECTORY.rst new file mode 100644 index 0000000..77d4e58 --- /dev/null +++ b/Help/variable/CTEST_SCRIPT_DIRECTORY.rst @@ -0,0 +1,5 @@ +CTEST_SCRIPT_DIRECTORY +---------------------- + +The directory containing the top-level CTest script. +The concept is similar to :variable:`CMAKE_SOURCE_DIR`. diff --git a/Help/variable/CTEST_SITE.rst b/Help/variable/CTEST_SITE.rst new file mode 100644 index 0000000..526e6ed --- /dev/null +++ b/Help/variable/CTEST_SITE.rst @@ -0,0 +1,7 @@ +CTEST_SITE +---------- + +.. versionadded:: 3.1 + +Specify the CTest ``Site`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SOURCE_DIRECTORY.rst b/Help/variable/CTEST_SOURCE_DIRECTORY.rst new file mode 100644 index 0000000..4c6ac54 --- /dev/null +++ b/Help/variable/CTEST_SOURCE_DIRECTORY.rst @@ -0,0 +1,7 @@ +CTEST_SOURCE_DIRECTORY +---------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``SourceDirectory`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT.rst b/Help/variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT.rst new file mode 100644 index 0000000..175885a --- /dev/null +++ b/Help/variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT.rst @@ -0,0 +1,7 @@ +CTEST_SUBMIT_INACTIVITY_TIMEOUT +------------------------------- + +.. versionadded:: 3.23 + +Specify the CTest ``SubmitInactivityTimeout`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SUBMIT_URL.rst b/Help/variable/CTEST_SUBMIT_URL.rst new file mode 100644 index 0000000..b6e7f68 --- /dev/null +++ b/Help/variable/CTEST_SUBMIT_URL.rst @@ -0,0 +1,7 @@ +CTEST_SUBMIT_URL +---------------- + +.. versionadded:: 3.14 + +Specify the CTest ``SubmitURL`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SVN_COMMAND.rst b/Help/variable/CTEST_SVN_COMMAND.rst new file mode 100644 index 0000000..e97acd0 --- /dev/null +++ b/Help/variable/CTEST_SVN_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_SVN_COMMAND +----------------- + +.. versionadded:: 3.1 + +Specify the CTest ``SVNCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SVN_OPTIONS.rst b/Help/variable/CTEST_SVN_OPTIONS.rst new file mode 100644 index 0000000..5326e20 --- /dev/null +++ b/Help/variable/CTEST_SVN_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_SVN_OPTIONS +----------------- + +.. versionadded:: 3.1 + +Specify the CTest ``SVNOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SVN_UPDATE_OPTIONS.rst b/Help/variable/CTEST_SVN_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..24e0bbf --- /dev/null +++ b/Help/variable/CTEST_SVN_UPDATE_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_SVN_UPDATE_OPTIONS +------------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``SVNUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_TEST_LOAD.rst b/Help/variable/CTEST_TEST_LOAD.rst new file mode 100644 index 0000000..b6a9d62 --- /dev/null +++ b/Help/variable/CTEST_TEST_LOAD.rst @@ -0,0 +1,9 @@ +CTEST_TEST_LOAD +--------------- + +.. versionadded:: 3.4 + +Specify the ``TestLoad`` setting in the :ref:`CTest Test Step` +of a :manual:`ctest(1)` dashboard client script. This sets the +default value for the ``TEST_LOAD`` option of the :command:`ctest_test` +command. diff --git a/Help/variable/CTEST_TEST_TIMEOUT.rst b/Help/variable/CTEST_TEST_TIMEOUT.rst new file mode 100644 index 0000000..61d9191 --- /dev/null +++ b/Help/variable/CTEST_TEST_TIMEOUT.rst @@ -0,0 +1,7 @@ +CTEST_TEST_TIMEOUT +------------------ + +.. versionadded:: 3.1 + +Specify the CTest ``TimeOut`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_TRIGGER_SITE.rst b/Help/variable/CTEST_TRIGGER_SITE.rst new file mode 100644 index 0000000..6abb852 --- /dev/null +++ b/Help/variable/CTEST_TRIGGER_SITE.rst @@ -0,0 +1,6 @@ +CTEST_TRIGGER_SITE +------------------ + +.. versionadded:: 3.1 + +Legacy option. Not used. diff --git a/Help/variable/CTEST_UPDATE_COMMAND.rst b/Help/variable/CTEST_UPDATE_COMMAND.rst new file mode 100644 index 0000000..c4ed645 --- /dev/null +++ b/Help/variable/CTEST_UPDATE_COMMAND.rst @@ -0,0 +1,7 @@ +CTEST_UPDATE_COMMAND +-------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``UpdateCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_UPDATE_OPTIONS.rst b/Help/variable/CTEST_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..96c4b6c --- /dev/null +++ b/Help/variable/CTEST_UPDATE_OPTIONS.rst @@ -0,0 +1,7 @@ +CTEST_UPDATE_OPTIONS +-------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``UpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst b/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst new file mode 100644 index 0000000..f7c863c --- /dev/null +++ b/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst @@ -0,0 +1,7 @@ +CTEST_UPDATE_VERSION_ONLY +------------------------- + +.. versionadded:: 3.1 + +Specify the CTest :ref:`UpdateVersionOnly <UpdateVersionOnly>` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_UPDATE_VERSION_OVERRIDE.rst b/Help/variable/CTEST_UPDATE_VERSION_OVERRIDE.rst new file mode 100644 index 0000000..87918cb --- /dev/null +++ b/Help/variable/CTEST_UPDATE_VERSION_OVERRIDE.rst @@ -0,0 +1,7 @@ +CTEST_UPDATE_VERSION_OVERRIDE +----------------------------- + +.. versionadded:: 3.15 + +Specify the CTest :ref:`UpdateVersionOverride <UpdateVersionOverride>` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_USE_LAUNCHERS.rst b/Help/variable/CTEST_USE_LAUNCHERS.rst new file mode 100644 index 0000000..728cdc5 --- /dev/null +++ b/Help/variable/CTEST_USE_LAUNCHERS.rst @@ -0,0 +1,7 @@ +CTEST_USE_LAUNCHERS +------------------- + +.. versionadded:: 3.1 + +Specify the CTest ``UseLaunchers`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CYGWIN.rst b/Help/variable/CYGWIN.rst new file mode 100644 index 0000000..0039e07 --- /dev/null +++ b/Help/variable/CYGWIN.rst @@ -0,0 +1,6 @@ +CYGWIN +------ + +``True`` for Cygwin. + +Set to ``true`` when using Cygwin. diff --git a/Help/variable/ENV.rst b/Help/variable/ENV.rst new file mode 100644 index 0000000..6791853 --- /dev/null +++ b/Help/variable/ENV.rst @@ -0,0 +1,13 @@ +ENV +--- + +Operator to read environment variables. + +Use the syntax ``$ENV{VAR}`` to read environment variable ``VAR``. + +To test whether an environment variable is defined, use the signature +``if(DEFINED ENV{<name>})`` of the :command:`if` command. + +For general information on environment variables, see the +:ref:`Environment Variables <CMake Language Environment Variables>` +section in the :manual:`cmake-language(7)` manual. diff --git a/Help/variable/EXECUTABLE_OUTPUT_PATH.rst b/Help/variable/EXECUTABLE_OUTPUT_PATH.rst new file mode 100644 index 0000000..245b9eb --- /dev/null +++ b/Help/variable/EXECUTABLE_OUTPUT_PATH.rst @@ -0,0 +1,8 @@ +EXECUTABLE_OUTPUT_PATH +---------------------- + +Old executable location variable. + +The target property :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` supersedes this +variable for a target if it is set. Executable targets are otherwise placed in +this directory. diff --git a/Help/variable/GHSMULTI.rst b/Help/variable/GHSMULTI.rst new file mode 100644 index 0000000..7a90b84 --- /dev/null +++ b/Help/variable/GHSMULTI.rst @@ -0,0 +1,9 @@ +GHSMULTI +-------- + +.. versionadded:: 3.3 + +``1`` when using :generator:`Green Hills MULTI` generator. + +Also, Set to ``1`` when the target system is a Green Hills platform +(i.e. When :variable:`CMAKE_SYSTEM_NAME` is ``GHS-MULTI``). diff --git a/Help/variable/IGNORE_SEARCH_LOCATIONS.txt b/Help/variable/IGNORE_SEARCH_LOCATIONS.txt new file mode 100644 index 0000000..a98f359 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_LOCATIONS.txt @@ -0,0 +1,4 @@ +Ignoring search locations can be useful in cross-compiling environments where +some system directories contain incompatible but possibly linkable libraries. +For example, on cross-compiled cluster environments, this allows a user to +ignore directories containing libraries meant for the front-end machine. diff --git a/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt b/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt new file mode 100644 index 0000000..a32a189 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt @@ -0,0 +1,2 @@ +By default, |CMAKE_IGNORE_VAR| is empty. It is intended to be set by the +project or the end user. diff --git a/Help/variable/IGNORE_SEARCH_PATH.txt b/Help/variable/IGNORE_SEARCH_PATH.txt new file mode 100644 index 0000000..0811e02 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_PATH.txt @@ -0,0 +1,19 @@ +:ref:`Semicolon-separated list <CMake Language Lists>` of directories +to be ignored by the various ``find...()`` commands. + +For :command:`find_program`, :command:`find_library`, :command:`find_file`, +and :command:`find_path`, any file found in one of the listed directories +will be ignored. The listed directories do not apply recursively, so any +subdirectories to be ignored must also be explicitly listed. +|CMAKE_IGNORE_VAR| does not affect the search *prefixes* used by these +four commands. To ignore individual paths under a search prefix +(e.g. ``bin``, ``include``, ``lib``, etc.), each path must be listed in +|CMAKE_IGNORE_VAR| as a full absolute path. |CMAKE_IGNORE_PREFIX_VAR| +provides a more appropriate way to ignore a whole search prefix. + +:command:`find_package` is also affected by |CMAKE_IGNORE_VAR|, but only +for *Config mode* searches. Any ``<Name>Config.cmake`` or +``<name>-config.cmake`` file found in one of the specified directories +will be ignored. In addition, any search *prefix* found in |CMAKE_IGNORE_VAR| +will be skipped for backward compatibility reasons, but new code should +prefer to use |CMAKE_IGNORE_PREFIX_VAR| to ignore prefixes instead. diff --git a/Help/variable/IGNORE_SEARCH_PREFIX.txt b/Help/variable/IGNORE_SEARCH_PREFIX.txt new file mode 100644 index 0000000..f5ec3dc --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_PREFIX.txt @@ -0,0 +1,6 @@ +:ref:`Semicolon-separated list <CMake Language Lists>` of search *prefixes* +to be ignored by the :command:`find_program`, :command:`find_library`, +:command:`find_file`, and :command:`find_path` commands. +The prefixes are also ignored by the *Config mode* of the +:command:`find_package` command (*Module mode* is unaffected). +To ignore specific directories instead, see |CMAKE_IGNORE_NONPREFIX_VAR|. diff --git a/Help/variable/IGNORE_SEARCH_SYSTEM.txt b/Help/variable/IGNORE_SEARCH_SYSTEM.txt new file mode 100644 index 0000000..78b285d6 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_SYSTEM.txt @@ -0,0 +1,5 @@ +|CMAKE_IGNORE_VAR| is populated by CMake as part of its platform +and toolchain setup. Its purpose is to ignore locations containing +incompatible binaries meant for the host rather than the target platform. +The project or end user should not modify this variable, they should use +|CMAKE_IGNORE_NONSYSTEM_VAR| instead. diff --git a/Help/variable/IOS.rst b/Help/variable/IOS.rst new file mode 100644 index 0000000..b27be55 --- /dev/null +++ b/Help/variable/IOS.rst @@ -0,0 +1,6 @@ +IOS +--- + +.. versionadded:: 3.14 + +Set to ``1`` when the target system (:variable:`CMAKE_SYSTEM_NAME`) is ``iOS``. diff --git a/Help/variable/LIBRARY_OUTPUT_PATH.rst b/Help/variable/LIBRARY_OUTPUT_PATH.rst new file mode 100644 index 0000000..bb4328f --- /dev/null +++ b/Help/variable/LIBRARY_OUTPUT_PATH.rst @@ -0,0 +1,9 @@ +LIBRARY_OUTPUT_PATH +------------------- + +Old library location variable. + +The target properties :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`, +:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` +supersede this variable for a target if they are set. Library targets are +otherwise placed in this directory. diff --git a/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt b/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt new file mode 100644 index 0000000..557886e --- /dev/null +++ b/Help/variable/LINK_GROUP_PREDEFINED_FEATURES.txt @@ -0,0 +1,22 @@ +``RESCAN`` + Some linkers are single-pass only. For such linkers, circular references + between libraries typically result in unresolved symbols. This feature + instructs the linker to search the specified static libraries repeatedly + until no new undefined references are created. + + Normally, a static library is searched only once in the order that it is + specified on the command line. If a symbol in that library is needed to + resolve an undefined symbol referred to by an object in a library that + appears later on the command line, the linker would not be able to resolve + that reference. By grouping the static libraries with the ``RESCAN`` + feature, they will all be searched repeatedly until all possible references + are resolved. This will use linker options like ``--start-group`` and + ``--end-group``, or on SunOS, ``-z rescan-start`` and ``-z rescan-end``. + + Using this feature has a significant performance cost. It is best to use it + only when there are unavoidable circular references between two or more + static libraries. + + This feature is available when using toolchains that target Linux, BSD, and + SunOS. It can also be used when targeting Windows platforms if the GNU + toolchain is used. diff --git a/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt new file mode 100644 index 0000000..9158631 --- /dev/null +++ b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt @@ -0,0 +1,101 @@ +``DEFAULT`` + This feature corresponds to standard linking, essentially equivalent to + using no feature at all. It is typically only used with the + :prop_tgt:`LINK_LIBRARY_OVERRIDE` and + :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties. + +``WHOLE_ARCHIVE`` + Force inclusion of all members of a static library. This feature is only + supported for the following platforms, with limitations as noted: + + * Linux. + * All BSD variants. + * SunOS. + * All Apple variants. The library must be specified as a CMake target name, + a library file name (such as ``libfoo.a``), or a library file path (such as + ``/path/to/libfoo.a``). Due to a limitation of the Apple linker, it + cannot be specified as a plain library name like ``foo``, where ``foo`` + is not a CMake target. + * Windows. When using a MSVC or MSVC-like toolchain, the MSVC version must + be greater than 1900. + * Cygwin. + * MSYS. + +``FRAMEWORK`` + This option tells the linker to search for the specified framework using + the ``-framework`` linker option. It can only be used on Apple platforms, + and only with a linker that understands the option used (i.e. the linker + provided with Xcode, or one compatible with it). + + The framework can be specified as a CMake framework target, a bare framework + name, or a file path. If a target is given, that target must have the + :prop_tgt:`FRAMEWORK` target property set to true. For a file path, if it + contains a directory part, that directory will be added as a framework + search path. + + .. code-block:: cmake + + add_library(lib SHARED ...) + target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>") + + # The constructed linker command line will contain: + # -F/path/to -framework my_framework + + File paths must conform to one of the following patterns (``*`` is a + wildcard, and optional parts are shown as ``[...]``): + + * ``[/path/to/]FwName[.framework]`` + * ``[/path/to/]FwName.framework/FwName[suffix]`` + * ``[/path/to/]FwName.framework/Versions/*/FwName[suffix]`` + + Note that CMake recognizes and automatically handles framework targets, + even without using the :genex:`$<LINK_LIBRARY:FRAMEWORK,...>` expression. + The generator expression can still be used with a CMake target if the + project wants to be explicit about it, but it is not required to do so. + The linker command line may have some differences between using the + generator expression or not, but the final result should be the same. + On the other hand, if a file path is given, CMake will recognize some paths + automatically, but not all cases. The project may want to use + :genex:`$<LINK_LIBRARY:FRAMEWORK,...>` for file paths so that the expected + behavior is clear. + + .. versionadded:: 3.25 + The :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` target property as + well as the ``suffix`` of the framework library name are now supported by + the ``FRAMEWORK`` features. + +``NEEDED_FRAMEWORK`` + This is similar to the ``FRAMEWORK`` feature, except it forces the linker + to link with the framework even if no symbols are used from it. It uses + the ``-needed_framework`` option and has the same linker constraints as + ``FRAMEWORK``. + +``REEXPORT_FRAMEWORK`` + This is similar to the ``FRAMEWORK`` feature, except it tells the linker + that the framework should be available to clients linking to the library + being created. It uses the ``-reexport_framework`` option and has the + same linker constraints as ``FRAMEWORK``. + +``WEAK_FRAMEWORK`` + This is similar to the ``FRAMEWORK`` feature, except it forces the linker + to mark the framework and all references to it as weak imports. It uses + the ``-weak_framework`` option and has the same linker constraints as + ``FRAMEWORK``. + +``NEEDED_LIBRARY`` + This is similar to the ``NEEDED_FRAMEWORK`` feature, except it is for use + with non-framework targets or libraries (Apple platforms only). + It uses the ``-needed_library`` or ``-needed-l`` option as appropriate, + and has the same linker constraints as ``NEEDED_FRAMEWORK``. + +``REEXPORT_LIBRARY`` + This is similar to the ``REEXPORT_FRAMEWORK`` feature, except it is for use + with non-framework targets or libraries (Apple platforms only). + It uses the ``-reexport_library`` or ``-reexport-l`` option as appropriate, + and has the same linker constraints as ``REEXPORT_FRAMEWORK``. + +``WEAK_LIBRARY`` + This is similar to the ``WEAK_FRAMEWORK`` feature, except it is for use + with non-framework targets or libraries (Apple platforms only). + It uses the ``-weak_library`` or ``-weak-l`` option as appropriate, + and has the same linker constraints as ``WEAK_FRAMEWORK``. diff --git a/Help/variable/LINUX.rst b/Help/variable/LINUX.rst new file mode 100644 index 0000000..26379b3 --- /dev/null +++ b/Help/variable/LINUX.rst @@ -0,0 +1,6 @@ +LINUX +----- + +.. versionadded:: 3.25 + +Set to true when the target system is Linux. diff --git a/Help/variable/MINGW.rst b/Help/variable/MINGW.rst new file mode 100644 index 0000000..27c56ea --- /dev/null +++ b/Help/variable/MINGW.rst @@ -0,0 +1,8 @@ +MINGW +----- + +.. versionadded:: 3.2 + +``True`` when using MinGW + +Set to ``true`` when the compiler is some version of MinGW. diff --git a/Help/variable/MSVC.rst b/Help/variable/MSVC.rst new file mode 100644 index 0000000..a2dbc2e --- /dev/null +++ b/Help/variable/MSVC.rst @@ -0,0 +1,7 @@ +MSVC +---- + +Set to ``true`` when the compiler is some version of Microsoft Visual C++ +or another compiler simulating the Visual C++ ``cl`` command-line syntax. + +See also the :variable:`MSVC_VERSION` variable. diff --git a/Help/variable/MSVC10.rst b/Help/variable/MSVC10.rst new file mode 100644 index 0000000..55c6337 --- /dev/null +++ b/Help/variable/MSVC10.rst @@ -0,0 +1,7 @@ +MSVC10 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using the Microsoft Visual Studio ``v100`` toolset +(``cl`` version 16) or another compiler that simulates it. diff --git a/Help/variable/MSVC11.rst b/Help/variable/MSVC11.rst new file mode 100644 index 0000000..17943dc --- /dev/null +++ b/Help/variable/MSVC11.rst @@ -0,0 +1,7 @@ +MSVC11 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using the Microsoft Visual Studio ``v110`` toolset +(``cl`` version 17) or another compiler that simulates it. diff --git a/Help/variable/MSVC12.rst b/Help/variable/MSVC12.rst new file mode 100644 index 0000000..a524fab --- /dev/null +++ b/Help/variable/MSVC12.rst @@ -0,0 +1,7 @@ +MSVC12 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using the Microsoft Visual Studio ``v120`` toolset +(``cl`` version 18) or another compiler that simulates it. diff --git a/Help/variable/MSVC14.rst b/Help/variable/MSVC14.rst new file mode 100644 index 0000000..1eb5183 --- /dev/null +++ b/Help/variable/MSVC14.rst @@ -0,0 +1,9 @@ +MSVC14 +------ + +.. versionadded:: 3.1 + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using the Microsoft Visual Studio ``v140`` or ``v141`` +toolset (``cl`` version 19) or another compiler that simulates it. diff --git a/Help/variable/MSVC60.rst b/Help/variable/MSVC60.rst new file mode 100644 index 0000000..14164bf --- /dev/null +++ b/Help/variable/MSVC60.rst @@ -0,0 +1,8 @@ +MSVC60 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using Microsoft Visual C++ 6.0. + +Set to ``true`` when the compiler is version 6.0 of Microsoft Visual C++. diff --git a/Help/variable/MSVC70.rst b/Help/variable/MSVC70.rst new file mode 100644 index 0000000..ed3b0bb --- /dev/null +++ b/Help/variable/MSVC70.rst @@ -0,0 +1,8 @@ +MSVC70 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using Microsoft Visual C++ 7.0. + +Set to ``true`` when the compiler is version 7.0 of Microsoft Visual C++. diff --git a/Help/variable/MSVC71.rst b/Help/variable/MSVC71.rst new file mode 100644 index 0000000..0237592 --- /dev/null +++ b/Help/variable/MSVC71.rst @@ -0,0 +1,8 @@ +MSVC71 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using Microsoft Visual C++ 7.1. + +Set to ``true`` when the compiler is version 7.1 of Microsoft Visual C++. diff --git a/Help/variable/MSVC80.rst b/Help/variable/MSVC80.rst new file mode 100644 index 0000000..1533218 --- /dev/null +++ b/Help/variable/MSVC80.rst @@ -0,0 +1,7 @@ +MSVC80 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using the Microsoft Visual Studio ``v80`` toolset +(``cl`` version 14) or another compiler that simulates it. diff --git a/Help/variable/MSVC90.rst b/Help/variable/MSVC90.rst new file mode 100644 index 0000000..4981ecf --- /dev/null +++ b/Help/variable/MSVC90.rst @@ -0,0 +1,7 @@ +MSVC90 +------ + +Discouraged. Use the :variable:`MSVC_VERSION` variable instead. + +``True`` when using the Microsoft Visual Studio ``v90`` toolset +(``cl`` version 15) or another compiler that simulates it. diff --git a/Help/variable/MSVC_IDE.rst b/Help/variable/MSVC_IDE.rst new file mode 100644 index 0000000..18e9983 --- /dev/null +++ b/Help/variable/MSVC_IDE.rst @@ -0,0 +1,14 @@ +MSVC_IDE +-------- + +``True`` when using the Microsoft Visual C++ IDE. + +Set to ``true`` when the target platform is the Microsoft Visual C++ IDE, as +opposed to the command line compiler. + +.. note:: + + This variable is only available after compiler detection has been performed, + so it is not available to toolchain files or before the first + :command:`project` or :command:`enable_language` call which uses an + MSVC-like compiler. diff --git a/Help/variable/MSVC_TOOLSET_VERSION.rst b/Help/variable/MSVC_TOOLSET_VERSION.rst new file mode 100644 index 0000000..59479af --- /dev/null +++ b/Help/variable/MSVC_TOOLSET_VERSION.rst @@ -0,0 +1,25 @@ +MSVC_TOOLSET_VERSION +-------------------- + +.. versionadded:: 3.12 + +The toolset version of Microsoft Visual C/C++ being used if any. +If MSVC-like is being used, this variable is set based on the version +of the compiler as given by the :variable:`MSVC_VERSION` variable. + +Known toolset version numbers are:: + + 80 = VS 2005 (8.0) + 90 = VS 2008 (9.0) + 100 = VS 2010 (10.0) + 110 = VS 2012 (11.0) + 120 = VS 2013 (12.0) + 140 = VS 2015 (14.0) + 141 = VS 2017 (15.0) + 142 = VS 2019 (16.0) + 143 = VS 2022 (17.0) + +Compiler versions newer than those known to CMake will be reported +as the latest known toolset version. + +See also the :variable:`MSVC_VERSION` variable. diff --git a/Help/variable/MSVC_VERSION.rst b/Help/variable/MSVC_VERSION.rst new file mode 100644 index 0000000..cbb3a3c --- /dev/null +++ b/Help/variable/MSVC_VERSION.rst @@ -0,0 +1,25 @@ +MSVC_VERSION +------------ + +The version of Microsoft Visual C/C++ being used if any. +If a compiler simulating Visual C++ is being used, this variable is set +to the toolset version simulated as given by the ``_MSC_VER`` +preprocessor definition. + +Known version numbers are:: + + 1200 = VS 6.0 + 1300 = VS 7.0 + 1310 = VS 7.1 + 1400 = VS 8.0 (v80 toolset) + 1500 = VS 9.0 (v90 toolset) + 1600 = VS 10.0 (v100 toolset) + 1700 = VS 11.0 (v110 toolset) + 1800 = VS 12.0 (v120 toolset) + 1900 = VS 14.0 (v140 toolset) + 1910-1919 = VS 15.0 (v141 toolset) + 1920-1929 = VS 16.0 (v142 toolset) + 1930-1939 = VS 17.0 (v143 toolset) + +See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` and +:variable:`MSVC_TOOLSET_VERSION` variable. diff --git a/Help/variable/MSYS.rst b/Help/variable/MSYS.rst new file mode 100644 index 0000000..6be7681 --- /dev/null +++ b/Help/variable/MSYS.rst @@ -0,0 +1,6 @@ +MSYS +---- + +.. versionadded:: 3.14 + +``True`` when using the :generator:`MSYS Makefiles` generator. diff --git a/Help/variable/PROJECT-NAME_BINARY_DIR.rst b/Help/variable/PROJECT-NAME_BINARY_DIR.rst new file mode 100644 index 0000000..49bc558 --- /dev/null +++ b/Help/variable/PROJECT-NAME_BINARY_DIR.rst @@ -0,0 +1,8 @@ +<PROJECT-NAME>_BINARY_DIR +------------------------- + +Top level binary directory for the named project. + +A variable is created with the name used in the :command:`project` command, +and is the binary directory for the project. This can be useful when +:command:`add_subdirectory` is used to connect several projects. diff --git a/Help/variable/PROJECT-NAME_DESCRIPTION.rst b/Help/variable/PROJECT-NAME_DESCRIPTION.rst new file mode 100644 index 0000000..f372f5c --- /dev/null +++ b/Help/variable/PROJECT-NAME_DESCRIPTION.rst @@ -0,0 +1,7 @@ +<PROJECT-NAME>_DESCRIPTION +-------------------------- + +.. versionadded:: 3.12 + +Value given to the ``DESCRIPTION`` option of the most recent call to the +:command:`project` command with project name ``<PROJECT-NAME>``, if any. diff --git a/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst b/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst new file mode 100644 index 0000000..4800b13 --- /dev/null +++ b/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst @@ -0,0 +1,7 @@ +<PROJECT-NAME>_HOMEPAGE_URL +--------------------------- + +.. versionadded:: 3.12 + +Value given to the ``HOMEPAGE_URL`` option of the most recent call to the +:command:`project` command with project name ``<PROJECT-NAME>``, if any. diff --git a/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst b/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst new file mode 100644 index 0000000..ca3a769 --- /dev/null +++ b/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst @@ -0,0 +1,28 @@ +<PROJECT-NAME>_IS_TOP_LEVEL +--------------------------- + +.. versionadded:: 3.21 + +A boolean variable indicating whether the named project was called in a top +level ``CMakeLists.txt`` file. + +To obtain the value from the most recent call to :command:`project` in +the current directory scope or above, see the +:variable:`PROJECT_IS_TOP_LEVEL` variable. + +The variable value will be true in: + +* the top-level directory of the project +* the top-level directory of an external project added by + :module:`ExternalProject` +* a directory added by :command:`add_subdirectory` that does not also contain + a :command:`project` call +* a directory added by :command:`FetchContent_MakeAvailable`, + if the fetched content does not contain a :command:`project` call + +The variable value will be false in: + +* a directory added by :command:`add_subdirectory` that also contains + a :command:`project` call +* a directory added by :command:`FetchContent_MakeAvailable`, + if the fetched content contains a :command:`project` call diff --git a/Help/variable/PROJECT-NAME_SOURCE_DIR.rst b/Help/variable/PROJECT-NAME_SOURCE_DIR.rst new file mode 100644 index 0000000..4df3e22 --- /dev/null +++ b/Help/variable/PROJECT-NAME_SOURCE_DIR.rst @@ -0,0 +1,8 @@ +<PROJECT-NAME>_SOURCE_DIR +------------------------- + +Top level source directory for the named project. + +A variable is created with the name used in the :command:`project` command, +and is the source directory for the project. This can be useful when +:command:`add_subdirectory` is used to connect several projects. diff --git a/Help/variable/PROJECT-NAME_VERSION.rst b/Help/variable/PROJECT-NAME_VERSION.rst new file mode 100644 index 0000000..0f6ed51 --- /dev/null +++ b/Help/variable/PROJECT-NAME_VERSION.rst @@ -0,0 +1,11 @@ +<PROJECT-NAME>_VERSION +---------------------- + +Value given to the ``VERSION`` option of the most recent call to the +:command:`project` command with project name ``<PROJECT-NAME>``, if any. + +See also the component-wise version variables +:variable:`<PROJECT-NAME>_VERSION_MAJOR`, +:variable:`<PROJECT-NAME>_VERSION_MINOR`, +:variable:`<PROJECT-NAME>_VERSION_PATCH`, and +:variable:`<PROJECT-NAME>_VERSION_TWEAK`. diff --git a/Help/variable/PROJECT-NAME_VERSION_MAJOR.rst b/Help/variable/PROJECT-NAME_VERSION_MAJOR.rst new file mode 100644 index 0000000..9e2d755 --- /dev/null +++ b/Help/variable/PROJECT-NAME_VERSION_MAJOR.rst @@ -0,0 +1,5 @@ +<PROJECT-NAME>_VERSION_MAJOR +---------------------------- + +First version number component of the :variable:`<PROJECT-NAME>_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PROJECT-NAME_VERSION_MINOR.rst b/Help/variable/PROJECT-NAME_VERSION_MINOR.rst new file mode 100644 index 0000000..fa2cdab --- /dev/null +++ b/Help/variable/PROJECT-NAME_VERSION_MINOR.rst @@ -0,0 +1,5 @@ +<PROJECT-NAME>_VERSION_MINOR +---------------------------- + +Second version number component of the :variable:`<PROJECT-NAME>_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PROJECT-NAME_VERSION_PATCH.rst b/Help/variable/PROJECT-NAME_VERSION_PATCH.rst new file mode 100644 index 0000000..85b5e6b --- /dev/null +++ b/Help/variable/PROJECT-NAME_VERSION_PATCH.rst @@ -0,0 +1,5 @@ +<PROJECT-NAME>_VERSION_PATCH +---------------------------- + +Third version number component of the :variable:`<PROJECT-NAME>_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PROJECT-NAME_VERSION_TWEAK.rst b/Help/variable/PROJECT-NAME_VERSION_TWEAK.rst new file mode 100644 index 0000000..65c4044 --- /dev/null +++ b/Help/variable/PROJECT-NAME_VERSION_TWEAK.rst @@ -0,0 +1,5 @@ +<PROJECT-NAME>_VERSION_TWEAK +---------------------------- + +Fourth version number component of the :variable:`<PROJECT-NAME>_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PROJECT_BINARY_DIR.rst b/Help/variable/PROJECT_BINARY_DIR.rst new file mode 100644 index 0000000..09e9ef2 --- /dev/null +++ b/Help/variable/PROJECT_BINARY_DIR.rst @@ -0,0 +1,6 @@ +PROJECT_BINARY_DIR +------------------ + +Full path to build directory for project. + +This is the binary directory of the most recent :command:`project` command. diff --git a/Help/variable/PROJECT_DESCRIPTION.rst b/Help/variable/PROJECT_DESCRIPTION.rst new file mode 100644 index 0000000..1fefcdc --- /dev/null +++ b/Help/variable/PROJECT_DESCRIPTION.rst @@ -0,0 +1,11 @@ +PROJECT_DESCRIPTION +------------------- + +.. versionadded:: 3.9 + +Short project description given to the project command. + +This is the description given to the most recently called :command:`project` +command in the current directory scope or above. To obtain the description +of the top level project, see the :variable:`CMAKE_PROJECT_DESCRIPTION` +variable. diff --git a/Help/variable/PROJECT_HOMEPAGE_URL.rst b/Help/variable/PROJECT_HOMEPAGE_URL.rst new file mode 100644 index 0000000..0d2c937 --- /dev/null +++ b/Help/variable/PROJECT_HOMEPAGE_URL.rst @@ -0,0 +1,11 @@ +PROJECT_HOMEPAGE_URL +-------------------- + +.. versionadded:: 3.12 + +The homepage URL of the project. + +This is the homepage URL given to the most recently called :command:`project` +command in the current directory scope or above. To obtain the homepage URL +of the top level project, see the :variable:`CMAKE_PROJECT_HOMEPAGE_URL` +variable. diff --git a/Help/variable/PROJECT_IS_TOP_LEVEL.rst b/Help/variable/PROJECT_IS_TOP_LEVEL.rst new file mode 100644 index 0000000..871dfdb --- /dev/null +++ b/Help/variable/PROJECT_IS_TOP_LEVEL.rst @@ -0,0 +1,39 @@ +PROJECT_IS_TOP_LEVEL +-------------------- + +.. versionadded:: 3.21 + +A boolean variable indicating whether the most recently called +:command:`project` command in the current scope or above was in the top +level ``CMakeLists.txt`` file. + +Some modules should only be included as part of the top level +``CMakeLists.txt`` file to not cause unintended side effects in the build +tree, and this variable can be used to conditionally execute such code. For +example, consider the :module:`CTest` module, which creates targets and +options: + +.. code-block:: cmake + + project(MyProject) + ... + if(PROJECT_IS_TOP_LEVEL) + include(CTest) + endif() + +The variable value will be true in: + +* the top-level directory of the project +* the top-level directory of an external project added by + :module:`ExternalProject` +* a directory added by :command:`add_subdirectory` that does not also contain + a :command:`project` call +* a directory added by :command:`FetchContent_MakeAvailable`, + if the fetched content does not contain a :command:`project` call + +The variable value will be false in: + +* a directory added by :command:`add_subdirectory` that also contains + a :command:`project` call +* a directory added by :command:`FetchContent_MakeAvailable`, + if the fetched content contains a :command:`project` call diff --git a/Help/variable/PROJECT_NAME.rst b/Help/variable/PROJECT_NAME.rst new file mode 100644 index 0000000..672680a --- /dev/null +++ b/Help/variable/PROJECT_NAME.rst @@ -0,0 +1,8 @@ +PROJECT_NAME +------------ + +Name of the project given to the project command. + +This is the name given to the most recently called :command:`project` +command in the current directory scope or above. To obtain the name of +the top level project, see the :variable:`CMAKE_PROJECT_NAME` variable. diff --git a/Help/variable/PROJECT_SOURCE_DIR.rst b/Help/variable/PROJECT_SOURCE_DIR.rst new file mode 100644 index 0000000..b4601c2 --- /dev/null +++ b/Help/variable/PROJECT_SOURCE_DIR.rst @@ -0,0 +1,8 @@ +PROJECT_SOURCE_DIR +------------------ + +This is the source directory of the last call to the +:command:`project` command made in the current directory scope or one +of its parents. Note, it is not affected by calls to +:command:`project` made within a child directory scope (i.e. from +within a call to :command:`add_subdirectory` from the current scope). diff --git a/Help/variable/PROJECT_VERSION.rst b/Help/variable/PROJECT_VERSION.rst new file mode 100644 index 0000000..234558d --- /dev/null +++ b/Help/variable/PROJECT_VERSION.rst @@ -0,0 +1,11 @@ +PROJECT_VERSION +--------------- + +Value given to the ``VERSION`` option of the most recent call to the +:command:`project` command, if any. + +See also the component-wise version variables +:variable:`PROJECT_VERSION_MAJOR`, +:variable:`PROJECT_VERSION_MINOR`, +:variable:`PROJECT_VERSION_PATCH`, and +:variable:`PROJECT_VERSION_TWEAK`. diff --git a/Help/variable/PROJECT_VERSION_MAJOR.rst b/Help/variable/PROJECT_VERSION_MAJOR.rst new file mode 100644 index 0000000..4b6072c --- /dev/null +++ b/Help/variable/PROJECT_VERSION_MAJOR.rst @@ -0,0 +1,5 @@ +PROJECT_VERSION_MAJOR +--------------------- + +First version number component of the :variable:`PROJECT_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PROJECT_VERSION_MINOR.rst b/Help/variable/PROJECT_VERSION_MINOR.rst new file mode 100644 index 0000000..5f31220 --- /dev/null +++ b/Help/variable/PROJECT_VERSION_MINOR.rst @@ -0,0 +1,5 @@ +PROJECT_VERSION_MINOR +--------------------- + +Second version number component of the :variable:`PROJECT_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PROJECT_VERSION_PATCH.rst b/Help/variable/PROJECT_VERSION_PATCH.rst new file mode 100644 index 0000000..ac72ec0 --- /dev/null +++ b/Help/variable/PROJECT_VERSION_PATCH.rst @@ -0,0 +1,5 @@ +PROJECT_VERSION_PATCH +--------------------- + +Third version number component of the :variable:`PROJECT_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PROJECT_VERSION_TWEAK.rst b/Help/variable/PROJECT_VERSION_TWEAK.rst new file mode 100644 index 0000000..d7f96d6 --- /dev/null +++ b/Help/variable/PROJECT_VERSION_TWEAK.rst @@ -0,0 +1,5 @@ +PROJECT_VERSION_TWEAK +--------------------- + +Fourth version number component of the :variable:`PROJECT_VERSION` +variable as set by the :command:`project` command. diff --git a/Help/variable/PackageName_ROOT.rst b/Help/variable/PackageName_ROOT.rst new file mode 100644 index 0000000..98ba20e --- /dev/null +++ b/Help/variable/PackageName_ROOT.rst @@ -0,0 +1,16 @@ +<PackageName>_ROOT +------------------ + +.. versionadded:: 3.12 + +Calls to :command:`find_package(<PackageName>)` will search in prefixes +specified by the ``<PackageName>_ROOT`` CMake variable, where +``<PackageName>`` is the name given to the :command:`find_package` call +and ``_ROOT`` is literal. For example, ``find_package(Foo)`` will search +prefixes specified in the ``Foo_ROOT`` CMake variable (if set). +See policy :policy:`CMP0074`. + +This variable may hold a single prefix or a +:ref:`semicolon-separated list <CMake Language Lists>` of multiple prefixes. + +See also the :envvar:`<PackageName>_ROOT` environment variable. diff --git a/Help/variable/UNIX.rst b/Help/variable/UNIX.rst new file mode 100644 index 0000000..49d8668 --- /dev/null +++ b/Help/variable/UNIX.rst @@ -0,0 +1,7 @@ +UNIX +---- + +Set to ``True`` when the target system is UNIX or UNIX-like +(e.g. :variable:`APPLE` and :variable:`CYGWIN`). The +:variable:`CMAKE_SYSTEM_NAME` variable should be queried if +a more specific understanding of the target system is required. diff --git a/Help/variable/WIN32.rst b/Help/variable/WIN32.rst new file mode 100644 index 0000000..78ab772 --- /dev/null +++ b/Help/variable/WIN32.rst @@ -0,0 +1,4 @@ +WIN32 +----- + +Set to ``True`` when the target system is Windows, including Win64. diff --git a/Help/variable/WINCE.rst b/Help/variable/WINCE.rst new file mode 100644 index 0000000..4dca297 --- /dev/null +++ b/Help/variable/WINCE.rst @@ -0,0 +1,7 @@ +WINCE +----- + +.. versionadded:: 3.1 + +True when the :variable:`CMAKE_SYSTEM_NAME` variable is set +to ``WindowsCE``. diff --git a/Help/variable/WINDOWS_PHONE.rst b/Help/variable/WINDOWS_PHONE.rst new file mode 100644 index 0000000..bf7099d --- /dev/null +++ b/Help/variable/WINDOWS_PHONE.rst @@ -0,0 +1,7 @@ +WINDOWS_PHONE +------------- + +.. versionadded:: 3.1 + +True when the :variable:`CMAKE_SYSTEM_NAME` variable is set +to ``WindowsPhone``. diff --git a/Help/variable/WINDOWS_STORE.rst b/Help/variable/WINDOWS_STORE.rst new file mode 100644 index 0000000..13831c2 --- /dev/null +++ b/Help/variable/WINDOWS_STORE.rst @@ -0,0 +1,7 @@ +WINDOWS_STORE +------------- + +.. versionadded:: 3.1 + +True when the :variable:`CMAKE_SYSTEM_NAME` variable is set +to ``WindowsStore``. diff --git a/Help/variable/XCODE.rst b/Help/variable/XCODE.rst new file mode 100644 index 0000000..167ca86 --- /dev/null +++ b/Help/variable/XCODE.rst @@ -0,0 +1,6 @@ +XCODE +----- + +.. versionadded:: 3.7 + +``True`` when using :generator:`Xcode` generator. diff --git a/Help/variable/XCODE_VERSION.rst b/Help/variable/XCODE_VERSION.rst new file mode 100644 index 0000000..9caf19a --- /dev/null +++ b/Help/variable/XCODE_VERSION.rst @@ -0,0 +1,7 @@ +XCODE_VERSION +------------- + +Version of Xcode (:generator:`Xcode` generator only). + +Under the :generator:`Xcode` generator, this is the version of Xcode +as specified in ``Xcode.app/Contents/version.plist`` (such as ``3.1.2``). |