xt-cli 0.2.1__py3-none-any.whl

errors.py

@@ -0,0 +1,29 @@
+"""xt-cli 异常定义。"""
+
+
+class XtCliError(Exception):
+    """xt-cli 基础异常。"""
+
+
+class CliUsageError(XtCliError):
+    """命令参数使用错误。"""
+
+
+class ConfigError(XtCliError):
+    """配置相关错误。"""
+
+
+class ProjectError(XtCliError):
+    """项目相关错误。"""
+
+
+class TargetResolveError(XtCliError):
+    """目标解析错误。"""
+
+
+class XmakeInvokeError(XtCliError):
+    """xmake 调用错误。"""
+
+
+class HookError(XtCliError):
+    """Hook 执行错误。"""

hooks.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import types
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from models import BuildContext
+from output import print_step
+
+_BUILTIN_TASKS = {"build", "clean", "fullclean"}
+
+
+@dataclass(slots=True, frozen=True)
+class HookResult:
+    """Hook 调用结果。"""
+
+    handled: bool
+    returncode: int = 0
+
+
+def _load_hook_module(hook_path: Path) -> types.ModuleType | None:
+    """动态加载 hook.py 模块，不生成字节码缓存。"""
+    if not hook_path.is_file():
+        return None
+    try:
+        spec = importlib.util.spec_from_file_location(
+            "xt_hook", hook_path,
+            submodule_search_locations=[],
+        )
+        if spec is None or spec.origin is None:
+            return None
+        # 用 compile + exec 替代 exec_module，避免生成 __pycache__
+        source = hook_path.read_text(encoding="utf-8")
+        code = compile(source, str(hook_path), "exec")
+        module = types.ModuleType("xt_hook")
+        module.__file__ = str(hook_path)
+        exec(code, module.__dict__)  # noqa: S102
+        return module
+    except Exception:
+        return None
+
+
+def _try_dispatch(
+    hook_path: Path,
+    task: str,
+    context: BuildContext,
+    global_args: argparse.Namespace,
+    shared_args: argparse.Namespace,
+    self_args: argparse.Namespace,
+    unknown_args: list[str],
+    source: str = "",
+) -> HookResult:
+    """尝试从指定 hook 文件分发 task，有特定 handler 时预打印。"""
+    module = _load_hook_module(hook_path)
+    if module is None:
+        return HookResult(handled=False)
+    if not callable(getattr(module, f"handle_{task}", None)) and not callable(getattr(module, "handle", None)):
+        return HookResult(handled=False)
+    if callable(getattr(module, f"handle_{task}", None)):
+        print_step(f"{task}, via {source} hook")
+
+    # 临时注入 dispatch 参数，供 context.run_task() 自动透传
+    prev = getattr(context, "_dispatch_args", None)
+    object.__setattr__(context, "_dispatch_args", (global_args, shared_args, self_args, unknown_args))
+    try:
+        return _call_hook(module, task, context, global_args, shared_args, self_args, unknown_args)
+    finally:
+        object.__setattr__(context, "_dispatch_args", prev)
+
+
+def _call_hook(
+    module: types.ModuleType,
+    task: str,
+    context: BuildContext,
+    global_args: argparse.Namespace,
+    shared_args: argparse.Namespace,
+    self_args: argparse.Namespace,
+    unknown_args: list[str],
+) -> HookResult:
+    """调用 hook 模块中的处理函数。
+
+    返回 None 表示不处理此 task，视为 unhandled。
+    """
+    specific_fn = getattr(module, f"handle_{task}", None)
+    if callable(specific_fn):
+        returncode = specific_fn(context, global_args, shared_args, self_args, unknown_args)
+        if returncode is None:
+            return HookResult(handled=False)
+        return HookResult(handled=True, returncode=returncode)
+
+    generic_fn = getattr(module, "handle", None)
+    if callable(generic_fn):
+        returncode = generic_fn(context, task, unknown_args)
+        if returncode is None:
+            return HookResult(handled=False)
+        return HookResult(handled=True, returncode=returncode)
+
+    return HookResult(handled=False)
+
+
+def run_platform_hook(
+    context: BuildContext,
+    task: str,
+    unknown_args: list[str],
+    global_args: argparse.Namespace,
+    shared_args: argparse.Namespace,
+    self_args: argparse.Namespace,
+) -> HookResult:
+    """运行平台级 hook。"""
+    hook_path = context.target_path.parent / "xt_hook.py"
+    module = _load_hook_module(hook_path)
+    if module is None:
+        return HookResult(handled=False)
+    return _call_hook(module, task, context, global_args, shared_args, self_args, unknown_args)
+
+
+def run_project_hook(
+    context: BuildContext,
+    task: str,
+    unknown_args: list[str],
+    global_args: argparse.Namespace,
+    shared_args: argparse.Namespace,
+    self_args: argparse.Namespace,
+) -> HookResult:
+    """运行工程级 hook。"""
+    hook_path = context.project_dir / "xt_hook.py"
+    module = _load_hook_module(hook_path)
+    if module is None:
+        return HookResult(handled=False)
+    return _call_hook(module, task, context, global_args, shared_args, self_args, unknown_args)
+
+
+def _run_builtin_task(
+    context: BuildContext,
+    task: str,
+    unknown_args: list[str],
+    global_args: argparse.Namespace | None = None,
+    shared_args: argparse.Namespace | None = None,
+    self_args: argparse.Namespace | None = None,
+) -> int:
+    """直接执行内置 task（不经过 hook），用于递归保护时的 fallback。"""
+    if global_args is None:
+        global_args = argparse.Namespace()
+    if shared_args is None:
+        shared_args = argparse.Namespace()
+    if self_args is None:
+        self_args = argparse.Namespace()
+
+    if task == "build":
+        from xmake import build_command, run_xmake
+
+        before_ret = run_lifecycle_hook(context, "before_build", unknown_args, global_args, shared_args, self_args)
+        if before_ret != 0:
+            return before_ret
+
+        print_step("build")
+        result = run_xmake(context, build_command(context))
+        build_ret = result.returncode
+
+        run_lifecycle_hook(context, "after_build", unknown_args, global_args, shared_args, self_args)
+        return build_ret
+    elif task == "clean":
+        from xmake import build_clean_command, run_xmake
+
+        before_ret = run_lifecycle_hook(context, "before_clean", unknown_args, global_args, self_args)
+        if before_ret != 0:
+            return before_ret
+
+        print_step("clean")
+        result = run_xmake(context, build_clean_command(context))
+        clean_ret = result.returncode
+
+        run_lifecycle_hook(context, "after_clean", unknown_args, global_args, self_args)
+        return clean_ret
+    elif task == "fullclean":
+        import shutil
+
+        before_ret = run_lifecycle_hook(context, "before_fullclean", unknown_args, global_args, self_args)
+        if before_ret != 0:
+            return before_ret
+
+        print_step("fullclean")
+        shutil.rmtree(context.project_dir / ".xmake", ignore_errors=True)
+        shutil.rmtree(context.project_dir / ".build", ignore_errors=True)
+
+        run_lifecycle_hook(context, "after_fullclean", unknown_args, global_args, self_args)
+        return 0
+    return 1
+
+
+def dispatch_hook(
+    context: BuildContext,
+    task: str,
+    unknown_args: list[str],
+    *,
+    dispatching_tasks: set[str] | None = None,
+    global_args: argparse.Namespace | None = None,
+    shared_args: argparse.Namespace | None = None,
+    self_args: argparse.Namespace | None = None,
+) -> HookResult:
+    """按优先级分发 hook：工程优先，未被处理再平台。
+
+    dispatching_tasks 用于递归保护：如果 task 在集合中，
+    跳过 hook 直接执行内置行为。
+    """
+    if dispatching_tasks is None:
+        dispatching_tasks = set()
+    if global_args is None:
+        global_args = argparse.Namespace()
+    if shared_args is None:
+        shared_args = argparse.Namespace()
+    if self_args is None:
+        self_args = argparse.Namespace()
+
+    # 递归保护：同 task 直接走内置行为
+    if task in dispatching_tasks and task in _BUILTIN_TASKS:
+        returncode = _run_builtin_task(context, task, unknown_args, global_args, shared_args, self_args)
+        return HookResult(handled=True, returncode=returncode)
+
+    # 工程 hook → 平台 hook
+    project_path = context.project_dir / "xt_hook.py"
+    result = _try_dispatch(project_path, task, context, global_args, shared_args, self_args, unknown_args, source="project")
+    if result.handled:
+        return result
+
+    platform_path = context.target_path.parent / "xt_hook.py"
+    if platform_path != project_path:
+        result = _try_dispatch(platform_path, task, context, global_args, shared_args, self_args, unknown_args, source="platform")
+        if result.handled:
+            return result
+
+    return HookResult(handled=False)
+
+
+def run_lifecycle_hook(
+    context: BuildContext,
+    lifecycle: str,
+    unknown_args: list[str] | None = None,
+    global_args: argparse.Namespace | None = None,
+    shared_args: argparse.Namespace | None = None,
+    self_args: argparse.Namespace | None = None,
+) -> int:
+    """运行生命周期 hook（before_build 等），未定义则静默跳过。"""
+    result = dispatch_hook(
+        context, lifecycle, unknown_args or [],
+        global_args=global_args or argparse.Namespace(),
+        shared_args=shared_args or argparse.Namespace(),
+        self_args=self_args or argparse.Namespace(),
+    )
+    return result.returncode if result.handled else 0
+
+
+_LIFECYCLE_PREFIXES = ("before_", "after_")
+
+
+def discover_hook_tasks(context: BuildContext) -> tuple[list[tuple[str, Callable | None, str, str | None]], dict[str, Callable]]:
+    """扫描工程和平台 hook，返回 (task 列表, scope_parsers 字典)。
+
+    排除生命周期 hook（before_* / after_*）。
+    """
+    from collections.abc import Callable as CallableType
+
+    results: list[tuple[str, CallableType | None, str, str | None]] = []
+    scope_parsers: dict[str, CallableType] = {}
+    seen: set[str] = set()
+
+    project_hook_path = context.project_dir / "xt_hook.py"
+    module = _load_hook_module(project_hook_path)
+    if module is not None:
+        _collect_hook_task_names(module, results, seen, "project")
+        _collect_scope_parsers(module, "project", scope_parsers)
+
+    platform_hook_path = context.target_path.parent / "xt_hook.py"
+    if platform_hook_path != project_hook_path:
+        module = _load_hook_module(platform_hook_path)
+        if module is not None:
+            source = f"platform/{context.platform_name}"
+            _collect_hook_task_names(module, results, seen, source)
+            _collect_scope_parsers(module, source, scope_parsers)
+
+    return results, scope_parsers
+
+
+def _collect_scope_parsers(module: types.ModuleType, source: str, scope_parsers: dict[str, Callable]) -> None:
+    """从 hook 模块中收集 scope 级 parser 函数。"""
+    for fn_name in ("add_shared_args_builtin", "add_shared_args_platform", "add_shared_args_project"):
+        fn = getattr(module, fn_name, None)
+        if callable(fn) and source not in scope_parsers:
+            scope_parsers[source] = fn
+
+
+def _collect_hook_task_names(module: types.ModuleType, results: list[tuple[str, Callable | None, str, str | None]], seen: set[str], source: str) -> None:
+    """从 hook 模块中收集 task 名称、add_parser 及 --help 描述。"""
+    for name in dir(module):
+        if name.startswith("handle_") and callable(getattr(module, name)):
+            task_name = name[len("handle_"):]
+            if not any(task_name.startswith(p) for p in _LIFECYCLE_PREFIXES):
+                if task_name not in seen:
+                    fn = getattr(module, name)
+                    help_desc = _extract_help_from_doc(fn)
+                    add_parser = getattr(module, f"add_args_{task_name}", None)
+                    results.append((task_name, add_parser if callable(add_parser) else None, source, help_desc))
+                    seen.add(task_name)
+
+
+def _extract_help_from_doc(fn) -> str | None:
+    """从函数 docstring 中提取 --help: 前缀行作为简短描述。"""
+    if not fn.__doc__:
+        return None
+    for line in fn.__doc__.strip().splitlines():
+        stripped = line.strip()
+        if stripped.startswith("--help:"):
+            return stripped[len("--help:"):].strip()
+    return None

