Code Editing, Build, Terminal and Documents

What This Chapter Covers

This chapter covers the general development tools rather than the model editors: how to edit, build, and run the C, C++, and Rust sources in the project's code folder, how to use the integrated terminal, and how to use the Markdown document editor for the doc folder.

• Intended readers: developers who write and build application code inside PAIO
• Prerequisite: a workspace and a project are open
• If you edit and build on a remote target (SSH, container, or WSL), read 17. Remote Development (SSH, Dev Container, WSL) alongside this chapter.

16.1 The Code Editor (C / C++ / Rust)

16.1.1 Which Files Open Here

Double-click a file in the Explorer and the extension decides which editor opens.

Language	Extensions	Status bar
C	.c, .h	C
C++	.cpp, .hpp, .cc, .cxx, .hh, .hxx	C++
Rust	.rs	Rust

The code editor applies only under the code and doc folders. A file with the same extension in any other location opens in the XML editor. In a remote workspace this folder restriction does not apply, and the extension alone decides.

If a file does not appear in the Explorer, a per-folder display filter is hiding it (see 4.4). Besides the source extensions, the code folder also shows CMakeLists.txt, Makefile, Cargo.toml, and Cargo.lock by name, and it always hides the target folder.

16.1.2 Layout and Shortcuts

The PROBLEMS panel sits below the edit area; drag the divider between them to change the split. When a build starts, an Output panel appears below that. The status bar shows the cursor position (Ln 1, Col 1 — click it to open the go-to-line dialog), the encoding, and the file language. Line endings are always saved as LF.

main.c from the code folder is open. Line numbers, folding markers, and a minimap at the top right are visible, and an orange squiggle runs under "calculator.h" on line 2. PROBLEMS at the bottom is collapsed and reports only the count, 1, and the status bar at the very bottom shows Ln 1, Col 1, UTF-8, and C.

Shortcut	Action
Ctrl+B	Build — compiles the current file only (16.2.1)
Ctrl+F5	Build & Run — detects the project type, then builds and runs
Ctrl+S	Save
Shift+Alt+F	Format the document
Alt+O	Switch between header and source
Ctrl + click	Go to definition. Without a language server, it follows the #include "..." path

Ctrl+B behaves differently depending on where the focus is. Inside the code editor it runs Build; outside the code editor it collapses and expands the Explorer panel on the left.

16.1.3 Language Servers (LSP)

Completion, hover, go to definition, find references, signature help, and formatting are all provided by language servers. C and C++ use clangd and Rust uses rust-analyzer, and both ship with the app, so you do not install them separately. If the bundled binary is missing, PAIO looks for one installed on the system.

• Rename (F2) and quick fixes are not provided.
• C files offer 23 code snippets and C++ files offer 45, listed after the other completion items. Rust has no snippets.
• clangd works from the project root, so place compile_commands.json in the project root.

When completion and diagnostics quietly stop working. The ⚠ in the status bar appears only when the language server process exits with an error (click it to open a dialog with a Restart action). When the server never starts at all — no binary in the bundle or on the system, or no cargo inside the container — nothing is shown. If the features do not work and there is no indicator, suspect this case first.

code/Cargo.toml is generated automatically and overwritten. When you open a code file, PAIO scans for .rs files under code and regenerates Cargo.toml. Opening a C file does the same. Dependencies you add to this file by hand therefore disappear the next time you open a code file. Keep a hand-managed Cargo project in a subfolder rather than directly under code.

16.1.4 The PROBLEMS Panel

This is the diagnostics list, grouped by file. Each entry shows a severity badge (Error, Warning, Info, or Hint) with the file, line number, and message; click an entry to jump to that location (a different file opens in a new tab). The number badge in the header is the sum of errors and warnings, and No problems found appears when there are no diagnostics. The scope is everything under the code folder that contains the current file.

