Ausführbare Dateien

Vertrag für Programme, die mit clau -o oder einem Projekt-Build erstellt werden. Positionelle Eingaben oder genau ein ausgewähltes Projektziel werden zum -o-Pfad gelinkt; ein Projekt-Build linkt jedes ausgewählte ausführbare Ziel zu seinem output im Manifest (Linken, Projekte).

Auswahl des Einstiegspunkts

Der Einstiegspunkt ist eine exportierte Funktion der Stelligkeit 1, die die Argumentliste erhält.

• FUNCTION ist standardmäßig main. Namen sind Atomtext ohne Anführungszeichen: 1–255 Unicode-Skalare, gültiges UTF-8, keine Steuerzeichen und kein :. Andere Schreibweisen sind Aufruffehler (CLI, Exit 2) oder Manifest-Fehler (Exit 1).
• entry ist ein optionaler Schlüssel des Schemas 1; ältere Manifeste bleiben gültig. Das gesamte Manifest wird dekodiert, daher scheitert ein fehlerhaftes entry auch in nicht ausgewählten Zielen.
• Das CLI---entry überschreibt den Manifest-Schlüssel und verlangt genau ein ausgewähltes Ziel. Es steht im Konflikt mit Prüf-/Ausgabeaktionen und --new-project; diese Aktionen ignorieren entry im Manifest (wie sie output ignorieren).
• Ein expliziter Einstiegspunkt wird in jedem kompilierenden Modus (Standard, --emit, IR-/Typinspektion) zusammen mit den gewöhnlichen semantischen Diagnosen validiert.

Für Projektziele nennt der Hinweis auch den Manifest-Schlüssel: ... --entry MODULE[:FUNCTION] or with entry = "MODULE[:FUNCTION]" in this target's [[targets]] table of the project manifest ..., zum Beispiel:

[[targets]]
name = "app"
sources = ["src/*.erl"]
entry = "app:start"   # calls app:start/1; plain "app" calls app:main/1

Argumente

Entry(Argv) erhält eine echte Liste von Strings (Listen von Unicode-Codepoints), ohne den Programmnamen und die führenden Runtime-Optionen, sonst unverändert und in Reihenfolge, wie bei escript.

• POSIX: Die Bytes jedes Arguments werden als UTF-8 dekodiert; ein Byte, das keine gültige Sequenz beginnt, wird zum Codepoint dieses Bytes (Latin-1-Rückfall).
• Windows: der breite (UTF-16-)Argumentvektor der CRT, aufgeteilt nach denselben Regeln wie argv; ein ungepaartes Surrogat wird zu U+FFFD.
• Keine weitere Optionsauswertung, kein Globbing und keine Expansion von Umgebungsvariablen findet in der Runtime statt.

Runtime-Optionen

Die Runtime liest ihre Optionen aus der Umgebungsvariable CLAUSE_FLAGS (Wörter getrennt an Leerzeichen und Tabs, kein Quoting) und dann aus den führenden Befehlszeilenargumenten, sodass die Befehlszeile gewinnt. Beide werden gleich ausgewertet; ein Wert steht im nächsten Argument oder nach =.

Auf der Befehlszeile endet die Auswertung beim ersten Argument, das keine Runtime-Option ist, sodass prog data --max-atoms 9 alle drei Argumente an das Programm übergibt. In CLAUSE_FLAGS muss jedes Wort eine Runtime-Option sein. Ein ungültiger Wert, ein Wort in der Variable, das keine Option ist, oder --args-file stoppt das Programm, bevor irgendein Modul registriert ist: clau: runtime failure: <reason>, Exit 70. Prozessanzahlen sind nicht begrenzt, und Speicher ist standardmäßig unbegrenzt. Byte-Werte sind dezimal ohne Suffixe und werden auf ganze Wörter abgerundet; ein Programm, das eine Obergrenze erreicht, scheitert mit resource_limit, Exit 70 (Speichergrenze der Runtime).

Exit-Status

Ungültige Argumente von halt/1 lösen im Aufrufer badarg aus. Endet der Einstiegspunkt, beendet sich das Programm: Andere Prozesse werden gestoppt, ohne weiterzulaufen, wie bei halt/1 von OTP nach der Rückkehr von escript. Ein Halt in einem beliebigen Prozess beendet das Programm mit dessen Status, und ein Runtime-Fehler in einem beliebigen Prozess beendet es mit 70; eine Ausnahme in einem gestarteten Prozess beendet nur diesen Prozess (Prozesse).

