54 lines
5.9 KiB
Markdown
54 lines
5.9 KiB
Markdown
# pcode-bibliotheken Specification
|
|
|
|
## Purpose
|
|
|
|
Ermöglicht die quellfreie Wiederverwendung übersetzter BASIC-Module als portable TBL-Bibliotheken und deren Verknüpfung zu vollständigen Programmen für dieselbe TBVM.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: Portables TBL-Bibliotheksformat
|
|
`tbc build --library` und Make Library SHALL eine `.tbl` mit übersetzten BASIC-Modulen, exportierten Deklarationen, typisierten Imports sowie den benötigten Daten und Forms-Ressourcen erzeugen. Sie SHALL ohne ihre ursprünglichen BAS-/FRM-/Include-Quellen weiterverwendbar sein. Das Format SHALL versioniert und unabhängig von Windows/Linux/macOS sowie amd64/arm64 sein. Native Runtime und plattformspezifischer Maschinencode MUST NOT Bestandteil der TBL sein; die native Runtime SHALL im Ziel-`tbrt` liegen.
|
|
|
|
#### Scenario: Bibliothek auf einem anderen Ziel verwenden
|
|
- **WHEN** dieselben TBL-Bytes mit kompatiblen Terminal-Basic-Versionen für die vier Releaseziele verknüpft werden
|
|
- **THEN** liefern die Programme bei gleichen Eingaben dieselben BASIC-Ergebnisse ohne Neubau der Bibliothek aus Quellen
|
|
|
|
### Requirement: Gemeinsamer Linkbefehl
|
|
`tbc link` SHALL ein Hauptprojekt und angegebene TBL-Bibliotheken zu einem vollständig aufgelösten TBC-Programm verbinden. Mit `--exe` SHALL derselbe Befehl dieses Programm in die passende vorgebaute `tbrt`-Vorlage einbetten und ein natives eigenständiges Executable erzeugen. `tbc build`, `run` und `check` SHALL bei Projekten mit TBL-Verweisen dieselbe Auflösung verwenden. Erzeugen und Linken SHALL ohne C-/Rust-Compiler oder nativen Linker beim Anwender möglich sein; dokumentierte Systemvoraussetzungen zur EXE-Finalisierung bleiben anwendbar.
|
|
|
|
#### Scenario: Quellfreie Bibliotheksnutzung bis zur EXE
|
|
- **WHEN** nach dem TBL-Bau deren Quellen entfernt werden und ein Verbraucherprojekt über `tbc link --exe` verknüpft wird
|
|
- **THEN** läuft das Executable anschließend ohne separate TBL/TBC, separat installiertes tbrt/tb/tbc oder Buildtoolchain mit dem korrekten Bibliotheksverhalten
|
|
|
|
### Requirement: Explizite Bibliothekszuordnung
|
|
TBL-Dateien SHALL als geordnete MAK-Einträge relativ zur Projektdatei mit der bestehenden DOS-großschreibungsunabhängigen Pfadauflösung verwendbar sein. `tbc link` SHALL zusätzliche TBL-Eingaben ausdrücklich annehmen. Bibliotheksmodule SHALL ihre Identität und Deklarationen behalten; ein TBL-Eintrag MUST NOT als editierbare Quelltextdatei oder als Startdatei interpretiert werden. Externe Bibliotheksabhängigkeiten SHALL aus den angegebenen Eingaben aufgelöst werden; fehlende Abhängigkeiten MUST vor Programmausgabe diagnostiziert werden.
|
|
|
|
#### Scenario: Projekt mit verschobener Bibliothek
|
|
- **WHEN** ein Projekt und seine relativ referenzierte TBL gemeinsam in ein anderes Verzeichnis verschoben werden
|
|
- **THEN** bleibt das Projekt ohne Bibliotheksquellen verknüpfbar; fehlt stattdessen die TBL, nennt die Diagnose die fehlende Datei und ihren Projektbezug
|
|
|
|
### Requirement: Eindeutige und typgeprüfte Verknüpfung
|
|
Der Linkpfad SHALL Imports eindeutig mit kompatiblen Exporten verbinden und die bestehenden Regeln für Namen, Konstanten, UDTs, COMMON sowie Prozedursignaturen erhalten. Fehlende Definitionen, mehrdeutige Exporte, inkompatible Parameter-/Ergebnistypen, doppelte Modulidentitäten und überschrittene Formatgrenzen SHALL vor Programmausführung mit konkretem Bezug abgewiesen werden. Bibliotheken SHALL typisierte offene Imports speichern können; ein ausführbares Endprodukt MUST NOT unaufgelöste Imports enthalten.
|
|
|
|
#### Scenario: Bibliothek benötigt eine weitere Bibliothek
|
|
- **WHEN** Bibliothek A eine typisierte Prozedur aus B importiert und nur A zum Verbraucher angegeben wird
|
|
- **THEN** scheitert das Linken mit dem fehlenden Symbol; nach Hinzufügen eines signaturkompatiblen B funktioniert der Aufruf, während ein inkompatibles B eine Typdiagnose auslöst
|
|
|
|
#### Scenario: Mehrdeutiges Symbol
|
|
- **WHEN** zwei eingebundene Module einen nach bestehenden Sprachregeln mehrdeutigen Export anbieten
|
|
- **THEN** meldet der Linker den Namenskonflikt mit beiden Herkunftsmodulen und wählt keine zufällige Definition
|
|
|
|
### Requirement: Erhaltene BASIC- und Laufzeitsemantik
|
|
Verknüpfte Bibliotheksmodule SHALL dieselben Wert-, BYREF-/BYVAL-, Array-, UDT-, COMMON-, DATA-/RESTORE-, Forms- und Fehlerregeln wie entsprechende Quellmodule erfüllen. Globale Anfangswerte SHALL vor Ausführung bereitstehen; Modulrümpfe SHALL in der dokumentierten erweiterten Projektreihenfolge mit demselben Kontrollfluss wie die entsprechenden Quellmodule ausgeführt werden; bloße Symbolverweise SHALL keine zusätzliche Modulinitialisierung auslösen. Die Startauswahl SHALL dem Hauptprojekt gehören. RUN ohne Ziel SHALL auch den Bibliothekszustand neu initialisieren. Physische Fehlerorte und BASIC-Zeilenlabels SHALL trotz fehlender Bibliotheksquellen erhalten bleiben.
|
|
|
|
#### Scenario: Quellmodule durch TBL ersetzen
|
|
- **WHEN** Bibliotheksmodule eines Projekts durch ihre TBL in derselben Modulreihenfolge ersetzt und direkte sowie verknüpfte Variante mit gleichen Ereignissen gestartet werden
|
|
- **THEN** stimmen Initialisierung, BYREF-Änderungen, strukturierte Werte, Forms-Ereignisse und Fehlerorte überein; nach RUN besitzen beide denselben frischen Anfangszustand
|
|
|
|
### Requirement: Validierung und geschützte Ausgabe
|
|
TBL-Lader und Linker SHALL Format-/P-Code-/Runtime-Kompatibilität, Grenzen und alle Tabellen-/Symbolverweise prüfen. Beschädigte oder inkompatible Bibliotheken SHALL kontrolliert abgewiesen werden. Fehler, Abbruch oder Ausgabekonflikte SHALL bestehende Ausgaben und sämtliche Eingaben einschließlich Bibliotheken erhalten. Erfolg SHALL erst nach vollständiger validierter Veröffentlichung gemeldet werden.
|
|
|
|
#### Scenario: Beschädigter Container oder Ausgabe auf Eingabe
|
|
- **WHEN** eine abgeschnittene TBL geladen wird oder das Linkziel eine der Eingabebibliotheken überschreiben würde
|
|
- **THEN** scheitert der Vorgang mit konkreter Diagnose, führt keinen BASIC-Code aus und erhält bestehende Eingaben und Ausgaben
|