From 9e40bd860f77d4701824f14e40b4b70332527cc9 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Sat, 1 Mar 2025 19:56:16 +0100 Subject: [PATCH] ProcessorCount: Update documentation Changes: - Module documentation is sorted into a function description and a note section is added where cmake_host_system_information() is mentioned as an alternative. - Module usage example is moved to a titled section at the end for better readability. - Instead of mentioning the physical processors count, the logical processors is used as this is what is most likely wanted in most cases and also all the used commands in this module return this number. - Function's code style is synced a bit across the code base. --- Modules/CMakeFindCodeBlocks.cmake | 2 +- Modules/CMakeFindEclipseCDT4.cmake | 2 +- Modules/CMakeFindKate.cmake | 2 +- Modules/ProcessorCount.cmake | 77 ++++++++++++++++-------------- 4 files changed, 45 insertions(+), 38 deletions(-) diff --git a/Modules/CMakeFindCodeBlocks.cmake b/Modules/CMakeFindCodeBlocks.cmake index bf27ec111a..105b5ba07d 100644 --- a/Modules/CMakeFindCodeBlocks.cmake +++ b/Modules/CMakeFindCodeBlocks.cmake @@ -18,7 +18,7 @@ include(${CMAKE_CURRENT_LIST_DIR}/CMakeExtraGeneratorDetermineCompilerMacrosAndI set(_CMAKE_CODEBLOCKS_INITIAL_MAKE_ARGS "") include(ProcessorCount) -processorcount(_CMAKE_CODEBLOCKS_PROCESSOR_COUNT) +ProcessorCount(_CMAKE_CODEBLOCKS_PROCESSOR_COUNT) # Only set -j if we are under UNIX and if the make-tool used actually has "make" in the name # (we may also get here in the future e.g. for ninja) diff --git a/Modules/CMakeFindEclipseCDT4.cmake b/Modules/CMakeFindEclipseCDT4.cmake index e563a12b09..16a60e2bef 100644 --- a/Modules/CMakeFindEclipseCDT4.cmake +++ b/Modules/CMakeFindEclipseCDT4.cmake @@ -68,7 +68,7 @@ _find_eclipse_version() set(_CMAKE_ECLIPSE_INITIAL_MAKE_ARGS "") include(ProcessorCount) -processorcount(_CMAKE_ECLIPSE_PROCESSOR_COUNT) +ProcessorCount(_CMAKE_ECLIPSE_PROCESSOR_COUNT) # Only set -j if we are under UNIX and if the make-tool used actually has "make" in the name # (we may also get here in the future e.g. for ninja) diff --git a/Modules/CMakeFindKate.cmake b/Modules/CMakeFindKate.cmake index 521bc5caf8..043418950b 100644 --- a/Modules/CMakeFindKate.cmake +++ b/Modules/CMakeFindKate.cmake @@ -9,7 +9,7 @@ # Try to find out how many CPUs we have and set the -j argument for make accordingly include(ProcessorCount) -processorcount(_CMAKE_KATE_PROCESSOR_COUNT) +ProcessorCount(_CMAKE_KATE_PROCESSOR_COUNT) # Only set -j if we are under UNIX and if the make-tool used actually has "make" in the name # (we may also get here in the future e.g. for ninja) diff --git a/Modules/ProcessorCount.cmake b/Modules/ProcessorCount.cmake index 1b4f24a4f7..4c10c37a9e 100644 --- a/Modules/ProcessorCount.cmake +++ b/Modules/ProcessorCount.cmake @@ -5,49 +5,56 @@ ProcessorCount -------------- -ProcessorCount(var) +This module provides the following function to determine the number of +processors/cores: -Determine the number of processors/cores and save value in ${var} +.. command:: ProcessorCount -Sets the variable named ${var} to the number of physical cores -available on the machine if the information can be determined. -Otherwise it is set to 0. Currently this functionality is implemented -for AIX, cygwin, FreeBSD, HPUX, Linux, macOS, QNX, Sun and -Windows. + .. code-block:: cmake -.. versionchanged:: 3.15 - On Linux, returns the container CPU count instead of the host CPU count. + ProcessorCount() -This function is guaranteed to return a positive integer (>=1) if it -succeeds. It returns 0 if there's a problem determining the processor -count. + Sets a local variable named ```` to the number of logical CPU cores + available on the machine, if the information can be determined. If + successful, the variable is guaranteed to be set to a positive integer (>=1). + If the processor count cannot be determined, it is set to 0. -More generally accurate physical CPU count can be obtained via -:command:`cmake_host_system_information`: + Currently, this functionality is implemented for AIX, Cygwin, FreeBSD, Haiku, + HPUX, Linux, macOS, QNX, Sun and Windows. + + This function provides an approximation of the number of compute cores + available on the current machine, making it useful for parallel building and + testing. It is meant to help utilize as much of the machine as seems + reasonable, though users should consider other workloads running on the + machine before using its full capacity for parallel tasks. + + .. versionchanged:: 3.15 + On Linux, returns the container CPU count instead of the host CPU count. + +.. note:: + + This module relies on system-dependent commands to determine the number of + processors, which may not always provide accurate information in certain + environments. A more generally accurate logical CPU count can be also + obtained with the :command:`cmake_host_system_information`: + + .. code-block:: cmake + + cmake_host_system_information(RESULT n QUERY NUMBER_OF_LOGICAL_CORES) + +Examples +^^^^^^^^ + +Using ``ProcessorCount`` module in a :option:`ctest -S` dashboard script: .. code-block:: cmake - cmake_host_system_information(RESULT N - QUERY NUMBER_OF_PHYSICAL_CORES) - -Example use, in a ctest -S dashboard script: - -.. code-block:: cmake - - include(ProcessorCount) - ProcessorCount(N) - if(NOT N EQUAL 0) - set(CTEST_BUILD_FLAGS -j${N}) - set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N}) - endif() - -This function is intended to offer an approximation of the value of -the number of compute cores available on the current machine, such -that you may use that value for parallel building and parallel -testing. It is meant to help utilize as much of the machine as seems -reasonable. Of course, knowledge of what else might be running on the -machine simultaneously should be used when deciding whether to request -a machine's full capacity all for yourself. + include(ProcessorCount) + ProcessorCount(n) + if(NOT n EQUAL 0) + set(CTEST_BUILD_FLAGS -j${n}) + set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${n}) + endif() #]=======================================================================] # A more reliable way might be to compile a small C program that uses the CPUID