Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@
# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root.
#
# S0's acceptance (spec section 8): build and test on Windows, Linux and macOS; initialize
# succeeds; the notices list is generated.
# succeeds; the notices list is generated. S1's: the core opens the RTOS's nucleo_f446re and
# pico2_w boards and reports the generator's errors with their locations, against the RTOS
# checked out at a pinned commit.
name: CI

on:
Expand Down Expand Up @@ -34,7 +36,18 @@ jobs:
- run: python -m pip install -e "core[dev]"
- run: ruff check core tools
- run: ruff format --check core tools
- name: EmbLinkRTOS, for stage S1's acceptance tests
uses: actions/checkout@v7
with:
repository: EmbLinkOs/EmbLinkRTOS
# The RTOS revision the core is tested against. Raise it with the hw.json and
# diagnostics formats the core supports (core/src/emblink_studio_core/rtos.py).
ref: a2cb045cf27a0f53bc53ce110d3bffc4d381817f
path: rtos
persist-credentials: false
- run: python -m pytest core -q
env:
EMBLINK_STUDIO_TEST_RTOS: ${{ github.workspace }}/rtos
- name: Notices list and licence check
run: python tools/notices.py --components third_party/components.json --pyproject core/pyproject.toml

Expand Down
3 changes: 2 additions & 1 deletion core/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ description = "EmbLink Studio Core: the engine behind the EmbLink Studio IDE for
license = "Apache-2.0"
requires-python = ">=3.11"
# Runtime dependencies must also be listed in third_party/components.json (tools/notices.py checks).
dependencies = []
# PyYAML: the RTOS's generator, which the core runs with its own Python, reads YAML with it.
dependencies = ["PyYAML>=6.0"]

[project.optional-dependencies]
dev = ["pytest>=8", "jsonschema>=4.21", "ruff>=0.6"]
Expand Down
89 changes: 85 additions & 4 deletions core/src/emblink_studio_core/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,17 +10,75 @@
"""The `emblink-studio-core` command line.
`serve` runs the JSON-RPC server on standard input and output; `--version` prints the
core's version and the protocol it speaks. Every RPC method gains a subcommand as it
lands (spec section 4).
core's version and the protocol it speaks. Every RPC method has a subcommand too
(spec section 4), printing the same result as JSON:
emblink-studio-core project status BOARD
emblink-studio-core project validate BOARD exit 0 if valid, 2 if not
emblink-studio-core board list RTOS
emblink-studio-core board describe|pins|clocks|memory BOARD
emblink-studio-core generate run BOARD
emblink-studio-core generate diff BOARD exit 0 if up to date, 1 if not
BOARD is a board directory of an EmbLinkRTOS checkout, such as
~/EmbLinkRTOS/boards/st/nucleo_f446re; RTOS is the checkout. The person running a
command chose to run the checkout's generator, so the command line does not ask for
trust; the IDE does (spec section 9).
"""

from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path
from typing import Any

from . import __version__, protocol


def _print(result: Any) -> None:
json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
sys.stdout.write("\n")


def _run(args: argparse.Namespace) -> int:
from .rtos import Rtos
from .workspace import Workspace, list_boards

if args.command == "board" and args.action == "list":
rtos = Rtos.find(Path(args.target).expanduser().resolve())
if rtos is None:
print(f"{args.target} is not an EmbLinkRTOS checkout.", file=sys.stderr)
return 1
_print(
{
"rtos": {"root": str(rtos.root), "generator": rtos.check_supported()},
"boards": list_boards(rtos),
}
)
return 0

workspace = Workspace.open(args.target)
if args.command == "project" and args.action == "status":
_print(workspace.status(trusted=True))
return 0
if args.command == "project" and args.action == "validate":
result = workspace.validate()
_print(result)
return 0 if result["valid"] else 2
if args.command == "board":
_print(getattr(workspace.model(), args.action)())
return 0
if args.command == "generate" and args.action == "run":
result = workspace.generate()
_print(result)
return 0 if result["written"] else 2
result = workspace.diff()
_print(result)
return 0 if result["up_to_date"] else 1


def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(prog="emblink-studio-core", description="EmbLink Studio Core")
parser.add_argument(
Expand All @@ -30,11 +88,34 @@ def main(argv: list[str] | None = None) -> int:
)
commands = parser.add_subparsers(dest="command", metavar="command")
commands.add_parser("serve", help="serve JSON-RPC 2.0 on standard input and output")

