Phase 6: Native Executables implementieren und Change archivieren
This commit is contained in:
145
docs/native-executables.md
Normal file
145
docs/native-executables.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# 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
|
||||
über den Callback prüfen. `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.
|
||||
Reference in New Issue
Block a user