models.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+try:
+    from enum import StrEnum
+except ImportError:  # Python 3.10
+    from enum import Enum
+
+    class StrEnum(str, Enum):
+        pass
+
+
+class ConfigSource(StrEnum):
+    """配置来源。"""
+
+    LOCAL = "local"
+    GLOBAL = "global"
+    DEFAULT = "default"
+    CLI = "cli"
+    DERIVED = "derived"
+
+
+@dataclass(slots=True, frozen=True)
+class ResolvedValue:
+    """解析后的配置值及其来源。"""
+
+    value: Any
+    source: ConfigSource
+    source_path: str | None = None
+
+
+@dataclass(slots=True, frozen=True)
+class BuildContext:
+    """构建上下文。"""
+
+    project_dir: Path
+    sdk_dir: Path
+    target: str
+    target_path: Path
+    platform_name: str
+    board: str = ""
+    toolchain_path: Path | None = None
+    debug_enabled: bool = False
+    resolved_values: dict[str, ResolvedValue] | None = None
+    _dispatch_args: Any = field(default=None, init=False, repr=False)
+
+    def run_task(
+        self,
+        task: str,
+        args: list[str] | None = None,
+        *,
+        global_args: Any = None,
+        shared_args: Any = None,
+        self_args: Any = None,
+        unknown_args: list[str] | None = None,
+    ) -> int:
+        """执行指定 task，支持组合命令。
+
+        自动从当前 handler 的 dispatch 上下文读取 global_args/shared_args 等，
+        调用方无需显式传入。同 task 递归时跳过 hook，直接执行内置行为。
+        """
+        from hooks import _BUILTIN_TASKS, _run_builtin_task, dispatch_hook
+
+        dispatch = getattr(self, "_dispatch_args", None)
+        if global_args is None and dispatch is not None:
+            global_args = dispatch[0]
+        if shared_args is None and dispatch is not None:
+            shared_args = dispatch[1]
+        if self_args is None and dispatch is not None:
+            self_args = dispatch[2]
+        if unknown_args is None and dispatch is not None:
+            unknown_args = dispatch[3]
+
+        actual_args = args or []
+        actual_unknown = unknown_args if unknown_args is not None else actual_args
+
+        if task in _BUILTIN_TASKS:
+            result = dispatch_hook(
+                self, task, actual_unknown,
+                dispatching_tasks={task},
+                global_args=global_args,
+                shared_args=shared_args,
+                self_args=self_args,
+            )
+            if result.handled:
+                return result.returncode
+            return _run_builtin_task(
+                self, task, actual_unknown,
+                global_args=global_args,
+                shared_args=shared_args,
+                self_args=self_args,
+            )
+
+        result = dispatch_hook(
+            self, task, actual_unknown,
+            global_args=global_args,
+            shared_args=shared_args,
+            self_args=self_args,
+        )
+        if not result.handled:
+            import sys
+            print(f"Unknown task: {task}", file=sys.stderr)
+            return 1
+        return result.returncode