project = commands.add_parser("project", help="a board's status and validation")
project.add_argument("action", choices=["status", "validate"])
project.add_argument("target", metavar="BOARD", help="a board directory of an RTOS checkout")
board = commands.add_parser("board", help="the boards of a checkout, and a board's model")
board.add_argument("action", choices=["list", "describe", "pins", "clocks", "memory"])
board.add_argument(
"target", metavar="BOARD_OR_RTOS", help="the checkout for list, a board directory otherwise"
)
generate = commands.add_parser(
"generate", help="run the generator, or see what it would change"
)
generate.add_argument("action", choices=["run", "diff"])
generate.add_argument("target", metavar="BOARD", help="a board directory of an RTOS checkout")
args = parser.parse_args(argv)

if args.command == "serve":
from .server import serve

return serve()
parser.print_help()
return 2
if args.command is None:
parser.print_help()
return 2

from .errors import CoreError

try:
return _run(args)
except CoreError as exc:
print(exc.message, file=sys.stderr)
return 1
76 changes: 76 additions & 0 deletions core/src/emblink_studio_core/diagnostics.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# SPDX-License-Identifier: Apache-2.0
# Copyright 2026 Junior Deogracias
#
# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS.
# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root.
#
# File: diagnostics.py
# Author: Junior Deogracias
# Created: 2026-11-12
"""The generator's diagnostics, as structured records the views can link to a file.
emb-hwgen 0.x writes one diagnostic per line (the RTOS's rule HW-002):
boards/st/nucleo_f446re/board.yaml:25: pins.usart2.tx: PA2 af9 is not usart2_tx
warning: soc/st/stm32f4/stm32f4.yaml:17: cpu.mpu: the cortex_m port does not use the MPU yet
that is, an optional 'warning: ', then the file (relative to the checkout, or absolute
for a board outside it), the line, the node's path in the YAML ('(root)' for the
document) and the message. Each becomes
{"severity", "message", "file", "line", "path", "source"}
with the file made absolute, so a view opens it at the line. Lines that are not
diagnostics (the generator's own summary) are dropped; a line in no known form is
kept as a diagnostic with only its message, so nothing the generator says is lost.
When the generator writes JSON diagnostics (asked of the RTOS for S1), they are read
instead and this parser stays for older checkouts.
"""

from __future__ import annotations

import re
from pathlib import Path
from typing import Any

SOURCE = "emb-hwgen"
_LOCATED = re.compile(r"^(?P<file>.+?):(?P<line>\d+): (?P<rest>.*)$")
_PATH = re.compile(r"^(?P<path>[^\s:]+): (?P<message>.+)$")


def parse(text: str, root: Path) -> list[dict[str, Any]]:
"""The diagnostics in emb-hwgen's output `text`; relative files are under `root`."""
out: list[dict[str, Any]] = []
for raw in text.splitlines():
line = raw.strip()
if not line or line.startswith("emb-hwgen"):
continue # blank, or the generator's summary ('emb-hwgen: 8 error(s)')
severity = "error"
if line.startswith("warning: "):
severity = "warning"
line = line[len("warning: ") :]
diagnostic: dict[str, Any] = {"severity": severity, "source": SOURCE}
located = _LOCATED.match(line)
if located is None:
diagnostic["message"] = line
out.append(diagnostic)
continue
file = Path(located["file"])
diagnostic["file"] = str(file if file.is_absolute() else root / file)
diagnostic["line"] = int(located["line"])
rest = located["rest"]
with_path = _PATH.match(rest)
if with_path is not None:
diagnostic["path"] = with_path["path"]
diagnostic["message"] = with_path["message"]
else:
diagnostic["message"] = rest
out.append(diagnostic)
return out


def counts(diagnostics: list[dict[str, Any]]) -> dict[str, int]:
return {
"errors": sum(1 for d in diagnostics if d["severity"] == "error"),
"warnings": sum(1 for d in diagnostics if d["severity"] == "warning"),
}
28 changes: 28 additions & 0 deletions core/src/emblink_studio_core/errors.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# SPDX-License-Identifier: Apache-2.0
# Copyright 2026 Junior Deogracias
#
# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS.
# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root.
#
# File: errors.py
# Author: Junior Deogracias
# Created: 2026-11-12
"""The core's error, shared by the server, the command line and the project code.
A CoreError carries one of the protocol's error codes (spec section 5, Errors), a
message written for the person, and optional data: the output of the tool that
failed and, where it applies, the file and line. The server answers it as a JSON-RPC
error; the command line prints its message and exits with 1.
"""

from __future__ import annotations

from typing import Any


class CoreError(Exception):
def __init__(self, code: int, message: str, data: Any = None) -> None:
super().__init__(message)
self.code = code
self.message = message
self.data = data
Loading
Loading