149 lines
8.1 KiB
Markdown
149 lines
8.1 KiB
Markdown
# Native Terminalprogramme mit tbrt
|
|
|
|
`tbc build` erzeugt weiterhin `.tbc`. Für ein direkt startbares Programm:
|
|
|
|
```sh
|
|
tbc build projekt.mak --exe --target aarch64-apple-darwin \
|
|
--template /pfad/runtimes/aarch64-apple-darwin/tbrt -o meinprogramm
|
|
./meinprogramm erstes "zweites Argument"
|
|
```
|
|
|
|
`--exe` funktioniert für BAS, FRM, MAK und bereits kompilierte TBC-Projekte.
|
|
`-o`/`--output` bestimmt die Ausgabe; ohne Angabe wird die Quellendung unter
|
|
Windows durch `.exe` ersetzt, unter Linux/macOS entfernt. `--target` wählt
|
|
explizit ein Target, andernfalls gilt das unterstützte Host-Target.
|
|
Ohne `--template` wird neben `tbc` unter
|
|
`runtimes/<Target-Triple>/tbrt` beziehungsweise `tbrt.exe` gesucht.
|
|
Die zugehörige Datei `<Vorlage>.meta` ist erforderlich.
|
|
|
|
Vorhandene Ausgaben bleiben erhalten; `--force` erlaubt ihr ausdrückliches
|
|
Ersetzen. Quellen, Includes, Projektmanifest, Eingabekompilat und Vorlage
|
|
sind als Ausgaben geschützt. Unbekannte/doppelte Optionen und fehlende
|
|
Werte werden abgewiesen. Native Ausgabeoptionen benötigen `--exe`.
|
|
|
|
## Ziel- und Systemvoraussetzungen
|
|
|
|
| Ziel | Target-Triple | Vorlage | Finalisierung |
|
|
| --- | --- | --- | --- |
|
|
| Windows amd64 | `x86_64-pc-windows-msvc` | `tbrt.exe` | PE32+ Console; keine Finalisierungs-Toolchain |
|
|
| macOS arm64 | `aarch64-apple-darwin` | `tbrt` | macOS mit `/usr/bin/codesign`, Ad-hoc-Signatur und strikte Prüfung |
|
|
| Linux amd64 | `x86_64-unknown-linux-gnu` | `tbrt` | ELF64; keine Finalisierungs-Toolchain |
|
|
| Linux arm64 | `aarch64-unknown-linux-gnu` | `tbrt` | ELF64; keine Finalisierungs-Toolchain |
|
|
|
|
Erzeugung aus einer gelieferten Vorlage und Ausführung benötigen kein Rust,
|
|
Cargo, keinen C-Compiler und keinen nativen Linker. Der Export lädt keine
|
|
Vorlage herunter und startet keinen Cargo-Ersatzbuild. Ohne passende Vorlage,
|
|
Metadaten oder Finalisierungsvoraussetzung gibt es einen Fehler vor der
|
|
Veröffentlichung. macOS-Export ist deshalb auf macOS beschränkt; vorhandene
|
|
PE-/ELF-Vorlagen können auch auf anderen unterstützten Hosts verpackt werden.
|
|
|
|
Standalone enthält die native VM/Runtime und Terminal-/Forms-Unterstützung.
|
|
Das BASIC-Projekt bleibt P-Code. Systembibliotheken des jeweiligen Builders
|
|
bleiben Betriebssystemvoraussetzungen: Linux verwendet das GNU/glibc-Target,
|
|
Windows die MSVC-/Windows-Systembasis, macOS seine Systembibliotheken. Eine
|
|
konkrete Linux-Mindestversion wird erst mit dem realen Gitea-Builder-Image
|
|
in Change 06 festgelegt; beliebig alte Systeme sind nicht zugesichert.
|
|
Die lokale Ad-hoc-Signatur ersetzt keine Developer-ID-Notarisierung.
|
|
|
|
## Laufzeitvertrag
|
|
|
|
Die einzelne Ausgabedatei enthält Projekt, Forms-Anfangswerte und physische
|
|
Quellorte. Originalquellen, eine separate TBC-Datei und installiertes tb/tbc
|
|
werden zum Start nicht gebraucht. `COMMAND$` verbindet die übergebenen
|
|
Argumente wie `tbc run`. Terminal und Pipe benutzen denselben Runner wie
|
|
CLI: Pipe-Eingaben kommen von stdin, der abschließende Textsnapshot von
|
|
stdout; `LPRINT` erzeugt `LPT1.TXT` im Arbeitsverzeichnis.
|
|
|
|
Exitcodes: 0 bei normalem Ende, 3 bei STOP/Abbruch, 2 bei BASIC-Laufzeitfehlern,
|
|
1 bei Lade-/Bedienfehlern. Die leere Vorlage endet mit einem Ladefehler.
|
|
`RUN` ohne Namen lädt den eingebetteten Anfangsstand erneut; nach einem
|
|
externen RUN startet ein weiterer namenloser RUN das nun aktive Kompilat neu.
|
|
|
|
`tbrt` hat keinen BASIC-Quellcompiler. Benannte externe RUN-Ziele müssen
|
|
vorkompilierte `.tbc` sein, zum Beispiel `RUN "NEXT.TBC"`. Sie werden wie beim
|
|
CLI relativ zum aktiven Programm und ohne Beachtung der Dateinamen-Großschreibung
|
|
aufgelöst. Ohne Endung gilt weiterhin die bestehende Suchfolge BAS/FRM/MAK/TBC;
|
|
liegt dort eine Quelle statt eines Kompilats, benennt tbrt die fehlende
|
|
Vorkompilierung. Externe Dateien für RUN, OPEN, ISAM und SHELL werden nicht
|
|
mit eingebettet und müssen ausdrücklich mitgeliefert werden.
|
|
|
|
## Vorlagen bauen (Entwickler und Actions)
|
|
|
|
Auf einem für das jeweilige Rust-Target eingerichteten Builder:
|
|
|
|
```sh
|
|
python3 tests/support/build-runtime.py --target aarch64-apple-darwin \
|
|
--output dist/runtimes/aarch64-apple-darwin
|
|
```
|
|
|
|
Derselbe Aufruf gilt mit jedem Triple aus der Tabelle. Windows baut nur
|
|
amd64, macOS nur arm64, Linux beide Architekturen. Das Skript führt
|
|
`cargo build --locked --release --target <Triple> -p tb-runner --bin tbrt`
|
|
aus und lässt die native Header-/Architekturprüfung durch `tb-template`
|
|
die Metadaten schreiben. Es installiert keine Cross-Toolchain. Ein bereits
|
|
vorhandenes Ausgabeverzeichnis wird nicht verändert; bei einem Fehler wird
|
|
die neu angelegte Ausgabe entfernt. Gitea-Releasepakete folgen in Change 06
|
|
(Windows `.7z`, Linux/macOS `.tar.gz`).
|
|
|
|
Metadatenformat 1 bindet Target, Runtime-ABI 1, Paketversion, TBC-Version und
|
|
FNV-1a-64 der exakten Vorlagendatei. Zusätzlich trägt tbrt eine eingebundene
|
|
Runtime-/Format-/Target-Markierung. FNV erkennt Dateibeschädigung und
|
|
Verwechslung; es authentifiziert keine Herkunft. Vorlagen und Metadaten
|
|
werden zusammen aus demselben vertrauenswürdigen Release bezogen.
|
|
|
|
## Container und Export-API für Changes 03/04/06
|
|
|
|
`tb_export::export(Export { module, target, template, output, overwrite,
|
|
protected }, cancelled)` erhält den fertig verknüpften Projektstand, keine
|
|
IDE-Dokumenttypen. `protected` enthält insbesondere das Eingabemanifest;
|
|
Quell-/Include-Pfade aus dem Kompilat sowie Vorlage/Metadaten ergänzt der
|
|
Export selbst. Die IDE kann ihren bestehenden Abbruch-/Revisionszustand
|
|
vor der Veröffentlichung prüfen: `prepare_export` beziehungsweise
|
|
`prepare_publication` liefern ein fertiges `PreparedPublication`. Der
|
|
UI-Thread prüft Auftrag und Eingaben, bevor er dessen `publish` aufruft;
|
|
Drop verwirft das Staging. `publish` stellt denselben Schutz für TBL/Link
|
|
bereit: temporäre Geschwisterdatei, vollständige Finalisierung, sync,
|
|
Abbruch- und Zielkonfliktprüfung, danach Veröffentlichung. Ein neues Ziel
|
|
wird mit atomarem No-clobber angelegt. Ein vorhandenes Ziel wird nur nach
|
|
Freigabe und unverändertem Inhalt ersetzt. CLI-SIGINT/SIGTERM beziehungsweise
|
|
Windows-Ctrl+C/Break setzen den Abbruchzustand; temporäre Dateien werden
|
|
beim kontrollierten Fehlerpfad entfernt. Unabfangbares Prozessende wie
|
|
SIGKILL ist keine kontrollierte Abbruchbehandlung.
|
|
|
|
Nutzlastabschluss: 48 Bytes, Little Endian, `TBPCODE!`, Container-Version
|
|
(u32), Runtime-ABI (u32), TBC-Version (u32), Target-ID (u32), Offset (u64),
|
|
Länge (u64), FNV-1a-64 der Nutzlast (u64). Vor dem Start werden native
|
|
Architektur, Versionen, Grenzen, Prüfsumme und anschließend der bestehende
|
|
TBC-Ladervertrag geprüft. Fehler führen nicht zur Ausführung von Projektcode.
|
|
|
|
ELF/PE verwenden den Abschluss hinter der Nutzlast. PE-Vorlagen müssen
|
|
unsigniert sein; eine vorhandene Authenticode-Signatur wird ausdrücklich
|
|
abgewiesen, die optionale PE-Prüfsumme auf 0 gesetzt. Auf macOS wird die alte
|
|
Signatur vor dem Einbetten entfernt, `__LINKEDIT` um Nutzlast/Abschluss
|
|
erweitert und danach mit codesign neu signiert und strikt geprüft. Der
|
|
Lader findet den Abschluss vor dem durch `LC_CODE_SIGNATURE` ausgewiesenen
|
|
Signaturbereich einschließlich maximal 15 Nullbytes Ausrichtung; er nimmt
|
|
kein unveränderliches Dateiende an. Die fertige Datei wird erneut geladen,
|
|
bevor sie veröffentlicht wird. Apple beschreibt, dass Signieren das
|
|
Executable verändert und spätere Änderungen die Signatur ungültig machen:
|
|
[Code Signing In Depth](https://developer.apple.com/library/archive/technotes/tn2206/_index.html).
|
|
|
|
## Reproduzierbare lokale Abnahme
|
|
|
|
```sh
|
|
cargo build --locked --release -p tb-cli -p tb-runner -p tb-export
|
|
python3 tests/support/native-abnahme.py --target aarch64-apple-darwin
|
|
cargo test --locked --workspace
|
|
cargo clippy --locked --workspace --all-targets -- -D warnings
|
|
cargo fmt --all -- --check
|
|
```
|
|
|
|
Die native Probe vergleicht CLI und EXE für Konsole/COMMAND$/Eingaben/LPRINT,
|
|
RUN-Neustart, STOP, Fehler, Mehrmodul-/Include-/Dateieffekte, Forms und
|
|
externes TBC-RUN. Vor nativer Ausführung werden die Originalquellen entfernt;
|
|
PATH ist leer. macOS prüft jede Signatur. Unix-PTY prüft echte Terminaleingabe,
|
|
Abbruch und Wiederherstellung; zusätzliche Fälle prüfen Exportabbruch und
|
|
beschädigte Nutzlasten. Kopf-/Architekturtests für alle vier Targets sind
|
|
Formatnachweise; tatsächliche Windows-/Linux-Ausführung und deren
|
|
Terminalmatrix stehen in Changes 05/06 aus.
|