The 1 from the previous figure is expanded. Entries are grouped by file name (main.c — 1 warning), and the row below it holds the severity badge, the file, the position (2:11), and the message. What is caught here is the #include letter-case warning described just below. Cargo.toml and Cargo.lock appear in the Explorer because they were generated automatically when a code file was opened (16.1.3).

Compiler errors do not arrive here. PROBLEMS collects only language server diagnostics and the results of the #include letter-case check. Errors from gcc, g++, cmake, and cargo appear only as underlines in the edit area and in the Output panel. Compiler diagnostics are also not filtered per file, so when you build several files, an error from another file can appear on the same line number in the current file.

The #include letter-case check. If the file name in #include "..." differs from the actual file only in letter case, a warning is attached, because the include opens on Windows but breaks the build on Linux.

Include case mismatch: "calculator.h" should be "Calculator.h" (will fail on Linux)

The Problems tab in the bottom utility panel is unrelated to code diagnostics. It always shows the same fixed text.

16.1.5 Saving and External Changes

Press Ctrl+S to save. If the write fails, the dirty marker stays.

The code editor does not protect unsaved edits. When an open file changes on disk (a remote build script, a git checkout, and so on), it is replaced with the disk contents without a confirmation and the dirty marker is cleared. This differs from the model editors, so save first before touching a file from outside.

16.2 Build and Run

16.2.1 Build and Build & Run Are Different

Ctrl+B (Build) does not build the project. It compiles only the file that is currently open with gcc or g++. It does not look for CMakeLists.txt or Cargo.toml even when they exist, and it calls gcc on .rs files too, which fails. The project-level build is Ctrl+F5 (Build & Run).

Both actions save first when there are unsaved edits, then build.

16.2.2 The Order Build & Run Uses to Detect a Project

Starting from the folder that holds the current file, PAIO walks upward and checks each condition in order, stopping at the first match.

Order	Condition	Action
1	A CMakeLists.txt exists above	CMake configure + build (does not run)
2	A Cargo.toml exists above	cargo run
3	Neither exists and the file is .rs	Prints a message only
4	Anything else (a single .c / .cpp file)	Compiles, then runs

The CMake path builds only and does not run the executable. Run it yourself from the terminal when you need to.

16.2.3 Commands Executed and Their Output

Path	Command
Single file (C)	gcc -Wall -g <file> -o <output>
Single file (C++)	g++ -Wall -g -std=c++17 <file> -o <output>
CMake	cmake -S <root> -B <root>/build -DCMAKE_BUILD_TYPE=Debug, then cmake --build
Cargo	cargo run --manifest-path <root>/Cargo.toml

The build type is fixed to Debug. Run a release build yourself from the terminal.

When a build starts, the Output panel opens, clears the previous output, and streams the result in real time (standard error in red). The first line is the command that ran, and the last is Process exited with code <number>. When the run step is reached, the program output is appended.

The Output panel after pressing Ctrl+F5 in main.rs, which built and ran through the Cargo path. The package name is paio-code because Cargo.toml was generated automatically (16.1.3), and the build used the dev profile, which is the fixed Debug type described above.

• There is no button to cancel a build in progress. A remote build is killed at 120 seconds and a local single-file compile is cut off at 60 seconds, but local CMake and Cargo builds have no limit, so you have to clean them up from the terminal.
• In a remote state the commands run in that environment (container, SSH, or WSL). Note that a workspace opened with Connect to WSL builds inside the distribution, but the run step is handled with host paths and can fail. In that case, run the executable yourself from the terminal.

16.2.4 The Toolchain Used

The Rust toolchain, CMake, and gcc ship with the app, so builds work without a separate installation. PAIO uses a bundled tool first and falls back to the tool on the system PATH when there is none. Which tool is actually used can differ depending on what your installation includes.

When no compiler is found at all, a remote build also prints an installation hint. A local build shows the error from the shell as-is.

Hint: 'gcc' was not found in this environment. Install a C/C++ toolchain (e.g. 'sudo apt install build-essential' on Debian/Ubuntu).

16.3 The Integrated Terminal

16.3.1 Opening and Operating It