halt/0,1, error/1,2,3, exit/1 und throw/1 sind mit oder ohne Präfix erlang: aufrufbar; eine lokale Definition oder -compile({no_auto_import, ...}) hält den unqualifizierten Namen lokal, wie in OTP. halt/2 ist nicht verfügbar. halt(N) behält die unteren 31 Bits jeder nichtnegativen Ganzzahl, wie OTP. Ein Slogan ist eine echte Liste von höchstens 1.023 Unicode-Codepoints. Ein Halt wickelt den Einstiegspunkt wie ein Fehler über den geprüften Fehlerkanal ab, sodass er das Programm erst nach dem erzeugten Aufräumen stoppt.

Ausgabeströme

• stdout: Ausgabe von standard_io (io:format/1,2, io:put_chars/1, erlang:display/1). Gepuffert; geleert auf jedem Exit-Pfad außer abort.
• stderr: der Bericht über nicht abgefangene Ausnahmen, Ausgabe von standard_error, Runtime-Fehler und die Fehlerberichte anderer Prozesse, die abstürzen (Prozesse).
• Der Bericht ist eine Zeile uncaught exception <class>: <reason in ~w form>, später gefolgt von Stack-Frames (step 15). Sein genauer Text ist keine stabile Schnittstelle; Tests matchen ihn über Muster.

Startobjekt

Kompilieren mit einem expliziten Einstiegspunkt (--entry oder entry im Manifest) fügt nach den Modulen des Batches ein Startmodul hinzu. Mit --emit wird es als clausev1_start.{obj,o,ll,bc} neben den Modulartefakten veröffentlicht (der Name kann nicht mit einem Modulartefakt kollidieren). Es enthält einen konstanten abi::v1::StartupDescriptor (startup.hpp): ABI-Revision, Term-Breite, jeden Moduldeskriptor in Quelltextreihenfolge, die Schreibweisen von Einstiegsmodul und -funktion sowie ein escript-Flag. Sein int main(int, char **) ruft CLAUSE_main_v1 der Runtime auf, das:

1. Startdeskriptor und jeden Moduldeskriptor auf ABI-Revision und Breite prüft, bevor irgendetwas registriert wird; eine Abweichung endet mit 70.
2. Die Runtime startet und alle Module registriert; jeder Fehler stoppt vor dem Einstiegspunkt und verwirft die Runtime (Exit 70), sodass kein Erlang-Code gegen einen unvollständigen Batch läuft.
3. Den Einstiegsprozess erzeugt, argv aufbaut und den Aufruf von M:F/1 als Hauptprozess einreiht, ihn dann zusammen mit jedem Prozess, den er startet, auf dem kooperativen Executor (Prozesse) ausführt, bis er endet.
4. Das Ergebnis auf den obigen Exit-Status abbildet, Berichte nach dem Leeren von stdout ausgibt, dann jeden Prozess freigibt und die Runtime auf jedem Pfad herunterfährt (außer halt(abort)).

clau -o linkt diese Objekte selbst (Linken). Manuelles Linken (das Rezept für das native Harness ohne Harness-Quelltext):

