# 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.