output.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+
+def print_step(step: str) -> None:
+    """统一的步骤输出格式。"""
+    # ******************** Run Step(build, via hook) ... *****************************
+    msg = f" Run Step({step}) ... "
+    left_stars = "*" * 20
+    total_width = 80
+    right_stars_count = total_width - len(left_stars) - len(msg)
+    # 防止消息过长导致右侧负填充
+    if right_stars_count < 0:
+        right_stars_count = 0
+    right_stars = "*" * right_stars_count
+    print("\n" + left_stars + msg + right_stars + "\n")
+

paths.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from errors import TargetResolveError
+
+
+GLOBAL_CONFIG_DIRNAME = ".xt"
+GLOBAL_CONFIG_FILENAME = "xt_conf.jsonc"
+_PLATFORMS_DIRNAME = "platforms"
+
+
+def normalize_path(path: str | Path) -> Path:
+    """规范化路径。"""
+    return Path(path).expanduser()
+
+
+def build_global_config_path(home: str | Path | None = None) -> Path:
+    """构造全局配置文件路径。"""
+    base_home = normalize_path(home) if home is not None else Path.home()
+    return base_home / GLOBAL_CONFIG_DIRNAME / GLOBAL_CONFIG_FILENAME
+
+
+def resolve_target_path(
+    target: str | Path,
+    project_dir: str | Path,
+    sdk_dir: str | Path,
+) -> Path:
+    """解析 target 路径并返回目录。"""
+    normalized_target = normalize_path(target)
+    if normalized_target.is_absolute():
+        candidate = normalized_target
+        if candidate.is_dir():
+            return candidate
+        raise TargetResolveError(f"Unable to resolve target path: {target}")
+
+    normalized_project_dir = normalize_path(project_dir)
+    normalized_sdk_dir = normalize_path(sdk_dir)
+
+    for base_dir in (normalized_project_dir, normalized_sdk_dir):
+        candidate = base_dir / _PLATFORMS_DIRNAME / normalized_target
+        if candidate.is_dir():
+            return candidate
+
+    raise TargetResolveError(f"Unable to resolve target path: {target}")
+
+
+def resolve_platform_name(target: str | Path) -> str:
+    """从 target 名称或路径中提取平台名称。"""
+    normalized_target = normalize_path(target)
+    target_parts = normalized_target.parts
+
+    if _PLATFORMS_DIRNAME in target_parts:
+        platforms_index = target_parts.index(_PLATFORMS_DIRNAME)
+        if platforms_index + 1 < len(target_parts):
+            return target_parts[platforms_index + 1]
+
+    if target_parts:
+        return target_parts[0]
+
+    raise TargetResolveError("Unable to resolve platform name from target")

