k2c 1.5.1__py3-none-any.whl

k2c-1.5.1.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: k2c
+Version: 1.5.1
+Summary: Keil .uvprojx to compile_commands.json Converter
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: json5>=0.12.0
+
+# Keil to Compile Commands Converter
+
+这是一个 Python/uv 工具，用于解析 Keil MDK 项目文件 (.uvprojx、.uvproj) 并生成 `compile_commands.json` 文件。这个文件可以被 Clangd 等语言服务器使用，以提供更准确的代码补全、导航和诊断功能。
+
+## 功能
+
+*   解析 Keil `.uvprojx` XML 文件。
+*   提取项目中包含的 C/C++ 源文件 (`.c`) 和汇编文件 (`.s`)。
+*   提取在 Keil 项目设置中定义的宏 (`-D` 标志)。
+*   提取在 Keil 项目设置中指定的包含路径 (`-I` 标志)。
+*   支持 Target 选择和 Target 列表查看。
+*   合并 Target、Group、File 级别的宏、包含路径和部分编译选项。
+*   支持 C、C++、汇编源文件 (`.c`, `.cc`, `.cpp`, `.cxx`, `.s`, `.S`)。
+*   从 Keil CPU/FPU 配置推导常用 clang 参数，如 `-mcpu`、`-mthumb`、`-mfpu`。
+*   自动处理包含路径的相对路径转换
+*   统一路径分隔符为 `/` 格式
+*   支持从 VSCode Clangd 设置中自动获取编译器路径
+*   支持检查缺失的源文件和包含目录。
+*   根据提取的信息生成 `compile_commands.json` 文件。
+
+## 依赖
+
+*   uv
+*   Python 3.13+
+*   标准库: `xml.etree.ElementTree`, `json`, `os`, `sys` (无需额外安装)
+*   `json5` (由 uv 按 `pyproject.toml` 自动安装，用于读取带注释的VSCode设置文件)
+
+## 使用方法
+
+### 安装
+
+通过 pip 安装 Python 包:
+
+```bash
+pip install k2c
+```
+
+安装后可以直接运行:
+
+```bash
+k2c --version
+```
+
+也可以从 GitHub Release 下载 `k2c.exe` 后直接运行。
+
+### 本地开发运行
+
+首次使用先同步运行环境：
+
+```bash
+uv sync
+```
+
+日常使用建议加 `--no-sync`，避免每次运行前重复检查和同步环境：
+
+```bash
+uv run --no-sync k2c <path_to_your_keil_project.uvprojx> [options]
+```
+
+**参数说明:**
+- `--version`: 输出当前版本号
+- `-d`: 可选参数，创建clangd缓存目录
+  - 不带参数值: 默认创建`.cache`目录
+  - 带参数值: 创建指定名称的目录
+- `-o, --output`: 指定输出文件路径，默认 `compile_commands.json`
+- `--target`: 指定要解析的 Keil Target 名称
+- `--list-targets`: 列出工程中的 Target 名称后退出
+- `--compiler`: 显式指定编译器路径，优先级高于 VSCode 设置
+- `--dry-run`: 只解析并打印摘要，不写入文件
+- `--verbose`: 打印解析摘要
+- `--check-missing-files`: 检查缺失的源文件和 include 路径
+
+**示例:**
+
+基本用法:
+```bash
+uv run --no-sync k2c C:/Path/To/Your/Project/YourProject.uvprojx
+```
+
+查看 Target:
+```bash
+uv run --no-sync k2c ../../MyKeilProject/MyProject.uvprojx --list-targets
+```
+
+查看版本:
+```bash
+uv run --no-sync k2c --version
+```
+
+指定 Target 和编译器:
+```bash
+uv run --no-sync k2c ../../MyKeilProject/MyProject.uvprojx --target Debug --compiler C:/Keil_v5/ARM/ARMCLANG/bin/armclang.exe
+```
+
+指定输出路径:
+```bash
+uv run --no-sync k2c ../../MyKeilProject/MyProject.uvprojx -o build/compile_commands.json
+```
+
+检查解析结果:
+```bash
+uv run --no-sync k2c ../../MyKeilProject/MyProject.uvprojx --dry-run --verbose --check-missing-files
+```
+
+创建默认缓存目录:
+```bash
+uv run --no-sync k2c ../../MyKeilProject/MyProject.uvprojx -d
+```
+
+创建自定义缓存目录:
+```bash
+uv run --no-sync k2c ../../MyKeilProject/MyProject.uvprojx -d my_cache
+```
+
+当然你也可以使用打包好的exe可执行文件 [Release](https://github.com/liuyu80/keil2CompileCommands/releases/latest)
+
+```bash
+k2c ../../MyKeilProject/MyProject.uvprojx -d
+```
+
+工具默认将在当前工作目录下生成一个名为 `compile_commands.json` 的文件。
+
+## 编译器路径设置
+
+为了获取正确的编译器路径，脚本会按以下顺序查找：
+1. 当前项目目录下的 `.vscode/settings.json`
+2. 全局 VSCode 用户设置 (`AppData/Code/User/settings.json`)
+
+如果找不到编译器路径，脚本会提醒您添加以下配置到 VSCode 设置中：
+```json
+"clangd.arguments": ["--query-driver=<absolute_path_to_compiler>"]
+```
+
+## `compile_commands.json`
+
+生成的 `compile_commands.json` 文件包含一个 JSON 数组，其中每个对象代表项目中的一个源文件及其编译参数。结构如下：
+
+```json
+[
+  {
+    "directory": "/path/to/source/file/directory",
+    "arguments": [
+      "<absolute_path_to_compiler>",
+      "-Iinclude/path1",
+      "-Iinclude/path2",
+      "-DMACRO1",
+      "-DMACRO2"
+    ],
+    "file": "/path/to/source/file/filename.c"
+  },
+  ...
+]
+```
+
+这个文件可以被许多开发工具（如 VS Code 配合 Clangd 插件）使用，以增强代码编辑体验。
+
+Clangd LSP 安装包: https://github.com/clangd/clangd/releases/latest
+
+VS Code 的 Clangd 插件: https://github.com/clangd/vscode-clangd/releases/latest
+

k2c-1.5.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+keil2compilecommands/__init__.py,sha256=BfQ2MCyweriP8ve0GQfXLgIdl7HJ4f_tsi0oNaKA4lc,55
+keil2compilecommands/cli.py,sha256=0TfGUncyEsK8s1_MtgeuE6wms5mpb8x1Hf82IBsWSak,3450
+keil2compilecommands/k2c_utils.py,sha256=i8Hl4gBDEXotyK73NhDlXe0r5ILn32K3eJhm991KHQM,17206
+keil2compilecommands/version.py,sha256=TFIXKBGtjU6i9bBeiQzQdTCmzBpGkKPXrezObldiZrQ,531
+k2c-1.5.1.dist-info/METADATA,sha256=g9SufFtCeBRSYqDtxFQ28ntcDC5Abz1Y7QSIfRYpLyc,4958
+k2c-1.5.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+k2c-1.5.1.dist-info/entry_points.txt,sha256=mx9n8xKKecNasNyMB19o61LJ8h2MJ5J160TH_7xszGk,54
+k2c-1.5.1.dist-info/top_level.txt,sha256=UZtSAEj8jqduhZ8cuyNJqom-EFbleLKa1OpbrOsmnTg,21
+k2c-1.5.1.dist-info/RECORD,,

k2c-1.5.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

k2c-1.5.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+k2c = keil2compilecommands.cli:main

k2c-1.5.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+keil2compilecommands

keil2compilecommands/__init__.py

@@ -0,0 +1 @@
+"""Keil project to compile_commands.json converter."""

keil2compilecommands/cli.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .k2c_utils import (
+    build_compile_commands,
+    check_missing_paths,
+    create_clangd_directory,
+    get_clangd_query_driver,
+    list_target_names,
+    write_compile_commands,
+)
+from .version import get_version
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Parse Keil project file and generate compile_commands.json"
+    )
+    parser.add_argument("--version", action="version", version=f"k2c {get_version()}")
+    parser.add_argument("project_file", type=str, help="Path to Keil project file (.uvprojx .uvproj)")
+    parser.add_argument("-d", nargs="?", const=".cache", metavar="CACHE_DIR",
+                        help="Create clangd cache directory (default: .cache)")
+    parser.add_argument("-o", "--output", default="compile_commands.json",
+                        help="Output compile_commands.json path")
+    parser.add_argument("--target", help="Keil target name to parse")
+    parser.add_argument("--list-targets", action="store_true",
+                        help="List target names and exit")
+    parser.add_argument("--compiler", help="Compiler path used as argv[0] in compile commands")
+    parser.add_argument("--dry-run", action="store_true",
+                        help="Parse and print a summary without writing output")
+    parser.add_argument("--verbose", action="store_true",
+                        help="Print parsing summary")
+    parser.add_argument("--check-missing-files", action="store_true",
+                        help="Warn about missing source and include paths")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    project_path = Path(args.project_file)
+    if not project_path.exists():
+        parser.error(f"The specified Keil project file does not exist: {args.project_file}")
+
+    try:
+        if args.list_targets:
+            for target_name in list_target_names(project_path):
+                print(target_name)
+            return 0
+
+        compiler = args.compiler or get_clangd_query_driver(project_path.resolve().parent)
+        compile_info = build_compile_commands(
+            project_path,
+            compiler=compiler,
+            target_name=args.target,
+            output_dir=Path(args.output).resolve().parent,
+            verbose=args.verbose,
+        )
+
+        if args.check_missing_files:
+            report = check_missing_paths(project_path, target_name=args.target)
+            if report.missing_sources:
+                print(f"Missing source files: {len(report.missing_sources)}")
+                for missing in report.missing_sources:
+                    print(f"  {missing}")
+            if report.missing_includes:
+                print(f"Missing include paths: {len(report.missing_includes)}")
+                for missing in report.missing_includes:
+                    print(f"  {missing}")
+
+        if args.dry_run:
+            print(f"Would write {len(compile_info)} compile command entries to {args.output}")
+        else:
+            write_compile_commands(compile_info, args.output)
+
+        if args.d is not None:
+            create_clangd_directory(args.d)
+    except Exception as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

