alloy-embedded 0.1.0__py3-none-any.whl

alloy_cli/__init__.py

@@ -0,0 +1,3 @@
+"""alloy CLI: codegen + build orchestration for the Alloy framework."""
+
+__version__ = "0.1.0"

alloy_cli/build.py

@@ -0,0 +1,201 @@
+"""Render the CMake build tree and drive cmake + ninja.
+
+Users never see CMake: the tree lives in .alloy/build-tree (gitignored,
+regenerated every run). `alloy export cmake` will later emit a standalone
+copy for people who want to own their build.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from .emit.common import EmitError
+from .project import Project
+
+# Core name -> GCC -mcpu flag; fallback per architecture.
+_CPU_BY_CORE = {
+    "cm0": "cortex-m0",
+    "cm0plus": "cortex-m0plus",
+    "cm3": "cortex-m3",
+    "cm4": "cortex-m4",
+    "cm7": "cortex-m7",
+    "cm33": "cortex-m33",
+}
+_CPU_BY_ARCH = {
+    "armv6m": "cortex-m0plus",
+    "armv7m": "cortex-m3",
+    "armv7em": "cortex-m4",
+    "armv8m_base": "cortex-m23",
+    "armv8m_main": "cortex-m33",
+}
+
+
+def _arch_ns(chip: dict[str, Any]) -> str:
+    arch = chip["cores"][0]["arch"]
+    if arch.startswith("armv"):
+        return "cortex_m"
+    if arch.startswith("xtensa"):
+        return "xtensa"
+    raise EmitError(f"unsupported architecture {arch}")
+
+
+def _xtensa_prefix() -> str:
+    if found := shutil.which("xtensa-esp-elf-gcc"):
+        return str(Path(found).with_name("xtensa-esp-elf-"))
+    candidate = Path.home() / ".alloy/tools/xtensa-esp-elf/bin/xtensa-esp-elf-gcc"
+    if candidate.exists():
+        return str(candidate.with_name("xtensa-esp-elf-"))
+    raise EmitError(
+        "xtensa-esp-elf toolchain not found — looked on PATH and ~/.alloy/tools/xtensa-esp-elf"
+    )
+
+
+def _cpu_flags(chip: dict[str, Any]) -> str:
+    if _arch_ns(chip) == "xtensa":
+        # The unified xtensa-esp-elf toolchain is multi-core: -mdynconfig
+        # selects the concrete core (ESP32 = LX6 little-endian); without it
+        # GCC emits generic BIG-endian objects that esptool rejects. The flag
+        # must stay RELATIVE to match the multilib table (esp32/libgcc.a);
+        # macOS hardened dlopen then needs XTENSA_GNU_CONFIG (absolute) set
+        # in the environment — see _build_env().
+        return f"-mdynconfig=xtensa_{chip['family']}.so -mlongcalls"
+    core = chip["cores"][0]
+    cpu = _CPU_BY_CORE.get(core["name"]) or _CPU_BY_ARCH.get(core["arch"])
+    if cpu is None:
+        raise EmitError(f"no CPU mapping for core {core['name']} / arch {core['arch']}")
+    # Soft-float everywhere for now, even on FPU parts: hard-float needs a
+    # CPACR enable in the arch startup before the first FP instruction.
+    # TODO(arch): enable CP10/CP11 on armv7em, then honor core.fpu here.
+    return f"-mcpu={cpu} -mthumb -mfloat-abi=soft"
+
+
+def _toolchain_cmake(chip: dict[str, Any], cpu_flags: str) -> str:
+    if _arch_ns(chip) == "xtensa":
+        prefix = _xtensa_prefix()
+        processor = "xtensa"
+        cc, cxx = f"{prefix}gcc", f"{prefix}g++"
+    else:
+        processor = "arm"
+        cc, cxx = "arm-none-eabi-gcc", "arm-none-eabi-g++"
+    return f"""# GENERATED by alloy — DO NOT EDIT
+set(CMAKE_SYSTEM_NAME Generic)
+set(CMAKE_SYSTEM_PROCESSOR {processor})
+set(CMAKE_C_COMPILER "{cc}")
+set(CMAKE_CXX_COMPILER "{cxx}")
+set(CMAKE_ASM_COMPILER "{cc}")
+set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)
+set(CMAKE_C_FLAGS_INIT "{cpu_flags}")
+set(CMAKE_CXX_FLAGS_INIT "{cpu_flags}")
+set(CMAKE_ASM_FLAGS_INIT "{cpu_flags}")
+set(CMAKE_EXE_LINKER_FLAGS_INIT "{cpu_flags}")
+"""
+
+
+def _cmakelists(project: Project, chip: dict[str, Any], sources: list[Path],
+                runtime_sources: list[Path]) -> str:
+    gen = project.gen_dir
+    gen_sources = [gen / "board.cpp"]
+    for optional in ("vector_table.c", "boot2.c", "irq_data.c"):
+        if (gen / optional).exists():
+            gen_sources.append(gen / optional)
+    src_list = "\n    ".join(
+        f'"{p}"' for p in [*sources, *gen_sources, *runtime_sources]
+    )
+    # newlib nano/nosys specs are an ARM-newlib convention; the xtensa
+    # toolchain links its own newlib without them.
+    specs = "" if _arch_ns(chip) == "xtensa" else """
+    --specs=nano.specs
+    --specs=nosys.specs"""
+    return f"""# GENERATED by alloy — DO NOT EDIT
+cmake_minimum_required(VERSION 3.25)
+project({project.name} C CXX ASM)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_C_EXTENSIONS OFF)
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+add_executable({project.name}.elf
+    {src_list}
+)
+
+target_include_directories({project.name}.elf PRIVATE
+    "{project.alloy_root / 'src'}"
+    "{gen}"
+)
+
+target_compile_options({project.name}.elf PRIVATE
+    -Os -g3
+    -ffunction-sections -fdata-sections
+    -Wall -Wextra
+    $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
+    $<$<COMPILE_LANGUAGE:CXX>:-fno-rtti>
+    $<$<COMPILE_LANGUAGE:CXX>:-fno-threadsafe-statics>
+)
+
+target_link_options({project.name}.elf PRIVATE
+    -T "{gen / 'linker.ld'}"
+    -nostartfiles
+    -Wl,--gc-sections
+    -Wl,-Map={project.name}.map{specs}
+)
+"""
+
+
+def build(project: Project, chip: dict[str, Any]) -> Path:
+    sources = sorted((project.root / "src").rglob("*.cpp")) + \
+        sorted((project.root / "src").rglob("*.c"))
+    if not sources:
+        raise EmitError(f"no sources under {project.root / 'src'}")
+
+    arch_dir = project.alloy_root / "src" / "alloy" / "arch" / _arch_ns(chip)
+    runtime_sources = sorted(arch_dir.glob("*.cpp")) + sorted(arch_dir.glob("*.S"))
+
+    tree = project.build_dir
+    tree.mkdir(parents=True, exist_ok=True)
+    (tree / "toolchain.cmake").write_text(_toolchain_cmake(chip, _cpu_flags(chip)))
+    (tree / "CMakeLists.txt").write_text(_cmakelists(project, chip, sources, runtime_sources))
+
+    env = None
+    if _arch_ns(chip) == "xtensa":
+        import os  # noqa: PLC0415
+
+        dynconfig = (Path(_xtensa_prefix()).parent.parent / "lib" /
+                     f"xtensa_{chip['family']}.so")
+        if not dynconfig.exists():
+            raise EmitError(f"toolchain dynconfig missing: {dynconfig}")
+        env = os.environ | {"XTENSA_GNU_CONFIG": str(dynconfig)}
+
+    out = tree / "out"
+    subprocess.run(
+        ["cmake", "-G", "Ninja", "-S", str(tree), "-B", str(out),
+         f"-DCMAKE_TOOLCHAIN_FILE={tree / 'toolchain.cmake'}",
+         "-DCMAKE_BUILD_TYPE=MinSizeRel"],
+        check=True, env=env,
+    )
+    subprocess.run(["cmake", "--build", str(out)], check=True, env=env)
+
+    elf = out / f"{project.name}.elf"
+    if not elf.exists():
+        raise EmitError(f"build finished but {elf} is missing")
+
+    size_tool = (
+        f"{_xtensa_prefix()}size" if _arch_ns(chip) == "xtensa"
+        else shutil.which("arm-none-eabi-size")
+    )
+    if size_tool:
+        subprocess.run([size_tool, str(elf)], check=False)
+
+    # clangd support out of the box.
+    cc_json = out / "compile_commands.json"
+    link = project.root / "compile_commands.json"
+    if cc_json.exists():
+        link.unlink(missing_ok=True)
+        link.symlink_to(cc_json)
+
+    return elf

alloy_cli/cli.py

@@ -0,0 +1,351 @@
+"""alloy CLI.
+
+Commands:
+    new        scaffold a portable project (the scaffold IS the CI-built blink)
+    boards     list boards (--json for IDE integrations)
+    gen        regenerate .alloy/generated from the device database
+    build      gen + render CMake tree + compile
+    flash      build + program the board
+    monitor    bidirectional serial monitor
+    run        flash + monitor
+    clean      remove per-board build trees
+    set-board  change the board in alloy.toml
+    setup      verify/install toolchains into ~/.alloy/tools
+    debug-info debug-server facts for a board (--json)
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from alloy_devices.loader import load_database
+
+from . import __version__
+from .build import build
+from .emit import generate
+from .emit.common import EmitError
+from .project import Project, ProjectError, load_project
+
+_MAIN_CPP = """\
+// Portable hello — blink AND echo, so the board never looks dead after a
+// flash. Identical bytes on every supported board; zero #ifdefs.
+#include <alloy/board.hpp>
+
+#include <cstdint>
+
+int main() {
+    board::init();
+    auto uart = board::debug_uart::open({.baud = board::debug_uart_baud});
+    uart.write("alloy hello: blinking + echoing\\r\\n");
+
+    std::uint32_t last_toggle = alloy::uptime_ms();
+    while (true) {
+        std::uint8_t byte{};
+        if (uart.read(byte)) {
+            uart.write(byte);
+        }
+        if (alloy::uptime_ms() - last_toggle >= 500u) {
+            board::led.toggle();
+            last_toggle = alloy::uptime_ms();
+        }
+    }
+}
+"""
+
+_ALLOY_TOML = """\
+[project]
+name = "{name}"
+
+[board]
+id = "{board}"
+
+[alloy]
+root = "{root}"
+"""
+
+_GITIGNORE = """\
+.alloy/
+compile_commands.json
+"""
+
+
+def _project(args: argparse.Namespace) -> Project:
+    return load_project(
+        Path(getattr(args, "project", ".") or "."),
+        board_override=getattr(args, "board", None),
+    )
+
+
+def cmd_new(args: argparse.Namespace) -> int:
+    from .project import _find_alloy_root  # noqa: PLC0415
+
+    target = Path(args.name)
+    if target.exists():
+        print(f"error: {target} already exists", file=sys.stderr)
+        return 1
+    alloy_root = _find_alloy_root(Path.cwd())
+    boards_dir = alloy_root / "boards"
+    if not (boards_dir / args.board / "board.json").exists():
+        known = sorted(p.name for p in boards_dir.iterdir() if (p / "board.json").exists())
+        print(f"error: unknown board '{args.board}' — known: {', '.join(known)}", file=sys.stderr)
+        return 1
+    (target / "src").mkdir(parents=True)
+    from .project import packaged_alloy_root  # noqa: PLC0415
+
+    if alloy_root == packaged_alloy_root():
+        # Wheel installs are relocatable: resolution finds the package at
+        # runtime; baking a version-specific site-packages path would rot.
+        toml_text = _ALLOY_TOML.split("[alloy]")[0].format(
+            name=target.name, board=args.board
+        )
+    else:
+        toml_text = _ALLOY_TOML.format(
+            name=target.name, board=args.board, root=alloy_root
+        )
+    (target / "alloy.toml").write_text(toml_text)
+    (target / "src" / "main.cpp").write_text(_MAIN_CPP)
+    (target / ".gitignore").write_text(_GITIGNORE)
+    print(f"created {target}/ (board: {args.board}, framework: {alloy_root})")
+    print(f"next:  cd {target} && alloy run")
+    return 0
+
+
+def cmd_boards(args: argparse.Namespace) -> int:
+    import json  # noqa: PLC0415
+
+    project_dir = Path(getattr(args, "project", ".") or ".")
+    try:
+        project = load_project(project_dir)
+        boards_dir = project.alloy_root / "boards"
+    except ProjectError:
+        from .project import _find_alloy_root  # noqa: PLC0415
+
+        boards_dir = _find_alloy_root(project_dir.resolve()) / "boards"
+    rows = []
+    for board_json in sorted(boards_dir.glob("*/board.json")):
+        board = json.loads(board_json.read_text())
+        rows.append(board)
+    if getattr(args, "json", False):
+        print(json.dumps({
+            "schema": "alloy.boards.v1",
+            "boards": [
+                {
+                    "id": b["id"],
+                    "name": b.get("name", ""),
+                    "chip": b["chip"],
+                    "probe": b.get("probe", {}).get("kind"),
+                    "roles": sorted(b.get("roles", {})),
+                }
+                for b in rows
+            ],
+        }, indent=2))
+        return 0
+    for b in rows:
+        print(f"{b['id']:24} {b.get('name', ''):32} chip={b['chip']}")
+    return 0
+
+
+def cmd_gen(args: argparse.Namespace) -> int:
+    project = _project(args)
+    written = generate(project)
+    print(f"generated {len(written)} file(s) -> {project.gen_dir}")
+    return 0
+
+
+def cmd_build(args: argparse.Namespace) -> int:
+    project = _project(args)
+    generate(project)
+    board = project.load_board()
+    db = load_database(project.devices_root)
+    chip = db.chips[board["chip"]]
+    elf = build(project, chip)
+    print(f"\nbuilt {elf}")
+    return 0
+
+
+def cmd_flash(args: argparse.Namespace) -> int:
+    from .flash import flash  # noqa: PLC0415
+
+    project = _project(args)
+    generate(project)
+    board = project.load_board()
+    db = load_database(project.devices_root)
+    chip = db.chips[board["chip"]]
+    elf = build(project, chip)
+    runner = flash(board, chip, elf)
+    print(f"\nflashed {elf.name} via {runner}")
+    return 0
+
+
+def cmd_monitor(args: argparse.Namespace) -> int:
+    from .monitor import monitor  # noqa: PLC0415
+
+    project = _project(args)
+    monitor(project.load_board())
+    return 0
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    from .emit.common import EmitError  # noqa: PLC0415
+    from .monitor import monitor  # noqa: PLC0415
+
+    rc = cmd_flash(args)
+    if rc != 0:
+        return rc
+    project = _project(args)
+    try:
+        monitor(project.load_board())
+    except EmitError as exc:
+        print(f"note: {exc}")
+    return 0
+
+
+def cmd_clean(args: argparse.Namespace) -> int:
+    import shutil  # noqa: PLC0415
+
+    root = Path(getattr(args, "project", ".") or ".").resolve()
+    if not (root / "alloy.toml").exists():
+        print(f"error: {root} is not an alloy project (no alloy.toml)", file=sys.stderr)
+        return 1
+    base = root / ".alloy"
+    targets = [base] if args.all else (
+        [base / "build-tree" / args.board, base / "generated" / args.board]
+        if getattr(args, "board", None)
+        else [base / "build-tree"]
+    )
+    removed = 0
+    for target in targets:
+        if target.exists():
+            shutil.rmtree(target)
+            removed += 1
+            print(f"removed {target}")
+    if removed == 0:
+        print("nothing to clean")
+    return 0
+
+
+def cmd_set_board(args: argparse.Namespace) -> int:
+    import re  # noqa: PLC0415
+
+    root = Path(getattr(args, "project", ".") or ".").resolve()
+    toml_path = root / "alloy.toml"
+    if not toml_path.exists():
+        print(f"error: {root} is not an alloy project (no alloy.toml)", file=sys.stderr)
+        return 1
+    # Validate against known boards first.
+    project = load_project(root)
+    boards_dir = project.alloy_root / "boards"
+    if not (boards_dir / args.board_id / "board.json").exists():
+        known = sorted(p.name for p in boards_dir.iterdir() if (p / "board.json").exists())
+        print(f"error: unknown board '{args.board_id}' — known: {', '.join(known)}",
+              file=sys.stderr)
+        return 1
+    text = toml_path.read_text()
+    new_text, n = re.subn(
+        r'(\[board\]\s*\n\s*id\s*=\s*")[^"]*(")',
+        rf"\g<1>{args.board_id}\g<2>",
+        text,
+        count=1,
+    )
+    if n != 1:
+        print("error: could not locate [board] id in alloy.toml", file=sys.stderr)
+        return 1
+    toml_path.write_text(new_text)
+    print(f"board set to {args.board_id}")
+    return 0
+
+
+def cmd_setup(args: argparse.Namespace) -> int:
+    from .toolchains import setup  # noqa: PLC0415
+
+    families = set(args.family) if args.family else None
+    return setup(families, check_only=args.check,
+                 json_out=args.json, json_progress=args.json_progress)
+
+
+def cmd_debug_info(args: argparse.Namespace) -> int:
+    import json  # noqa: PLC0415
+
+    from .debug import debug_info  # noqa: PLC0415
+
+    project = _project(args)
+    board = project.load_board()
+    db = load_database(project.devices_root)
+    chip = db.chips[board["chip"]]
+    elf = project.build_dir / "out" / f"{project.name}.elf"
+    info = debug_info(board, chip, elf if elf.exists() else None)
+    info["schema"] = "alloy.debug_info.v1"
+    if getattr(args, "json", False):
+        print(json.dumps(info, indent=2))
+    else:
+        for key, value in info.items():
+            print(f"{key:14} {value}")
+    return 0
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="alloy", description=__doc__)
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_new = sub.add_parser("new", help="scaffold a new project")
+    p_new.add_argument("name")
+    p_new.add_argument("--board", required=True)
+    p_new.set_defaults(func=cmd_new)
+
+    p_boards = sub.add_parser("boards", help="list known boards")
+    p_boards.add_argument("--project", default=".")
+    p_boards.add_argument("--json", action="store_true")
+    p_boards.set_defaults(func=cmd_boards)
+
+    p_clean = sub.add_parser("clean", help="remove per-board build trees")
+    p_clean.add_argument("--project", default=".")
+    p_clean.add_argument("--board", help="clean only this board's trees")
+    p_clean.add_argument("--all", action="store_true", help="remove the whole .alloy/")
+    p_clean.set_defaults(func=cmd_clean)
+
+    p_setb = sub.add_parser("set-board", help="change the board in alloy.toml")
+    p_setb.add_argument("board_id")
+    p_setb.add_argument("--project", default=".")
+    p_setb.set_defaults(func=cmd_set_board)
+
+    p_setup = sub.add_parser("setup", help="verify/install toolchains")
+    p_setup.add_argument("--family", action="append",
+                         help="limit to a chip family (repeatable)")
+    p_setup.add_argument("--check", action="store_true", help="report only")
+    p_setup.add_argument("--json", action="store_true")
+    p_setup.add_argument("--json-progress", action="store_true")
+    p_setup.set_defaults(func=cmd_setup)
+
+    p_dbg = sub.add_parser("debug-info", help="debug-server facts for a board")
+    p_dbg.add_argument("--project", default=".")
+    p_dbg.add_argument("--board")
+    p_dbg.add_argument("--json", action="store_true")
+    p_dbg.set_defaults(func=cmd_debug_info)
+
+    for cmd, func in (("gen", cmd_gen), ("build", cmd_build), ("flash", cmd_flash),
+                      ("monitor", cmd_monitor), ("run", cmd_run)):
+        p = sub.add_parser(cmd)
+        p.add_argument("--project", default=".")
+        p.add_argument("--board", help="override the board declared in alloy.toml")
+        p.set_defaults(func=func)
+
+    args = parser.parse_args()
+    try:
+        sys.exit(args.func(args))
+    except (ProjectError, EmitError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        sys.exit(1)
+    except subprocess.CalledProcessError as exc:
+        cmd = exc.cmd[0] if isinstance(exc.cmd, list) else str(exc.cmd)
+        print(f"error: {cmd} failed (exit {exc.returncode})", file=sys.stderr)
+        sys.exit(1)
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()

alloy_cli/debug.py

@@ -0,0 +1,61 @@
+"""Debug-server facts per board — consumed by IDE integrations.
+
+The openocd interface/target maps live HERE (flash.py imports them): one
+source of truth for tool-integration knowledge. `debug_info` emits what a
+Cortex-Debug launch.json needs; unsupported families say so honestly.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+# OpenOCD script maps (tool integration, not silicon facts).
+OPENOCD_TARGET = {
+    "stm32g0": "stm32g0x",
+    "stm32f4": "stm32f4x",
+    "stm32f7": "stm32f7x",
+    "stm32g4": "stm32g4x",
+    "same70": "atsamv",
+    "rp2040": "rp2040",
+}
+
+OPENOCD_INTERFACE = {
+    "stlink": "stlink",
+    "cmsis-dap": "cmsis-dap",
+}
+
+
+def debug_info(board: dict[str, Any], chip: dict[str, Any],
+               elf: Path | None) -> dict[str, Any]:
+    probe = board.get("probe") or {}
+    kind = probe.get("kind", "")
+    interface = OPENOCD_INTERFACE.get(kind)
+    target = OPENOCD_TARGET.get(chip["family"])
+
+    info: dict[str, Any] = {
+        "board": board["id"],
+        "chip": f"{chip['vendor']}/{chip['part']}",
+        "elf": str(elf) if elf else None,
+        "svd": None,  # SVD export is a future phase
+    }
+    if interface and target:
+        info.update(
+            supported=True,
+            servertype="openocd",
+            interface_cfg=f"interface/{interface}.cfg",
+            target_cfg=f"target/{target}.cfg",
+            device=chip["part"],
+            chip_id=probe.get("chip_id"),
+            gdb="arm-none-eabi-gdb",
+        )
+    else:
+        reason = (
+            "ESP32 interactive debug needs openocd-esp32 + xtensa gdb (future phase)"
+            if kind == "esptool"
+            else "BOOTSEL boards need a debug probe wired to SWD (picoprobe/debugprobe)"
+            if kind == "bootsel"
+            else f"no openocd mapping for probe kind '{kind}' / family '{chip['family']}'"
+        )
+        info.update(supported=False, reason=reason)
+    return info