undoStudio Released · v0.1

The IDE of the undoRT ecosystem. It edits what st2cpp compiles and what undoPLC runs: IEC 61131-3 Structured Text with the colouring and the completion lists driven by what the file actually declares, a project described in JSON, and Compile one button away from the transpiler.

Overview

undoStudio owns the application lifecycle, the window, the ImGui framework and the project on disk. It implements no domain functionality: everything else is an undoApp, an independent module built as a shared object and loaded from plugins/. The split is the architecture, not a convenience — an undoApp that has to be linked into the executable cannot be shipped on its own.

• One editor panel for every kind of file: .st, .json, .cpp, plain text
• Structured Text parsed as it is edited: semantic colouring from the symbol table, not from a keyword list
• Member, statement and signature completion, all driven by the parsed file
• Ctrl+Click from an identifier to its declaration, across files
• One POU in two panes — Variables above Body, with the splitter remembered per workspace
• Method tabs on a FUNCTION_BLOCK, added and removed from the tab itself
• A project is JSON: project.json, plcs.json, tasks.json, one file per task
• A role-aware tree: the context menu knows whether it is on a POU folder, a PLC or a task
• Diagnostics reported against the generated file, through the source map back to the editor that owns the line
• An embedded terminal — one shell per tab, on a real pty
• Recent projects and recent files, remembered between runs, in Ctrl+R and Ctrl+P
• Every feature is a plugin: a third party can add a panel without touching the core

Installation

Download the archive

Grab the latest release from GitHub Releases:

tar -xzf undoStudio-<version>-linux-x86_64.tar.gz
cd undoStudio-<version>
./undoStudio

What is in the archive:

The X11 and OpenGL development libraries GLFW builds against, and glm, still have to be on the machine; they are in the README under “System packages”.

Build from source

Every dependency is a git submodule, and two of them are undoRT forks — the ImGuiColorTextEdit branch that carries the semantic tokens, and st2cpp itself:

git clone --recursive https://github.com/undoRT/undoStudio.git
cd undoStudio

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"

# the transpiler the Compile button shells out to
cmake -S third_party/st2cpp -B build/st2cpp -DCMAKE_BUILD_TYPE=Release
cmake --build build/st2cpp -j"$(nproc)"

The binary, the core library and the undoApps are written next to resources/, because that is the directory the IDE resolves them against. The intermediates go to build/ — -B decides where those go, not where the build puts anything it has to find again.

The Window

Four panels, all listed under View, all shown or hidden from there:

View > Reset Layout puts them back where the shipped layout has them, and the terminal — an undoApp panel like any other — appears when its plugin is there.

The Editor Panel

undoStudio has one editor panel. A Structured Text file, a JSON file, a C++ file and a plain text file all open in it, each in its own tab, above the same tab bar. A document on screen is a document on screen whichever extension it has.

The tab bar

A file that is not on screen is not kept in memory as text on disk: its unsaved contents are stashed, and the stash is handed back when the tab is selected again — at the cursor and the pane division it was left at.

Which backend a file gets

Structured Text

The ST backend edits IEC 61131-3 Structured Text — POUs, variable sections, methods, structs and enums — with the file parsed, so the colouring, the outline and the completion lists all come from what the file declares rather than from a list of keywords.

The two panes

The upper pane holds the variable sections — VAR, VAR_INPUT, VAR_OUTPUT, VAR_IN_OUT, VAR_EXTERNAL, VAR_GLOBAL, VAR_TEMP — and the lower one the cyclic code. Where the splitter sits is remembered per workspace.

Methods

A FUNCTION_BLOCK has method tabs beside the POU tab; PROGRAM and FUNCTION do not, because they have no methods in ST. Tabs can be dragged to reorder them.

• + adds a method, asking for its name and its return type
• right-click a method tab for Delete Method, with a confirmation
• Add Method in a file's context menu does the same thing
• saving and compiling serialize every tab of the POU, not only the one on screen

Semantic colouring

Identifiers are coloured by what they resolve to — a declared variable, a function, a type, a keyword — using the symbol table st2cpp builds. A name that resolves to nothing is left uncoloured, which is how a typo shows up before it is compiled.

The toolbar

Autocomplete & Signature Help

Three lists, plus signature help and declaration jumps, all driven by the parsed file — so what they offer is what the file actually declares.

Without a . the identifier being typed is the prefix, so a half-typed variable or method name is completable too; neither list opens inside a comment or a string literal, where a name cannot be completed anyway. Only one list is ever on screen: a statement list answers about the same word a member list would, and the more specific one wins.

Tab opens the parameter picker for the call being written, and the name and type of the parameter being filled in are shown in grey at the caret. ↑ ↓ move, PageUp PageDown move a page, Enter accepts, Esc dismisses.

Ctrl+Click on an identifier jumps to where it is declared, across files. The status line says so while the mouse is over it, and a click on something that is not declared is reported in the ST Output panel rather than doing nothing.

