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
9 changes: 6 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
<!-- SPDX-License-Identifier: Apache-2.0 -->
# EmbLink Studio

The IDE made for EmbLinkRTOS: a native Qt 6 desktop application (`app/`) in front of
EmbLink Studio Core, a Python engine (`core/`) that it talks to over JSON-RPC 2.0 on stdio.
Stage S0 (setup) of the specification: the application starts the core, initializes it,
The development system for EmbLinkRTOS: EmbLink Studio Core, a Python engine (`core/`) that
configures, builds, flashes and debugs, and a native Qt 6 desktop (`app/`) that makes it visible.
They talk JSON-RPC 2.0 over stdio.

Stage S0 (setup) of the [specification](docs/specification.md): the application starts the core, initializes it,
shows its log, and offers a restart if it stops.

## Build and test
Expand All @@ -30,6 +32,7 @@ found; set `EMBLINK_STUDIO_CORE` to an installed `emblink-studio-core` to use th
| `app/` | The Qt application and its tests |
| `core/` | EmbLink Studio Core: `emblink-studio-core serve` |
| `protocol/` | JSON Schemas of every method's parameters and result |
| `docs/` | The [specification](docs/specification.md) and the [development guide](docs/development.md) |
| `third_party/components.json` | Every third-party component and its licence |
| `tools/notices.py` | Checks those licences and writes the notices list for the About box |

Expand Down
4 changes: 2 additions & 2 deletions app/src/mainwindow.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
*
* @details
* Builds the status label, the restart button, the "Core log" dock (a QDockWidget
* until the docking framework is decided, spec section 11 question 1) and the File,
* until Qt Advanced Docking System lands, spec section 11 question 1) and the File,
* View and Help menus. The About dialog shows the third-party notices bundled as the
* :/NOTICES.md resource. The core is started when the window is built and stopped
* when it closes.
Expand Down Expand Up @@ -55,7 +55,7 @@ MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent)
layout->addStretch();
setCentralWidget(central);

// QDockWidget until the docking framework is decided (spec section 11, question 1).
// QDockWidget until Qt Advanced Docking System lands (decided: spec section 11, question 1).
auto *dock = new QDockWidget(tr("Core log"), this);
dock->setObjectName(QStringLiteral("coreLog"));
m_log = new QPlainTextEdit(dock);
Expand Down
20 changes: 20 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
<!-- SPDX-License-Identifier: Apache-2.0 -->
# EmbLink Studio documentation

| Document | What it holds | Read it when |
| --- | --- | --- |
| [Specification](specification.md) | What EmbLink Studio is, the decisions taken, the architecture, the core's JSON-RPC interface, the project format, the views, the stages S0 to S9 and the engineering rules | You want to know what to build, in what order, and why |
| [Development](development.md) | Setting up a machine and an editor, the build and test commands, and how a change reaches `main` | You are about to change the code |
| [Protocol schemas](../protocol/README.md) | One JSON Schema per method's parameters and result | You change a method of the core's interface |
| [Contributing](../CONTRIBUTING.md) | The CLA and the DCO, the file header, formatting and licence rules | Before your first pull request |

## The specification is the source of truth

When the code says "spec section 5" or "§11 q4", it means [specification.md](specification.md), section 5 or
question 4 of section 11. The specification is changed by pull request and agreed with the owner. A decision
is added to §2 with its date, and a pull request that changes behaviour updates the specification with it.

## Where the project stands

Stage S0 (setup) is done: the application starts the core, initializes it, shows its log and offers a restart
if it stops. CI builds and tests it on Windows, Linux and macOS. S1, the core's foundation, is next (§8).
62 changes: 62 additions & 0 deletions docs/development.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
<!-- SPDX-License-Identifier: Apache-2.0 -->
# Development

How to set up a machine, build and test EmbLink Studio, and get a change into `main`.

## What you need

CMake 3.21 or later, Ninja, Qt 6.8 or later, Python 3.11 or later, and clang-format 18 for C++ formatting
(`pip install clang-format==18.1.8` gives the version CI runs). On macOS, Homebrew's `qt`, `cmake`, `ninja` and
`python` are enough.

## Build and test

```sh
cmake --preset dev # set CMAKE_PREFIX_PATH to your Qt if CMake can't find it
cmake --build --preset dev
ctest --preset dev # Qt tests, against the real core and fake ones

python3 -m venv core/.venv && core/.venv/bin/pip install -e "core[dev]"
core/.venv/bin/pytest core # the core's tests, including the protocol schemas
core/.venv/bin/ruff check . && core/.venv/bin/ruff format --check .
```

Run the application: `build/dev/app/EmbLinkStudio.app/Contents/MacOS/EmbLinkStudio` on macOS,
`build/dev/app/EmbLinkStudio` elsewhere. It runs the core from `core/src` with the Python CMake found; set
`EMBLINK_STUDIO_CORE` to an installed `emblink-studio-core` to use that instead.

## The editor

The repository's [`.clangd`](../.clangd) points clangd at `build/dev/compile_commands.json`, so any
editor that uses clangd (VS Code with the clangd extension, Qt Creator, Neovim, Emacs) finds the Qt headers
and the build's flags. Run `cmake --preset dev` once first; until that file exists, the editor reports headers
as missing.
After the first configure, restart the language server (in VS Code: *clangd: Restart language server*).

`progress-screenshots/` is ignored by git: keep pictures of the application as it grows there, on your
machine only.

## How a change reaches `main`

`main` takes changes only through pull requests, and only when every CI check passes:

1. Create a branch from `main`.
2. Commit with `git commit -s`. The DCO check requires a `Signed-off-by` line that matches the commit's author.
3. Give every new source file the header shown in [CONTRIBUTING.md](../CONTRIBUTING.md).
4. Push the branch and open a pull request.
5. Wait for the 11 checks: the core on three systems and two Python versions, the application on three
systems, clang-format, and the DCO sign-off.
6. Merge with *Squash and merge* or *Rebase and merge*. Merge commits are off, so the history stays linear.

Release tags (`v*`) can only be created by the maintainers, and can never be moved or deleted.

## Where things are

| Path | What |
| --- | --- |
| `app/` | The Qt application and its tests |
| `core/` | EmbLink Studio Core: `emblink-studio-core serve` |
| `protocol/` | JSON Schemas of every method's parameters and result |
| `docs/` | The specification and this guide |
| `third_party/components.json` | Every third-party component and its licence |
| `tools/notices.py` | Checks those licences and writes the notices list for the About box |
Loading
Loading