CMake Language Tools

Warnings

• breaking The project's Python package name officially changed from `cmake-format` to `cmakelang` around version 0.6.12/0.6.13. The old `cmake-format` PyPI package is now a transitional, empty package that depends on `cmakelang`.
  Fix: Update your installation commands from `pip install cmake-format` to `pip install cmakelang`. Existing `cmake-format` installs will pull in `cmakelang` as a dependency, but direct usage of `cmakelang` is recommended.
• breaking Configuration file datastructures were overhauled in v0.5.0. While legacy configuration files (without sections) are still supported, they may be deprecated in the future, and default formatting for some commands (e.g., `set()`) changed due to parser logic updates.
  Fix: Review your configuration files and consider updating them to the new structure. You can generate a default configuration in your preferred format using `cmake-format --dump-config [yaml|json|python]` as a starting point.
• gotcha Optional features like YAML configuration file support (`pyyaml`) or HTML annotation (`jinja2`) require additional, non-default dependencies.
  Fix: Install with feature flags (e.g., `pip install cmakelang[YAML]` or `pip install cmakelang[html-gen]`) or manually install the required Python packages (`pip install pyyaml` / `pip install jinja2`).
• gotcha `cmake-format` relies on user-provided specifications in its configuration file to correctly understand and format custom CMake commands (macros/functions). Without these, formatting of custom commands may be suboptimal or incorrect.
  Fix: Add detailed specifications for your custom commands to your `cmakelang` configuration file (e.g., in `additional_commands` section) to guide the formatter and linter.
• gotcha When running `cmake-format --dump-config`, the tool will attempt to load any automatically detected configuration files in the current or parent directories. If these files are corrupt or un-parsable, `dump-config` may fail.
  Fix: If `cmake-format --dump-config` fails, try executing it from a clean directory (e.g., `/` or `/tmp`) to ensure no corrupt local configuration files interfere.
• deprecated The GitHub repository is still named `cmake_format`, even though the PyPI package and project name are `cmakelang`. The documentation indicates the repository may be moved in the future.
  Fix: Be aware that external references (e.g., `git clone` URLs) might still use `cmake_format`, and these may change if the repository is officially renamed.

Install

• pip install cmakelang Standard Install
• pip install cmakelang[YAML] Install with YAML config support
• pip install cmakelang[html-gen] Install with HTML annotator support

Imports

• cmake-format (command-line tool)

  Run `cmake-format <file>` from your shell.

  The `cmakelang` library primarily exposes its functionality via command-line tools like `cmake-format` and `cmake-lint`, rather than a public Python API for direct programmatic import into application code. Direct imports from submodules are generally not considered part of the public API.

Quickstart

This quickstart demonstrates how to use `cmake-format` to automatically reformat a CMakeLists.txt file. It creates a sample file, formats it in-place, and then prints the before and after content. This highlights the primary command-line interface of the `cmakelang` tools.

import os

cmake_content_before = '''
cmake_minimum_required(VERSION 3.0)

project(MyProject)

set(SOURCES
    main.cpp
    anotherfile.cpp
    thirdfile.cpp)

add_executable(MyProject ${SOURCES})
'''

cmake_file_path = "CMakeLists.txt"

with open(cmake_file_path, "w") as f:
    f.write(cmake_content_before)

print("--- CMakeLists.txt (Before Formatting) ---")
print(cmake_content_before)

# Run cmake-format in-place
print("\nRunning cmake-format...")
# For quickstart, using os.system for simplicity, in production consider subprocess.run
exit_code = os.system(f"cmake-format -i {cmake_file_path}")

if exit_code == 0:
    with open(cmake_file_path, "r") as f:
        cmake_content_after = f.read()
    print("\n--- CMakeLists.txt (After Formatting) ---")
    print(cmake_content_after)
    print("\nFormatting successful!")
else:
    print(f"\nError: cmake-format exited with code {exit_code}")

# Clean up
os.remove(cmake_file_path)