project.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from paths import normalize_path
+
+_XMAKE_FILENAME = "xmake.lua"
+_XT_MAIN_MARKER = "xt_main"
+
+
+def has_xmake_project(project_dir: str | Path) -> bool:
+    """检查目录中是否存在 xmake.lua。"""
+    return _build_xmake_path(project_dir).is_file()
+
+
+def has_xt_main_target(project_dir: str | Path) -> bool:
+    """检查工程是否包含 xt_main 标记。"""
+    xmake_path = _build_xmake_path(project_dir)
+    if not xmake_path.is_file():
+        return False
+
+    content = xmake_path.read_text(encoding="utf-8")
+    return _XT_MAIN_MARKER in content
+
+
+def _build_xmake_path(project_dir: str | Path) -> Path:
+    """构造 xmake.lua 路径。"""
+    return normalize_path(project_dir) / _XMAKE_FILENAME

xmake.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+from models import BuildContext, ConfigSource, ResolvedValue
+
+
+def _xmake_file(context: BuildContext) -> Path:
+    """返回 xmake 主脚本路径。"""
+    return context.sdk_dir / "xmake.lua"
+
+
+def build_command(context: BuildContext) -> list[str]:
+    """构造构建命令。"""
+    return ["xmake", "build", "-F", str(_xmake_file(context))]
+
+
+def build_clean_config_command(context: BuildContext) -> list[str]:
+    """构造清理 xmake 配置命令。"""
+    return ["xmake", "f", "-c", "-F", str(_xmake_file(context))]
+
+
+def build_clean_command(context: BuildContext) -> list[str]:
+    """构造清理命令。"""
+    return ["xmake", "clean", "-F", str(_xmake_file(context))]
+
+
+def build_run_command(context: BuildContext, name: str | None = None) -> list[str]:
+    """构造运行命令。"""
+    command = ["xmake", "run", "-F", str(_xmake_file(context))]
+    if name:
+        command.append(name)
+    return command
+
+
+def build_env(context: BuildContext) -> dict[str, str]:
+    """构造 xmake 调用环境变量。"""
+    env = os.environ.copy()
+    env.update(
+        {
+            "XT_SDK_ROOT": str(context.sdk_dir),
+            "XT_SDK_TARGET_PATH": str(context.target_path),
+            "XT_SDK_TOOLCHAIN": str(context.toolchain_path) if context.toolchain_path is not None else "",
+            "XT_SDK_PROJECT_PATH": str(context.project_dir),
+            "XT_SDK_BOARD": context.board,
+        }
+    )
+    return env
+
+
+def run_xmake(
+    context: BuildContext,
+    command: list[str],
+    *,
+    check: bool = False,
+) -> subprocess.CompletedProcess[bytes]:
+    """执行 xmake 命令。"""
+    env = build_env(context)
+    if context.debug_enabled:
+        _print_debug_details(context, command, env)
+    return subprocess.run(
+        args=command,
+        cwd=context.project_dir,
+        env=env,
+        check=check,
+    )
+
+
+def _print_debug_details(context: BuildContext, command: list[str], env: dict[str, str]) -> None:
+    """输出调试模式下的命令与环境信息。"""
+    print(f"Final command: {' '.join(command)}")
+    print("Environment variables:")
+    for name in ("XT_SDK_ROOT", "XT_SDK_TARGET_PATH", "XT_SDK_TOOLCHAIN", "XT_SDK_PROJECT_PATH", "XT_SDK_BOARD"):
+        value, source = _resolve_env_debug_source(context, name)
+        print(f"  {name}={env[name]} (source={source}, value_source={value})")
+
+
+def _resolve_env_debug_source(context: BuildContext, env_name: str) -> tuple[str, str]:
+    """返回环境变量值来源与派生来源。"""
+    mapping = {
+        "XT_SDK_ROOT": "sdk",
+        "XT_SDK_TARGET_PATH": "target_path",
+        "XT_SDK_TOOLCHAIN": "toolchain_path",
+        "XT_SDK_PROJECT_PATH": "project",
+        "XT_SDK_BOARD": "board",
+    }
+    resolved_value = None if context.resolved_values is None else context.resolved_values.get(mapping[env_name])
+    if isinstance(resolved_value, ResolvedValue):
+        return str(resolved_value.value), resolved_value.source.value
+    return "", ConfigSource.DERIVED.value