CMake Format Tool

0.6.13 · active · verified Thu Apr 16

The `cmake-format` tool is a Python-based command-line utility for automatically formatting CMake listfiles (e.g., `CMakeLists.txt`), improving consistency and readability. It is part of the broader `cmakelang` project, which provides the underlying formatting library. The current version is 0.6.13, and the project is actively maintained with several releases per year addressing features and bug fixes.

Common errors

```
cmake-format: command not found
```
cause The `cmake-format` script is not in your system's PATH, or the package was not installed correctly.

fix Ensure `pip install cmake-format` completed successfully. Verify that the directory where pip installs scripts (e.g., `~/.local/bin` on Linux/macOS or `Scripts` within your virtual environment) is included in your system's PATH.
```
ERROR: Failed to parse configuration file: ... Invalid syntax (or similar Python/TOML parsing errors)
```
cause Your `.cmake-format.py` (Python) or `pyproject.toml` (TOML) configuration file contains syntax errors or incorrect structure.

fix Carefully check the syntax of your configuration file. For `.cmake-format.py`, ensure it's valid Python code. For `pyproject.toml`, verify that the TOML structure under `[tool.cmake-format]` is correct and well-formed.
```
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xXX in position YYY: invalid start byte
```
cause You are attempting to format a CMake file that is not encoded in UTF-8, and `cmake-format` is trying to read it as UTF-8 by default.

fix Save your CMake file with UTF-8 encoding. Alternatively, if the file uses a different encoding (e.g., 'latin-1'), specify it explicitly using the `--encoding <encoding>` command-line option, e.g., `cmake-format --encoding latin-1 CMakeLists.txt`.

Warnings

breaking The `0.6.0` release introduced a major rewrite of the underlying parser and significant changes to all configuration options and their defaults.
Fix: Review and update `.cmake-format.py` or `pyproject.toml` configuration files to the new schema. Refer to the 0.6.0 release notes and updated documentation for details on configuration changes.
gotcha Configuration for `cmake-format` is primarily done via a Python-based `.cmake-format.py` file or a TOML-based `pyproject.toml` (under `[tool.cmake-format]`). It does not support common INI or YAML formats for configuration.
Fix: Ensure your configuration file is named `.cmake-format.py` or `pyproject.toml` (in the project root or parent directories) and adheres to the correct Python or TOML syntax as specified in the documentation.
gotcha The `cmake-format` package provides the CLI tool. For programmatic access to formatting functions within Python, you must import directly from the `cmakelang` library, which is an internal dependency.
Fix: Do not attempt `import cmake_format`. Instead, use `from cmakelang.format import format_string` or other specific modules from `cmakelang`.

Install

pip install cmake-format Install `cmake-format`

Imports

format_string
wrong:
```
from cmake_format import format_string
```
correct:
```
from cmakelang.format import format_string
```
The `cmake-format` package is primarily a CLI tool. For programmatic formatting, import from the underlying `cmakelang` library (which is a dependency) rather than trying to import from `cmake_format` directly.

Quickstart

This quickstart demonstrates how to use the `cmake-format` command-line tool to format a CMakeLists.txt file in-place.

import os

# Create a dummy CMakeLists.txt with unformatted content
cmake_content = """
project(myproject)
  add_executable(myexec  main.cpp)

function(my_func arg1 arg2)
    message("Hello from my_func")
endfunction()
"""
with open("CMakeLists.txt", "w") as f:
    f.write(cmake_content)

print("Original CMakeLists.txt:\n---")
with open("CMakeLists.txt", "r") as f:
    print(f.read())
print("--- End Original\n")

# Format the file in-place using the CLI tool
# For a real application, consider subprocess.run for better control.
os.system("cmake-format -i CMakeLists.txt")

print("Formatted CMakeLists.txt:\n---")
with open("CMakeLists.txt", "r") as f:
    print(f.read())
print("--- End Formatted\n")

# Clean up
os.remove("CMakeLists.txt")

view raw JSON →