JSON: Text or Tree

A .json file gets one of two backends: text, which you can edit, or the tree viewer, which you can only look at. Which one it gets is the file's role, not its extension — answered from the project that is open.

A project's own configuration would go to the viewer by extension, and the viewer draws a tree and has nothing to type into. Those are the files the user is told to edit by hand — exports.json holds the PROGRAM order, a task file its cycle time — so they open as text. Every other .json gets the tree, and outside a project there are no configuration files, so a .json there is a tree.

Right-click any .json in the Workspace tree for Open as Text and Open as Tree. Both replace the tab rather than adding a second one: one file is one row in the bar, and the row is whichever view it is in.

Keyboard

Ctrl+R and Ctrl+P are held off while anything owns the keyboard — a code editor, the terminal — because in there the same two keys mean something else entirely, and stealing them would break the program the user is in.

The Workspace Tree

The two toolbars

What the context menu offers

Delete is not on the keyboard: removing a file is not something a stray keypress should do. Dragging a file onto a folder moves it there, and the rename follows the tab, the save path and the recent files entry with it.

Projects on Disk

A project is a directory with a .undoProject/ descriptor in it:

myProject/
|-- .undoProject/
|   |-- project.json          name, version, author, target, semantics
|   |-- plcs.json             the PLCs
|   `-- tasks.json            the task list
|-- undoCore/
|   |-- tasks/                one JSON file per task
|   `-- ...                   the core sources
|-- undoLogic/
|   `-- <plc>/
|       `-- exports.json      the PROGRAM order of that PLC
`-- ...

The tree is built from the roles in plcs.json and the shape of the directory rather than from names alone: undoLogic/<plc>/exports.json is the PLC's exports file because the PLC is in the list, not because of what it is called. A project with no plcs.json has no PLC, and its exports file is an ordinary .json.

A folder can also be opened as a workspace with no project in it — Select Workspace. The tree is flat rather than role-aware, the folder menu offers the generic items, and every .json in it is a tree.

Recent Projects & Files

A file is remembered however it was reached — clicked in the tree, opened from the menu, dropped onto the window — and opening it puts it back where it was, at the cursor and the pane it was left in. The list is ordered by when a file was last looked at, and an entry follows a rename or a move.

Both lists read and write the same max key in the same [recent] section: there is nothing useful to configure separately about how much of two lists of the same kind to remember. Changing it through either list trims the other on the next load.

State Between Runs

Four files are written next to the layout. They are yours, they are not tracked, and deleting any of them puts that part of the setup back to its default.

They sit in the working directory, which is why an installed copy has to be started from the directory holding resources/ and plugins/. They are the IDE's state and not the project's: nothing in a project reads them, so deleting them costs nothing but a layout.

Compiling & ST Output

Compile on the ST toolbar hands the project to st2cpp, which is a separate command-line binary built from third_party/st2cpp. The Editor looks for it on PATH first and then at build/st2cpp/st2cpp, and prints the path it used at the top of the panel. A missing transpiler is reported plainly and nothing else stops working.

Validate parses and analyses without generating.

undoApps

A plugin is a shared object exporting two C symbols. createUndoApp is expected to have fully initialised the app — registering its panels and all — before it returns, and destroyUndoApp to have removed them again:

extern "C" {

void* createUndoApp()
{
    auto& app = MyApp::getInstance();
    app.initialize();   // registers the panels
    return &app;
}

void destroyUndoApp(void* app)
{
    static_cast<MyApp*>(app)->shutdown();   // removes them
}

} // extern "C"

Registering a panel by a name another undoApp already registered replaces that one's callback rather than adding a second panel, so the load order decides which body is drawn. The core cannot call into an undoApp: it leaves a request and the undoApp picks it up, which is what the add-METHOD dialog and both recent-files lists live by.

The ones that are meant to

Each is described by what it is for rather than what it does, because none of them exists yet.

Terminal

A libvterm terminal drawn with ImGui, each tab running a real shell on a pty.

Testing

Three suites, all headless: no GPU and no display. They create an ImGui context with a font atlas and drive real frames.

./src/core/tests/run_tests.sh                    # 12 tests
./undoApps/undoApp.Editor/tests/run_tests.sh     # 26 tests
./undoApps/undoApp.Terminal/tests/run_tests.sh   # 2 tests

# a subset, by name
./undoApps/undoApp.Editor/tests/run_tests.sh completion

Each check that could not fail would not be a check, so every one of them found a real bug: a fuzzy match stealing the member completion, 1841 cells in 1920 painted the wrong colour, a key written above its own section header, and a row in the recent-files popup that rendered in the right order, in the right place, with the right name on it, and could not be picked because its ID belonged to another row.

The Editor and Terminal suites link against the built core and need the project compiled first. They run on every release build, which is why the archive is only ever attached to a release somebody deliberately made.