CMake (Python distribution)

Warnings

• breaking Python 3.7 and older `manylinux` wheels were dropped in CMake Python distribution version 4.1.0. If you require Python 3.7 or older `manylinux` environments (e.g., `manylinux2010`, `manylinux1`), you must use an older version of the `cmake` package (e.g., 4.0.3 for Python 3.7/manylinux2010, 3.22.x for manylinux1).
  Fix: Upgrade your Python version to 3.8+ or pin the `cmake` package version to `~=4.0.3` for Python 3.7, or `~=3.22` for older manylinux.
• gotcha The `cmake` Python package primarily serves to provide a convenient, platform-specific distribution of the CMake *executable*. It does not offer a high-level Python API for interacting with CMake's build system features directly within Python. For building Python extension modules using CMake, consider higher-level build backends like `scikit-build` or `scikit-build-core` which utilize this `cmake` package.
  Fix: Use `subprocess` to execute CMake commands via `cmake.cmake_path()`. If building Python C/C++/Fortran extensions with CMake, use `scikit-build` or `scikit-build-core` as your build backend.
• deprecated Older CMake modules `FindPythonInterp` and `FindPythonLibs` are deprecated and are no-ops since CMake 3.27. Using them in `CMakeLists.txt` will not correctly find Python installations with modern CMake versions.
  Fix: Migrate your `CMakeLists.txt` files to use the modern `find_package(Python3 COMPONENTS Interpreter Development)` command.
• breaking CMake 3.28 (and subsequent versions distributed by this package) changed the `PATH` behavior for Windows, where `find_{library,path,file}()` no longer searches the system `PATH` by default. This might break existing projects that rely on `PATH` for finding libraries on Windows.
  Fix: Explicitly add necessary directories to `CMAKE_PREFIX_PATH` or `CMAKE_LIBRARY_PATH` in your `CMakeLists.txt` or via command-line options when configuring CMake.
• breaking CMake 3.5 compatibility was removed. Calls to `cmake_minimum_required()` or `cmake_policy()` setting policy versions below 3.5 will now result in an error.
  Fix: Update your `CMakeLists.txt` to specify `cmake_minimum_required(VERSION X.Y)` with `X.Y` being at least 3.5, or preferably a more recent version (e.g., 3.15+ for improved `FindPython` modules).

Install

• pip install cmake Install latest version

Imports

• cmake_path

  import cmake
  cmake_executable = cmake.cmake_path()

  The `cmake` Python package provides the path to the bundled CMake executable. Direct programmatic execution of CMake commands should be done via `subprocess` using this path, not via a high-level Python API within the `cmake` package itself. For integrating CMake with Python package builds, consider `scikit-build` or `scikit-build-core`.
• cmake_version

  import cmake
  version_str = cmake.cmake_version()

  Returns the version string of the bundled CMake executable.

Quickstart

This quickstart demonstrates how to retrieve the path to the CMake executable provided by the `cmake` package and execute a basic CMake command using Python's `subprocess` module. It also shows how to get the version string directly from the `cmake` package.

import cmake
import subprocess
import sys

try:
    cmake_executable = cmake.cmake_path()
    print(f"Found CMake executable at: {cmake_executable}")

    # Run a simple CMake command, e.g., --version
    result = subprocess.run([cmake_executable, '--version'], capture_output=True, text=True, check=True)
    print("\nCMake --version output:")
    print(result.stdout)

    # Example of getting CMake version programmatically
    print(f"\nCMake version from package: {cmake.cmake_version()}")

except subprocess.CalledProcessError as e:
    print(f"Error running CMake: {e}", file=sys.stderr)
    print(f"Stderr: {e.stderr}", file=sys.stderr)
except Exception as e:
    print(f"An unexpected error occurred: {e}", file=sys.stderr)