& $tool --emit obj --entry app --artifact-dir build/app app.erl helper.erl
clang-cl /MT build/app/*.obj build/debug/lib/clause_runtime.lib /Fe:app.exe

Jedes Clang-kompatible Linken der Objekte mit Clause::generated_program funktioniert genauso (siehe tests/compiler/linking/startup.cmake).

Linken

clau [-O0|-O2|-Os] -o PATH a.erl b.erl ... (oder --project FILE [--target T] -o PATH für ein ausgewähltes Ziel) kompiliert den Batch im Speicher, fügt das Startobjekt für den Einstiegspunkt hinzu und linkt eine ausführbare Datei:

clau -O2 -o build/demo examples/compile/answer.erl examples/compile/client.erl
./build/demo          # build/demo.exe on Windows

-Os legt zusätzlich jede erzeugte und jede Runtime-Funktion und jedes Datenobjekt in einen eigenen Abschnitt und linkt mit --gc-sections (ELF), -dead_strip (Mach-O) oder /OPT:REF /OPT:ICF (MSVC), sodass Code, den kein Einstiegspfad erreicht, entfernt wird.

• PATH ist relativ zum Aufruf. Für Windows-Ziele wird .exe angehängt, wenn der Dateiname keine Erweiterung hat. Sein Verzeichnis muss existieren.
• Linker: --linker PATH (ein Pfad oder Programmname), sonst clang++ oder clang aus PATH, dann (Windows) %ProgramFiles%/LLVM/bin. Er läuft als <clang> --driver-mode=g++ --target=<triple> -o <staged> <objects> <runtime>, sodass Clang den Plattform-Linker und die C/C++-Runtime-Bibliotheken wählt (unter Windows findet es MSVC und das SDK selbst; keine Entwickler-Shell nötig).
• Runtime: --runtime-library PATH, sonst das Archiv clause_runtime des Builds, der clau erzeugt hat (Pfad relativ zur ausführbaren Datei gespeichert, z. B. bin/../lib/clause_runtime.lib). Jedes native Objekt im Archiv muss zu Architektur und Objektformat des Ziels passen; --target-triple für ein anderes Ziel braucht daher eine dafür gebaute Runtime.
• Objekte und die ausführbare Datei werden in einem privaten Verzeichnis .clause-link-* neben der Ausgabe bereitgestellt, das danach entfernt wird. Die Ausgabe wird erst nach einem erfolgreichen Linken ersetzt, sodass jeder Fehler eine vorhandene Datei unverändert lässt. Die Ausgabe darf kein Verzeichnis sein und keine Eingabe überdecken.
• Linker-Warnungen werden an stderr weitergereicht; --linker und --runtime-library verlangen --output oder einen linkenden Projekt-Build.
• Projekt-Builds ohne -o linken jedes ausgewählte Ziel, das output oder entry hat, zu seiner Ausgabe im Manifest, legen fehlende Verzeichnisse an und ersetzen die Ausgaben erst, nachdem alle ausgewählten Ziele gelinkt wurden (Projekte).

Escripts

Eine Quelldatei, deren erste Zeile mit #! beginnt, wird als escript kompiliert, in jedem Modus und mit jedem Dateinamen (positionelle Eingaben oder .erl-Dateien eines Projekts). Die Regeln folgen escript aus OTP 29 für Quelltext-Skripte:

• Die #!-Zeile wird ignoriert. Ein optionaler Kommentar in Zeile 2 und eine Emulator-Zeile %%! (Zeile 2 oder Zeile 3 nach dem Kommentar) sind Kommentare; %%!-Argumente können nicht auf kompilierten Code angewendet werden und erzeugen eine Warnung.
• Ist die erste Form nicht -module(...), heißt das Modul <file name with '.' replaced by '_'>__escript (?MODULE eingeschlossen). OTP fügt einen Zeitstempel/eindeutigen Suffix hinzu; Clause hält den Namen deterministisch. Die synthetisierte Deklaration belegt Zeile 1, sodass spätere Zeilennummern unverändert bleiben.
• main/1 ist erforderlich (escript does not define main/1) und implizit exportiert; andere Funktionen folgen den normalen Exportregeln.
• -mode(compile | interpret | debug | native) wird akzeptiert und ignoriert; andere Werte sind Fehler. Außerhalb von escripts bleibt -mode nicht unterstützt.
• Einstiegspunkt: Ohne --entry ist das einzige escript im Batch der Einstiegspunkt (es gewinnt gegenüber Modulen, die main/1 exportieren); mehrere escripts sind mehrdeutig.
• Exit-Status wie bei escript von OTP: Eine Ausnahme, die den escript-Einstiegspunkt verlässt, endet mit 127 und escript: exception <class>: <reason> auf stderr; die übrigen Zeilen der Exit-Status-Tabelle gelten unverändert.
• Dateien ohne #! sind gewöhnliche Module. (OTPs escript file.erl würde ihre erste Zeile überspringen; Clause tut das nicht.) Vorkompilierte Beam- und Archiv-escripts werden nicht unterstützt.

Vergleich mit OTP

Goldens für Programm-Fixtures führen den Einstiegspunkt unter OTP mit denselben Regeln aus (Orakel); dasselbe Orakel erzeugt die Golden-Fälle für ausführbare Dateien, die der End-to-End-Runner unter jeder Policy linkt und ausführt. Unterschiede zu escript für gewöhnliche Module: Nicht abgefangene Ausnahmen enden mit 1 statt 127, und main/1 muss exportiert sein. Escript-Quelltexte behalten die Regeln von OTP (siehe oben).