{"id":9772,"library":"gersemi","title":"Gersemi","description":"Gersemi is a Python-based command-line formatter for CMake code, designed to make your CMakeLists.txt files and `.cmake` modules consistent and readable. It leverages a custom handwritten parser in Rust for robust and efficient formatting. The current version is 0.27.2, with frequent releases addressing bug fixes and introducing new features.","status":"active","version":"0.27.2","language":"en","source_language":"en","source_url":"https://github.com/BlankSpruce/gersemi","tags":["formatter","cmake","code quality","cli","pre-commit"],"install":[{"cmd":"pip install gersemi","lang":"bash","label":"Install Gersemi"}],"dependencies":[],"imports":[],"quickstart":{"code":"import os\nimport subprocess\nimport tempfile\nfrom pathlib import Path\n\n# Create a temporary directory and CMake file for demonstration\nwith tempfile.TemporaryDirectory() as tmpdir_name:\n    tmp_path = Path(tmpdir_name)\n    cmake_file = tmp_path / \"CMakeLists.txt\"\n    original_content = \"\"\"\ncmake_minimum_required(VERSION 3.8)\n\nproject(MyProject CXX)\n\nset(MY_VAR  \"Hello\"\n  CACHE INTERNAL \"A variable\")\n\n  add_executable(my_app main.cpp\n    src/utils.cpp)\n\nmacro(MyMacro arg1 arg2)\n  message(\"Args: ${arg1} ${arg2}\")\nendmacro()\n\nMyMacro(VALUE_ONE VALUE_TWO)\n\n\"\"\"\n    cmake_file.write_text(original_content.strip())\n\n    print(f\"--- Original {cmake_file.name} ---\")\n    print(cmake_file.read_text())\n\n    # Run gersemi format command\n    try:\n        # Change current working directory for subprocess to find the file easily\n        process = subprocess.run(\n            [\"gersemi\", \"format\", \"CMakeLists.txt\"],\n            cwd=tmp_path,\n            capture_output=True,\n            text=True,\n            check=True # Raise an exception for non-zero exit codes\n        )\n        print(f\"\\n--- gersemi command output ---\")\n        print(process.stdout)\n        if process.stderr:\n            print(f\"Stderr: {process.stderr}\")\n\n        print(f\"\\n--- Formatted {cmake_file.name} ---\")\n        print(cmake_file.read_text())\n\n    except FileNotFoundError:\n        print(\"\\nERROR: 'gersemi' command not found.\")\n        print(\"Please install it: pip install gersemi\")\n    except subprocess.CalledProcessError as e:\n        print(f\"\\nERROR: gersemi exited with code {e.returncode}\")\n        print(f\"Stdout: {e.stdout}\")\n        print(f\"Stderr: {e.stderr}\")\n","lang":"python","description":"This quickstart demonstrates how to use `gersemi` to format a CMake file. It creates a temporary `CMakeLists.txt`, formats it using the `gersemi format` command-line tool, and prints the original and formatted content."},"warnings":[{"fix":"If you rely on the previous 'safe' formatting behavior, explicitly add `--safe` to your `gersemi` command (e.g., `gersemi format --safe <file>`) or configure `unsafe: false` in your `.gersemirc.toml`.","message":"The default behavior of `gersemi` for 'unsafe' operations changed from `unsafe: false` to `unsafe: true` in version 0.27.0. This means formatting might be more aggressive by default, potentially introducing more changes to your CMake code.","severity":"breaking","affected_versions":">=0.27.0"},{"fix":"Carefully review formatting changes after upgrading to 0.27.0 or newer, especially for intricate CMake scripts, to ensure the output aligns with expectations. Consider using `git diff` for large codebases.","message":"Gersemi's internal CMake parser was rewritten in Rust starting from version 0.27.0. While this improves performance and robustness, it might introduce subtle differences in how complex or edge-case CMake syntax is interpreted and formatted compared to previous versions.","severity":"gotcha","affected_versions":">=0.27.0"},{"fix":"Update your custom `gersemi` extensions to include the mandatory `signature` keyword in their definition according to the new API specification.","message":"For developers creating custom `gersemi` extensions, the extension API changed in version 0.26.0. Extensions are now required to specify a `signature` keyword (as one of `options`, `one_value_keywords`, or `multi_value_keywords`).","severity":"breaking","affected_versions":">=0.26.0"},{"fix":"Ensure your `.pre-commit-config.yaml` points to `repo: https://github.com/BlankSpruce/pre-commit-gersemi` for the `gersemi` hook.","message":"The official `pre-commit` hook for `gersemi` is now maintained in a separate repository (`https://github.com/BlankSpruce/pre-commit-gersemi`). Referencing the main `gersemi` repository for the hook will not provide the latest or correct installation with wheels.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the `gersemi` package using pip: `pip install gersemi`. Ensure your Python environment's script directory is in your PATH.","cause":"The `gersemi` command-line tool is not installed or not in your system's PATH.","error":"gersemi: command not found"},{"fix":"To revert to the previous, less aggressive 'safe' formatting, run `gersemi format --safe <files...>` or configure `unsafe: false` in your `.gersemirc.toml`.","cause":"From version 0.27.0, the default behavior for 'unsafe' formatting changed from `false` to `true`. This means `gersemi` will, by default, apply more extensive formatting changes that might be considered 'unsafe' by some users.","error":"My CMake files are formatted differently / more aggressively after upgrading Gersemi."},{"fix":"Verify your `.pre-commit-config.yaml` points to the correct repository for `gersemi`: `repo: https://github.com/BlankSpruce/pre-commit-gersemi`. Also, ensure `gersemi` is installed in your pre-commit environment by running `pre-commit install-hooks`.","cause":"The `pre-commit` configuration for `gersemi` is likely pointing to an incorrect or outdated repository, or `gersemi` isn't properly installed in the pre-commit environment.","error":"Pre-commit hook fails to format CMake files or complains about missing commands."}]}