keil2compilecommands/k2c_utils.py

@@ -0,0 +1,512 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable, Optional
+import xml.etree.ElementTree as ET
+
+
+SOURCE_SUFFIXES = {".c", ".cc", ".cpp", ".cxx", ".s"}
+
+
+@dataclass(frozen=True)
+class KeilControls:
+    defines: list[str] = field(default_factory=list)
+    include_paths: list[str] = field(default_factory=list)
+    misc_controls: list[str] = field(default_factory=list)
+    optimization: Optional[str] = None
+    language: Optional[str] = None
+    language_cpp: Optional[str] = None
+    warning_level: Optional[str] = None
+    warnings_as_errors: Optional[str] = None
+    rtti: Optional[str] = None
+    short_enums: Optional[str] = None
+    short_wchar: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class KeilSource:
+    path: str
+    controls: KeilControls = field(default_factory=KeilControls)
+
+
+@dataclass(frozen=True)
+class KeilTarget:
+    name: str
+    element: ET.Element
+    controls: KeilControls
+    cpu_text: str
+    sources: list[KeilSource]
+
+
+@dataclass(frozen=True)
+class MissingPathReport:
+    missing_sources: list[str]
+    missing_includes: list[str]
+
+
+def normalize_path(path: Path | str) -> str:
+    return str(path).replace("\\", "/")
+
+
+def relative_or_absolute(path: Path, start: Path) -> str:
+    try:
+        return normalize_path(os.path.relpath(path, start))
+    except ValueError:
+        return normalize_path(path)
+
+
+def split_list(value: Optional[str], separator: str) -> list[str]:
+    if not value:
+        return []
+    return [item.strip() for item in value.split(separator) if item.strip()]
+
+
+def split_shell_words(value: Optional[str]) -> list[str]:
+    if not value:
+        return []
+    import shlex
+
+    return shlex.split(value, posix=False)
+
+
+def unique_preserving_order(values: Iterable[str]) -> list[str]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for value in values:
+        if value not in seen:
+            seen.add(value)
+            result.append(value)
+    return result
+
+
+def parse_controls(container: Optional[ET.Element]) -> KeilControls:
+    if container is None:
+        return KeilControls()
+
+    various = container.find(".//VariousControls")
+    define_text = text_or_empty(various.find("Define") if various is not None else None)
+    include_text = text_or_empty(various.find("IncludePath") if various is not None else None)
+    misc_text = text_or_empty(various.find("MiscControls") if various is not None else None)
+    optimization = text_or_empty(container.find("Optim")) or None
+
+    return KeilControls(
+        defines=split_list(define_text, ","),
+        include_paths=split_list(include_text, ";"),
+        misc_controls=split_shell_words(misc_text),
+        optimization=optimization,
+        language=_language_standard(container),
+        language_cpp=_cpp_language_standard(container),
+        warning_level=_field_text(container, "wLevel"),
+        warnings_as_errors=_field_text(container, "v6WtE"),
+        rtti=_field_text(container, "v6Rtti"),
+        short_enums=_field_text(container, "vShortEn"),
+        short_wchar=_field_text(container, "vShortWch"),
+    )
+
+
+def merge_controls(*controls: KeilControls) -> KeilControls:
+    return KeilControls(
+        defines=unique_preserving_order(
+            item for control in controls for item in control.defines
+        ),
+        include_paths=unique_preserving_order(
+            item for control in controls for item in control.include_paths
+        ),
+        misc_controls=[
+            item for control in controls for item in control.misc_controls
+        ],
+        optimization=next(
+            (control.optimization for control in reversed(controls) if control.optimization),
+            None,
+        ),
+        language=next(
+            (control.language for control in reversed(controls) if control.language),
+            None,
+        ),
+        language_cpp=next(
+            (control.language_cpp for control in reversed(controls) if control.language_cpp),
+            None,
+        ),
+        warning_level=next(
+            (control.warning_level for control in reversed(controls) if control.warning_level),
+            None,
+        ),
+        warnings_as_errors=next(
+            (control.warnings_as_errors for control in reversed(controls) if control.warnings_as_errors),
+            None,
+        ),
+        rtti=next(
+            (control.rtti for control in reversed(controls) if control.rtti),
+            None,
+        ),
+        short_enums=next(
+            (control.short_enums for control in reversed(controls) if control.short_enums),
+            None,
+        ),
+        short_wchar=next(
+            (control.short_wchar for control in reversed(controls) if control.short_wchar),
+            None,
+        ),
+    )
+
+
+def text_or_empty(element: Optional[ET.Element]) -> str:
+    if element is None or element.text is None:
+        return ""
+    return element.text.strip()
+
+
+def _field_text(container: ET.Element, name: str) -> Optional[str]:
+    value = text_or_empty(container.find(name))
+    if not value or value == "2":
+        return None
+    return value
+
+
+def _language_standard(container: ET.Element) -> Optional[str]:
+    v6_lang = _field_text(container, "v6Lang")
+    if v6_lang:
+        mapping = {
+            "0": "c90",
+            "1": "c99",
+            "2": "c11",
+            "3": "gnu90",
+            "4": "gnu99",
+            "5": "gnu11",
+        }
+        return mapping.get(v6_lang)
+
+    if _field_text(container, "uGnu") == "1":
+        return "gnu99" if _field_text(container, "uC99") == "1" else "gnu90"
+    if _field_text(container, "uC99") == "1":
+        return "c99"
+    return None
+
+
+def _cpp_language_standard(container: ET.Element) -> Optional[str]:
+    v6_lang_cpp = _field_text(container, "v6LangP")
+    if not v6_lang_cpp:
+        return None
+    mapping = {
+        "0": "c++03",
+        "1": "gnu++03",
+        "2": "c++11",
+        "3": "gnu++11",
+        "4": "c++14",
+        "5": "gnu++14",
+        "6": "c++17",
+        "7": "gnu++17",
+    }
+    return mapping.get(v6_lang_cpp)
+
+
+def find_targets(project_file: str | Path) -> list[KeilTarget]:
+    tree = ET.parse(project_file)
+    root = tree.getroot()
+    targets = root.findall(".//Target")
+    return [_parse_target(target) for target in targets]
+
+
+def list_target_names(project_file: str | Path) -> list[str]:
+    return [target.name for target in find_targets(project_file)]
+
+
+def _parse_target(target: ET.Element) -> KeilTarget:
+    name = text_or_empty(target.find("TargetName")) or "<unnamed>"
+    target_option = target.find(".//TargetOption")
+    controls = parse_controls(target_option.find(".//Cads") if target_option is not None else None)
+    cpu_text = text_or_empty(target_option.find(".//Cpu") if target_option is not None else None)
+    sources = _parse_sources(target, controls)
+    return KeilTarget(name=name, element=target, controls=controls, cpu_text=cpu_text, sources=sources)
+
+
+def _parse_sources(target: ET.Element, target_controls: KeilControls) -> list[KeilSource]:
+    sources: list[KeilSource] = []
+    for group in target.findall(".//Group"):
+        group_controls = parse_controls(group.find(".//GroupOption/Cads"))
+        for file_element in group.findall("./Files/File"):
+            file_type = _parse_int(text_or_empty(file_element.find("FileType")))
+            file_path = text_or_empty(file_element.find("FilePath"))
+            if file_type not in {1, 2} or not file_path:
+                continue
+            if not _is_supported_source(file_path):
+                continue
+
+            file_controls = parse_controls(file_element.find(".//FileOption/Cads"))
+            controls = merge_controls(target_controls, group_controls, file_controls)
+            sources.append(KeilSource(path=file_path, controls=controls))
+    return sources
+
+
+def _parse_int(value: str) -> Optional[int]:
+    if not value:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def _is_supported_source(path: str) -> bool:
+    suffix = Path(path).suffix
+    return suffix.lower() in SOURCE_SUFFIXES or suffix == ".S"
+
+
+def select_target(targets: list[KeilTarget], target_name: Optional[str]) -> KeilTarget:
+    if not targets:
+        raise ValueError("Target element not found in Keil project file.")
+    if target_name is None:
+        return targets[0]
+
+    matches = [target for target in targets if target.name == target_name]
+    if not matches:
+        available = ", ".join(target.name for target in targets)
+        raise ValueError(f"Target '{target_name}' not found. Available targets: {available}")
+    return matches[0]
+
+
+def keil_cpu_arguments(cpu_text: str) -> list[str]:
+    args: list[str] = []
+    lowered = cpu_text.lower()
+
+    cpu = _extract_between(cpu_text, 'CPUTYPE("', '")')
+    if cpu:
+        cpu_map = {
+            "cortex-m0": "cortex-m0",
+            "cortex-m0+": "cortex-m0plus",
+            "cortex-m3": "cortex-m3",
+            "cortex-m4": "cortex-m4",
+            "cortex-m7": "cortex-m7",
+            "cortex-m23": "cortex-m23",
+            "cortex-m33": "cortex-m33",
+            "cortex-m55": "cortex-m55",
+        }
+        mapped = cpu_map.get(cpu.lower(), cpu.lower())
+        args.extend(["-mcpu=" + mapped, "-mthumb"])
+    elif "cortex-m" in lowered:
+        args.append("-mthumb")
+
+    if "fpu" in lowered or "dfpu" in lowered or "spfu" in lowered:
+        if "cortex-m7" in lowered:
+            args.extend(["-mfpu=fpv5-d16", "-mfloat-abi=hard"])
+        elif "cortex-m4" in lowered:
+            args.extend(["-mfpu=fpv4-sp-d16", "-mfloat-abi=hard"])
+
+    if "elittle" in lowered:
+        args.append("-mlittle-endian")
+    elif "ebig" in lowered:
+        args.append("-mbig-endian")
+
+    return unique_preserving_order(args)
+
+
+def optimization_argument(optimization: Optional[str]) -> list[str]:
+    if optimization is None:
+        return []
+    mapping = {
+        "0": "-O0",
+        "1": "-O1",
+        "2": "-O2",
+        "3": "-O3",
+        "4": "-Os",
+    }
+    return [mapping.get(optimization, f"-O{optimization}")]
+
+
+def control_arguments(controls: KeilControls, source_path: str) -> list[str]:
+    args: list[str] = []
+    standard = controls.language_cpp if _is_cpp_source(source_path) else controls.language
+    if standard:
+        args.append(f"-std={standard}")
+
+    args.extend(optimization_argument(controls.optimization))
+    args.extend(warning_arguments(controls.warning_level))
+
+    if controls.warnings_as_errors == "1":
+        args.append("-Werror")
+    if controls.short_enums == "1":
+        args.append("-fshort-enums")
+    if controls.short_wchar == "1":
+        args.append("-fshort-wchar")
+    if controls.rtti == "0" and _is_cpp_source(source_path):
+        args.append("-fno-rtti")
+    elif controls.rtti == "1" and _is_cpp_source(source_path):
+        args.append("-frtti")
+
+    args.extend(controls.misc_controls)
+    return args
+
+
+def warning_arguments(warning_level: Optional[str]) -> list[str]:
+    if warning_level is None:
+        return []
+    mapping = {
+        "0": ["-w"],
+        "1": ["-Wall"],
+        "2": ["-Wall"],
+        "3": ["-Wall", "-Wextra"],
+        "4": ["-Wall", "-Wextra"],
+    }
+    return mapping.get(warning_level, [])
+
+
+def _is_cpp_source(path: str) -> bool:
+    return Path(path).suffix.lower() in {".cc", ".cpp", ".cxx"}
+
+
+def _extract_between(value: str, prefix: str, suffix: str) -> Optional[str]:
+    start = value.find(prefix)
+    if start < 0:
+        return None
+    start += len(prefix)
+    end = value.find(suffix, start)
+    if end < 0:
+        return None
+    return value[start:end]
+
+
+def build_compile_commands(
+    project_file: str | Path,
+    *,
+    compiler: str,
+    target_name: Optional[str] = None,
+    output_dir: str | Path | None = None,
+    verbose: bool = False,
+) -> list[dict[str, Any]]:
+    project_path = Path(os.path.abspath(project_file))
+    project_dir = project_path.parent
+    output_path = Path(os.path.abspath(Path.cwd() if output_dir is None else output_dir))
+
+    targets = find_targets(project_path)
+    target = select_target(targets, target_name)
+    if verbose and target_name is None and len(targets) > 1:
+        print(f"Using first target '{target.name}'. Use --target to select another target.")
+
+    base_args = keil_cpu_arguments(target.cpu_text)
+    compile_commands: list[dict[str, Any]] = []
+    include_cache: dict[str, str] = {}
+
+    def include_argument(include: str) -> str:
+        cached = include_cache.get(include)
+        if cached is not None:
+            return cached
+        abs_include = Path(os.path.abspath(project_dir / include))
+        cached = "-I" + relative_or_absolute(abs_include, output_path)
+        include_cache[include] = cached
+        return cached
+
+    for source in target.sources:
+        abs_source = Path(os.path.abspath(project_dir / source.path))
+        rel_source = relative_or_absolute(abs_source, output_path)
+        includes = [include_argument(include) for include in source.controls.include_paths]
+        macros = [f"-D{define}" for define in source.controls.defines]
+        arguments = (
+            [compiler]
+            + base_args
+            + includes
+            + macros
+            + control_arguments(source.controls, source.path)
+            + [rel_source]
+        )
+        compile_commands.append(
+            {
+                "arguments": arguments,
+                "directory": str(output_path),
+                "file": rel_source,
+            }
+        )
+
+    if verbose:
+        print(
+            f"Parsed target '{target.name}': "
+            f"{len(target.controls.include_paths)} target includes, "
+            f"{len(target.controls.defines)} target macros, "
+            f"{len(target.sources)} source files."
+        )
+    return compile_commands
+
+
+def write_compile_commands(
+    compile_commands: list[dict[str, Any]],
+    output_file: str | Path = "compile_commands.json",
+) -> None:
+    output_path = Path(output_file)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(output_path, "w", encoding="utf-8") as file:
+        json.dump(compile_commands, file, indent=4, ensure_ascii=False)
+    print(f"Successfully wrote compile commands to {output_path}")
+
+
+def create_clangd_directory(cache_dir: Optional[str] = None) -> None:
+    cache_path = Path(".cache" if cache_dir is None else cache_dir)
+    cache_path.mkdir(parents=True, exist_ok=True)
+    (cache_path / ".gitignore").write_text("*", encoding="utf-8")
+    print(f"Successfully created {cache_path} directory and .gitignore file")
+
+
+def check_missing_paths(
+    project_file: str | Path,
+    *,
+    target_name: Optional[str] = None,
+) -> MissingPathReport:
+    project_path = Path(os.path.abspath(project_file))
+    project_dir = project_path.parent
+    target = select_target(find_targets(project_path), target_name)
+    missing_sources: list[str] = []
+    missing_includes: list[str] = []
+
+    for source in target.sources:
+        source_path = Path(os.path.abspath(project_dir / source.path))
+        if not source_path.exists():
+            missing_sources.append(normalize_path(source.path))
+        for include in source.controls.include_paths:
+            include_path = Path(os.path.abspath(project_dir / include))
+            normalized = normalize_path(include)
+            if not include_path.exists() and normalized not in missing_includes:
+                missing_includes.append(normalized)
+
+    return MissingPathReport(missing_sources=missing_sources, missing_includes=missing_includes)
+
+
+def get_clangd_query_driver(project_dir: str | Path | None = None) -> str:
+    def read_json_file(file_path: Path) -> dict[str, Any]:
+        try:
+            import json5
+        except ModuleNotFoundError:
+            with open(file_path, "r", encoding="utf-8") as file:
+                return json.load(file)
+        with open(file_path, "r", encoding="utf-8") as file:
+            return json5.load(file)
+
+    def find_compiler_in_settings(settings_path: Path) -> Optional[str]:
+        if not settings_path.exists():
+            return None
+        data = read_json_file(settings_path)
+        arguments = data.get("clangd.arguments", [])
+        if not isinstance(arguments, list):
+            return None
+        for arg in arguments:
+            if isinstance(arg, str) and arg.startswith("--query-driver="):
+                compilers = split_list(arg.split("=", 1)[1], ",")
+                if compilers:
+                    print(f"Found compiler: {compilers}")
+                    return compilers[0]
+        return None
+
+    search_dir = Path.cwd() if project_dir is None else Path(project_dir)
+    compiler = find_compiler_in_settings(search_dir / ".vscode" / "settings.json")
+    if compiler:
+        return compiler
+
+    app_data = os.getenv("AppData")
+    if app_data:
+        compiler = find_compiler_in_settings(Path(app_data) / "Code" / "User" / "settings.json")
+        if compiler:
+            return compiler
+
+    print("Please add the following to your VSCode settings.json (use absolute path):")
+    print('"clangd.arguments": ["--query-driver=<absolute_path_to_compiler>"]')
+    return "<compilerPath>"

keil2compilecommands/version.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import os
+from importlib import metadata
+
+
+PACKAGE_NAME = "k2c"
+DEFAULT_VERSION = "0.1.0"
+
+
+def normalize_version(version: str) -> str:
+    version = version.strip()
+    return version[1:] if version.startswith("v") else version
+
+
+def get_version() -> str:
+    env_version = os.getenv("K2C_VERSION")
+    if env_version:
+        return normalize_version(env_version)
+
+    try:
+        return metadata.version(PACKAGE_NAME)
+    except metadata.PackageNotFoundError:
+        return DEFAULT_VERSION