Press Ctrl+` or Ctrl+J to open the terminal panel (if no terminal exists, one is created). The terminal button at the left of the status bar only toggles the panel; it does not create a terminal. Right-click a project node and choose Open in Terminal to open a terminal in that project folder (this menu item exists on project nodes only).

The right side of the panel header holds font size controls and actions to add, split, and kill a terminal and to close the panel. The terminal list is in the sidebar on the right of the panel; click an entry to switch to it. Closing the last terminal hides the panel automatically.

A terminal is open at the bottom. The powershell C:\Dev\PA… entry in the right sidebar points to the one open terminal, and the working directory is set to the project folder. cargo runs immediately even though it was never installed separately, because the bundled toolchain is prepended to PATH (16.3.3).

Input	Action
Tab	Passed to the shell's completion
Ctrl+C	Copies when there is a selection; otherwise sends an interrupt to the shell
Ctrl+V / right-click	Paste (right-click copies when there is a selection)

Split Terminal does not split the view in place. Switch to another terminal in the sidebar and come back, and the two terminals appear side by side.

16.3.2 Which Shell Opens

The shell is decided from the working directory and the remote connection state, stopping at the first matching condition.

Order	Condition	Shell that opens
1	A shell was specified directly (New WSL Terminal and so on)	The one specified
2	Connected to a container	The shell inside the container
3	Connected over SSH	The remote SSH shell
4	The working directory is a WSL path (Windows)	That distribution
5	Anything else	The local shell

The default local shell is PowerShell on Windows and the SHELL environment variable on macOS and Linux (zsh and bash respectively when it is not set).

16.3.3 The Bundled Toolchain and PATH

When a terminal starts, the bundled toolchain paths are prepended to PATH, so you can type cargo, cmake, and gcc directly in a local terminal.

This applies to local terminals only. Container shells and WSL shells use their own environment's PATH, and it does not apply to SSH shells at all. Build tools for remote targets are deployed separately and covered in 17.6.

16.4 The Markdown Document Editor

16.4.1 Editing and Preview

Open a .md or .markdown file in the doc folder and the editor and a live preview open side by side. The toolbar inserts bold, italic, strikethrough, headings, inline code, and lists, and the three buttons on the right switch the view mode (editor only, split, or preview only).

The middle of the three view modes, split view. The table and inline code written on the left are rendered as-is on the right, and the ```mermaid code block is drawn as a flowchart — diagrams are covered in 16.4.2.

Shortcut	Action
Ctrl+S	Save (an untitled document opens the save dialog)
Ctrl+T	Open an untitled Markdown document in a new tab
Ctrl+O	Choose a file and open it in a new tab

The Ctrl+B and Ctrl+I shown in the toolbar tooltips do not work in this editor. Bold and italic are applied with the toolbar buttons only. The three keys in the table above are the only ones that work.

Drag the divider between the two panes to change the split. Scrolling is synchronized in both directions in split view only. Relative image paths resolve against the folder that holds the document.

16.4.2 Diagrams

Set a code block's language to one of the names below and the preview draws it as a diagram. All four are always enabled and there is no setting to turn them off. Typing @ or < inside such a code block brings up completion.

Language	Tool
mermaid	Mermaid (built in)
drawio	Draw.io (built in)
zenuml	ZenUML (built in)
plantuml	PlantUML — requires an internet connection

Only PlantUML renders through an external server, so on failure PlantUML Load Error or PlantUML Network Error appears in its place. When one tool fails, the others still render.

16.5 Other Viewers and Editors

File	Editor that opens	Main features
.md, .markdown (under doc)	Markdown editor	16.4
.html, .htm (under doc)	HTML preview	Back, Forward, Reload
.png .jpg .jpeg .gif .svg .webp .bmp	Image viewer	Ctrl + wheel to zoom (0.1x to 10x), fit to view
.txt	Text editor	Ctrl+S to save
.arxml, .xml, everything else	XML editor	See 05. UI Layout and Navigation