Skip to content

Commit 98155a1

Browse files
authored
S1: the core opens a board, reads its model, validates and generates (#9)
* S1: the core opens a board, reads its model, validates and generates The core's first workspace is a board of an EmbLinkRTOS checkout, until the project manifest exists (spec section 8: S1 to S3 work on the boards in the RTOS tree and their generated model). - project.open, close, status: a board directory, boards/<vendor>/<board>/, inside a checkout. Opening reads files and runs nothing. A checkout whose emb-hwgen or hw.json is outside the formats the core reads (emb-hwgen 0.x, hw.json schema 0) is refused with unsupported_rtos. - board.list, describe, pins, clocks, memory: the generator's resolved model, read from hw.json; nothing is computed, in the core or the GUI. - project.validate, generate.run, generate.diff: run the checkout's own emb-hwgen, with the core's Python, and turn its lines (HW-002) into diagnostics with the file, the line and the path in the YAML. diff writes nothing. - project.trust: running the generator runs the checkout's code, so it waits until the checkout is trusted (spec section 9). Trust is kept per path in the person's own settings, never in a checkout. - Every method has a command too: emblink-studio-core board list RTOS, project validate BOARD, generate diff BOARD, and the rest. - PyYAML becomes the core's dependency: the generator reads YAML with it. Schemas for every new method are in protocol/. Tests: a fake emb-hwgen with the real interface and output, the protocol end to end, and S1's acceptance against the real nucleo_f446re and pico2_w, with errors made in a copy of the NUCLEO's description found at their lines; CI checks out the RTOS at a pinned commit for it. Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> * core tests: Windows paths; show the generator's output when it fails Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> * core tests: format Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> * core acceptance: the clock error on Python 3.12+ only, until the RTOS's generator is fixed Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --------- Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com>
1 parent 9afb1fa commit 98155a1

34 files changed

Lines changed: 2793 additions & 18 deletions

‎.github/workflows/ci.yml‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@
55
# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root.
66
#
77
# S0's acceptance (spec section 8): build and test on Windows, Linux and macOS; initialize
8-
# succeeds; the notices list is generated.
8+
# succeeds; the notices list is generated. S1's: the core opens the RTOS's nucleo_f446re and
9+
# pico2_w boards and reports the generator's errors with their locations, against the RTOS
10+
# checked out at a pinned commit.
911
name: CI
1012

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

‎core/pyproject.toml‎

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

2122
[project.optional-dependencies]
2223
dev = ["pytest>=8", "jsonschema>=4.21", "ruff>=0.6"]

‎core/src/emblink_studio_core/cli.py‎

Lines changed: 85 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,17 +10,75 @@
1010
"""The `emblink-studio-core` command line.
1111
1212
`serve` runs the JSON-RPC server on standard input and output; `--version` prints the
13-
core's version and the protocol it speaks. Every RPC method gains a subcommand as it
14-
lands (spec section 4).
13+
core's version and the protocol it speaks. Every RPC method has a subcommand too
14+
(spec section 4), printing the same result as JSON:
15+
16+
emblink-studio-core project status BOARD
17+
emblink-studio-core project validate BOARD exit 0 if valid, 2 if not
18+
emblink-studio-core board list RTOS
19+
emblink-studio-core board describe|pins|clocks|memory BOARD
20+
emblink-studio-core generate run BOARD
21+
emblink-studio-core generate diff BOARD exit 0 if up to date, 1 if not
22+
23+
BOARD is a board directory of an EmbLinkRTOS checkout, such as
24+
~/EmbLinkRTOS/boards/st/nucleo_f446re; RTOS is the checkout. The person running a
25+
command chose to run the checkout's generator, so the command line does not ask for
26+
trust; the IDE does (spec section 9).
1527
"""
1628

1729
from __future__ import annotations
1830

1931
import argparse
32+
import json
33+
import sys
34+
from pathlib import Path
35+
from typing import Any
2036

2137
from . import __version__, protocol
2238

2339

40+
def _print(result: Any) -> None:
41+
json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
42+
sys.stdout.write("\n")
43+
44+
45+
def _run(args: argparse.Namespace) -> int:
46+
from .rtos import Rtos
47+
from .workspace import Workspace, list_boards
48+
49+
if args.command == "board" and args.action == "list":
50+
rtos = Rtos.find(Path(args.target).expanduser().resolve())
51+
if rtos is None:
52+
print(f"{args.target} is not an EmbLinkRTOS checkout.", file=sys.stderr)
53+
return 1
54+
_print(
55+
{
56+
"rtos": {"root": str(rtos.root), "generator": rtos.check_supported()},
57+
"boards": list_boards(rtos),
58+
}
59+
)
60+
return 0
61+
62+
workspace = Workspace.open(args.target)
63+
if args.command == "project" and args.action == "status":
64+
_print(workspace.status(trusted=True))
65+
return 0
66+
if args.command == "project" and args.action == "validate":
67+
result = workspace.validate()
68+
_print(result)
69+
return 0 if result["valid"] else 2
70+
if args.command == "board":
71+
_print(getattr(workspace.model(), args.action)())
72+
return 0
73+
if args.command == "generate" and args.action == "run":
74+
result = workspace.generate()
75+
_print(result)
76+
return 0 if result["written"] else 2
77+
result = workspace.diff()
78+
_print(result)
79+
return 0 if result["up_to_date"] else 1
80+
81+
2482
def main(argv: list[str] | None = None) -> int:
2583
parser = argparse.ArgumentParser(prog="emblink-studio-core", description="EmbLink Studio Core")
2684
parser.add_argument(
@@ -30,11 +88,34 @@ def main(argv: list[str] | None = None) -> int:
3088
)
3189
commands = parser.add_subparsers(dest="command", metavar="command")
3290
commands.add_parser("serve", help="serve JSON-RPC 2.0 on standard input and output")
91+
92+
project = commands.add_parser("project", help="a board's status and validation")
93+
project.add_argument("action", choices=["status", "validate"])
94+
project.add_argument("target", metavar="BOARD", help="a board directory of an RTOS checkout")
95+
board = commands.add_parser("board", help="the boards of a checkout, and a board's model")
96+
board.add_argument("action", choices=["list", "describe", "pins", "clocks", "memory"])
97+
board.add_argument(
98+
"target", metavar="BOARD_OR_RTOS", help="the checkout for list, a board directory otherwise"
99+
)
100+
generate = commands.add_parser(
101+
"generate", help="run the generator, or see what it would change"
102+
)
103+
generate.add_argument("action", choices=["run", "diff"])
104+
generate.add_argument("target", metavar="BOARD", help="a board directory of an RTOS checkout")
33105
args = parser.parse_args(argv)
34106

35107
if args.command == "serve":
36108
from .server import serve
37109

38110
return serve()
39-
parser.print_help()
40-
return 2
111+
if args.command is None:
112+
parser.print_help()
113+
return 2
114+
115+
from .errors import CoreError
116+
117+
try:
118+
return _run(args)
119+
except CoreError as exc:
120+
print(exc.message, file=sys.stderr)
121+
return 1
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# SPDX-License-Identifier: Apache-2.0
2+
# Copyright 2026 Junior Deogracias
3+
#
4+
# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS.
5+
# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root.
6+
#
7+
# File: diagnostics.py
8+
# Author: Junior Deogracias
9+
# Created: 2026-11-12
10+
"""The generator's diagnostics, as structured records the views can link to a file.
11+
12+
emb-hwgen 0.x writes one diagnostic per line (the RTOS's rule HW-002):
13+
14+
boards/st/nucleo_f446re/board.yaml:25: pins.usart2.tx: PA2 af9 is not usart2_tx
15+
warning: soc/st/stm32f4/stm32f4.yaml:17: cpu.mpu: the cortex_m port does not use the MPU yet
16+
17+
that is, an optional 'warning: ', then the file (relative to the checkout, or absolute
18+
for a board outside it), the line, the node's path in the YAML ('(root)' for the
19+
document) and the message. Each becomes
20+
21+
{"severity", "message", "file", "line", "path", "source"}
22+
23+
with the file made absolute, so a view opens it at the line. Lines that are not
24+
diagnostics (the generator's own summary) are dropped; a line in no known form is
25+
kept as a diagnostic with only its message, so nothing the generator says is lost.
26+
When the generator writes JSON diagnostics (asked of the RTOS for S1), they are read
27+
instead and this parser stays for older checkouts.
28+
"""
29+
30+
from __future__ import annotations
31+
32+
import re
33+
from pathlib import Path
34+
from typing import Any
35+
36+
SOURCE = "emb-hwgen"
37+
_LOCATED = re.compile(r"^(?P<file>.+?):(?P<line>\d+): (?P<rest>.*)$")
38+
_PATH = re.compile(r"^(?P<path>[^\s:]+): (?P<message>.+)$")
39+
40+
41+
def parse(text: str, root: Path) -> list[dict[str, Any]]:
42+
"""The diagnostics in emb-hwgen's output `text`; relative files are under `root`."""
43+
out: list[dict[str, Any]] = []
44+
for raw in text.splitlines():
45+
line = raw.strip()
46+
if not line or line.startswith("emb-hwgen"):
47+
continue # blank, or the generator's summary ('emb-hwgen: 8 error(s)')
48+
severity = "error"
49+
if line.startswith("warning: "):
50+
severity = "warning"
51+
line = line[len("warning: ") :]
52+
diagnostic: dict[str, Any] = {"severity": severity, "source": SOURCE}
53+
located = _LOCATED.match(line)
54+
if located is None:
55+
diagnostic["message"] = line
56+
out.append(diagnostic)
57+
continue
58+
file = Path(located["file"])
59+
diagnostic["file"] = str(file if file.is_absolute() else root / file)
60+
diagnostic["line"] = int(located["line"])
61+
rest = located["rest"]
62+
with_path = _PATH.match(rest)
63+
if with_path is not None:
64+
diagnostic["path"] = with_path["path"]
65+
diagnostic["message"] = with_path["message"]
66+
else:
67+
diagnostic["message"] = rest
68+
out.append(diagnostic)
69+
return out
70+
71+
72+
def counts(diagnostics: list[dict[str, Any]]) -> dict[str, int]:
73+
return {
74+
"errors": sum(1 for d in diagnostics if d["severity"] == "error"),
75+
"warnings": sum(1 for d in diagnostics if d["severity"] == "warning"),
76+
}
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# SPDX-License-Identifier: Apache-2.0
2+
# Copyright 2026 Junior Deogracias
3+
#
4+
# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS.
5+
# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root.
6+
#
7+
# File: errors.py
8+
# Author: Junior Deogracias
9+
# Created: 2026-11-12
10+
"""The core's error, shared by the server, the command line and the project code.
11+
12+
A CoreError carries one of the protocol's error codes (spec section 5, Errors), a
13+
message written for the person, and optional data: the output of the tool that
14+
failed and, where it applies, the file and line. The server answers it as a JSON-RPC
15+
error; the command line prints its message and exits with 1.
16+
"""
17+
18+
from __future__ import annotations
19+
20+
from typing import Any
21+
22+
23+
class CoreError(Exception):
24+
def __init__(self, code: int, message: str, data: Any = None) -> None:
25+
super().__init__(message)
26+
self.code = code
27+
self.message = message
28+
self.data = data

0 commit comments

Comments
 (0)