{"id":7088,"library":"cmake-format","title":"CMake Format Tool","description":"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.","status":"active","version":"0.6.13","language":"en","source_language":"en","source_url":"https://github.com/cheshirekow/cmakelang","tags":["cmake","formatter","cli","code-quality"],"install":[{"cmd":"pip install cmake-format","lang":"bash","label":"Install `cmake-format`"}],"dependencies":[],"imports":[{"note":"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.","wrong":"from cmake_format import format_string","symbol":"format_string","correct":"from cmakelang.format import format_string"}],"quickstart":{"code":"import os\n\n# Create a dummy CMakeLists.txt with unformatted content\ncmake_content = \"\"\"\nproject(myproject)\n  add_executable(myexec  main.cpp)\n\nfunction(my_func arg1 arg2)\n    message(\"Hello from my_func\")\nendfunction()\n\"\"\"\nwith open(\"CMakeLists.txt\", \"w\") as f:\n    f.write(cmake_content)\n\nprint(\"Original CMakeLists.txt:\\n---\")\nwith open(\"CMakeLists.txt\", \"r\") as f:\n    print(f.read())\nprint(\"--- End Original\\n\")\n\n# Format the file in-place using the CLI tool\n# For a real application, consider subprocess.run for better control.\nos.system(\"cmake-format -i CMakeLists.txt\")\n\nprint(\"Formatted CMakeLists.txt:\\n---\")\nwith open(\"CMakeLists.txt\", \"r\") as f:\n    print(f.read())\nprint(\"--- End Formatted\\n\")\n\n# Clean up\nos.remove(\"CMakeLists.txt\")\n","lang":"python","description":"This quickstart demonstrates how to use the `cmake-format` command-line tool to format a CMakeLists.txt file in-place."},"warnings":[{"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.","message":"The `0.6.0` release introduced a major rewrite of the underlying parser and significant changes to all configuration options and their defaults.","severity":"breaking","affected_versions":"<0.6.0 to >=0.6.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Do not attempt `import cmake_format`. Instead, use `from cmakelang.format import format_string` or other specific modules from `cmakelang`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The `cmake-format` script is not in your system's PATH, or the package was not installed correctly.","error":"cmake-format: command not found"},{"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.","cause":"Your `.cmake-format.py` (Python) or `pyproject.toml` (TOML) configuration file contains syntax errors or incorrect structure.","error":"ERROR: Failed to parse configuration file: ... Invalid syntax (or similar Python/TOML parsing errors)"},{"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`.","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.","error":"UnicodeDecodeError: 'utf-8' codec can't decode byte 0xXX in position YYY: invalid start byte"}]}