Bibliotheksmodule

Clause liefert eigene Versionen der OTP-Module, die Programme aufrufen, in Erlang nach dem dokumentierten Verhalten von OTP geschrieben (nicht aus OTP-Quelltexten kopiert) über Builtins der Runtime, und kompiliert sie mit den Programmen, die sie verwenden.

Inhalt

Jedes bereitgestellte Modul exportiert die vollständige Liste von OTP 29 für seinen Namen; sein Inventar <module>.terms (Dateien) hält fest, welche Funktionen implementiert und welche Stubs sind.

Ergebnisse und Fehlergründe entsprechen OTP 29, einschließlich der Fehlerformen der Erlang-Implementierungen von OTP (lists:map(F, x) ergibt {case_clause, x}, lists:nth(0, L) function_clause, lists:seq(1, 10, 0) badarg) und seiner BIFs (lists:member/2, lists:keyfind/3, lists:reverse/2, die maps-Funktionen: badarg, {badmap, M}, {badkey, K}). lists:member/2 vergleicht mit =:=, lists:keyfind/3 mit ==. lists:sort/1 ist ein stabiles Runtime-Builtin (Vergleich und Ordnung). Stacktraces nennen die Bibliotheksfunktionen, nicht die von OTP.

Interaktive Shell

shell:start_interactive/0,1 startet die Erlang-Shell auf den Standardströmen, und clau --shell linkt sie in eine ausführbare Datei, deren Einstiegspunkt sie ist, sofern --entry keinen anderen nennt (Kompilierung). Der Prozess clause_shell übernimmt die Rolle von user_drv in OTP: Er gibt die Systemversion aus, startet den Server von shell und startet einen neuen, wenn eine Shell endet (exit().). Der Server liest jeden Befehl über den Standardeingabeserver von io, wobei die Eingabeaufforderung für jede weitere Zeile eines Befehls erneut ausgegeben wird, behält den Verlauf und startet den Auswerter, der jeden Ausdruck mit erl_lint prüft, records expandiert und ihn mit erl_eval auswertet. Ergebnisse werden mit den records der Shell über den Pretty Printer der Runtime ausgegeben (clause_io_lib:pretty/2, io_lib). Das Eingabeende beendet das Programm nach *** Terminating erlang (nonode@nohost) mit Status 0.

Befehle rufen Module über ihren Namen auf, daher muss ein Programm, das die Shell startet, jeden Export aufrufbar halten: --shell behält sie bei (Erreichbarkeit von Exporten) und linkt jedes Bibliotheksmodul; ein ohne diese Option gebautes Programm erreicht nur die Module, die es nennt. Eingabezeilen werden so gelesen, wie das Terminal sie liefert, und vom Terminal selbst bearbeitet: Es gibt keine edlin- Zeilenbearbeitung, Verlaufstasten oder Tab-Vervollständigung (Unterschiede).

Wie Programme sie erhalten

• Nennt ein Batch (positionelle Eingaben oder ein Projektziel) ein Modul mit einem literalen Atom — M:F(...) mit literalem M, fun M:F/A, apply(M, F, Args) mit literalem M, -behaviour(M) oder -import(M, ...) —, das keine Eingabe definiert, sucht der Compiler M.erl in den Anwendungsverzeichnissen der Bibliothek, dann in den source_search_paths des Projekts (Projekte), parst und kompiliert die erste gefundene Datei in den Batch und wiederholt das für die Module, die die hinzugefügten Dateien nennen (zu welchem Modul ein Name aufgelöst wird). Ein Aufruf M:F(...) eines Katalog-Builtins (io:format/2, os:type/0) nennt kein Modul. --print-inputs listet die Eingaben auf, die dadurch hinzukommen.
• Die Bibliothek ist library/ des Build-Baums, relativ zu clau gefunden wie das Runtime-Archiv, mit einem Verzeichnis pro OTP-Anwendung (erts, kernel, stdlib), danach library-asn1/ des Build-Baums mit den Modulen, die der Build aus den ASN.1-Spezifikationen der Bibliothek erzeugt (public_key). -include_lib("kernel/include/logger.hrl"), file.hrl, eep48.hrl und inet.hrl (#hostent{}) werden zu den eigenen Headern der Bibliothek aufgelöst, sofern das Projekt keine Anwendung kernel nennt; stdlib/include/ zip.hrl, qlc.hrl, ms_transform.hrl (nennt die Transformation, die auf dem Host-OTP läuft: Transformationen) und assert.hrl, sofern es keine Anwendung stdlib nennt. assert.hrl hat die Makros, Fehlerterme und Schalter NOASSERT, NODEBUG, ASSERT von OTP. Die internen Header von OTP (erl_bits.hrl, erl_compile.hrl) und die für Verteilung (dist.hrl, dist_util.hrl, net_address.hrl) werden nicht bereitgestellt, ebenso wenig inet_sctp.hrl (kein SCTP).
• Ein Modul des Batches mit demselben Namen ersetzt das Bibliotheksmodul, mit einer Warnung; Katalog-Builtins dieses Namens gewinnen weiterhin (Registrierung).
• Bibliotheksmodule sind gewöhnliche Batch-Module: Sie werden in ausführbare Dateien gelinkt und erzeugen bei Objekt- oder IR-Ausgabe eigene Artefakte. Sie sind Erlang-Code, daher geben sie wie anderer Code ab.
• Ein Modul, das nur über Laufzeitnamen erreicht wird (M:F(...) mit M als Variable), wird nicht hinzugefügt: Ein solcher Aufruf löst undef aus, sofern nicht etwas anderes das Modul nennt.

Ersatz für Runtime-Module

Clause vertritt die OTP-Module, die ERTS in C implementiert (NIFs, BIFs, Port-Treiber, die vorgeladenen Module von erts/preloaded/src), sowie Module, die OTP beim Bauen erzeugt (unicode_util). kernel und stdlib von OTP sind reines Erlang, rufen aber diese Module auf.

Bereitgestellt oder fehlend

Was die Runtime braucht und nicht in reinem Erlang geschrieben werden kann, wird pro Modul entschieden, und pro Funktionsgruppe, wo ein Modul Belange mischt:

• Bereitgestellt (provided): Clause liefert das Modul mit der exakten Exportliste von OTP 29. Jede Funktion hat einen von vier Status: implemented (ein Runtime-Builtin oder ein Erlang-Rumpf über vorhandenen Runtime-Diensten), refused (gibt zurück oder löst aus, was Aufrufer in OTP bereits behandeln, wenn ein Feature fehlt, etwa {error, enotsup}), stub (löst error({not_implemented, F, A}) mit M:F/A oben auf dem Stack aus, wie es die erlang-Stubs tun; noch nicht umgesetzt) oder declined (ein Stub, der bleibt, mit einem Grund wie Distribution oder Laden von Code). Ein neues Modul beginnt mit jeder Funktion als Stub, sodass es auffindbar ist und seine Aufrufer kompilieren; Gruppen wechseln dann in ihren entschiedenen Status.
• Builtin-Platzhalter: Eine von einem Katalog-Builtin implementierte Funktion behält ihren Export und den Rumpf F(_, ...) -> clause_builtin_placeholder., der nie ausgeführt wird: Die Registrierung bindet stattdessen das Builtin, und ein qualifizierter Aufruf M:F(...) wird zur Brücke kompiliert. Nur ein unqualifizierter Aufruf im Modul würde den Platzhalter erreichen, daher ruft das Modul seine eigenen Builtins qualifiziert auf; library_inventory weist Platzhalter ohne zugehöriges Katalog-Builtin, als not_implemented-Stub verbliebene Katalog-Builtins und unqualifizierte Aufrufe eines Platzhalters zurück.
• Fehlend (missing): Clause liefert gar kein Modul, womöglich für immer, und hält fest, warum und welche höheren Clause-Module den Platz seiner Aufrufer einnehmen (library/modules.terms). Die niedrigen Datei- und Socket-Schichten prim_* (prim_file, prim_buffer, prim_socket, prim_net, prim_inet, socket_registry) sowie socket sind die fehlenden Module: Programme verwenden stattdessen file, gen_tcp, gen_udp, inet und net von Clause, und weil Clause-Module gegenüber denen von OTP gewinnen (siehe unten), gelangen die Aufrufer eines fehlenden Moduls aus OTP (gen_tcp_socket, inet_tcp, ... von OTP) nie in einen Batch. Ein fehlendes Modul erhält nie einen Stub, daher ist eine Referenz darauf ein Fehler zur Kompilierzeit, nie eine Überraschung zur Laufzeit.

Funktionen, die für die Runtime trivial sind, werden ohne eigene Entscheidung implementiert.

Zu welchem Modul ein Name aufgelöst wird

OTP ist auf dem Rechner des Nutzers optional; ist es vorhanden, darf es nicht ändern, was ein Build kompiliert. Ein Modulname wird in dieser Reihenfolge aufgelöst:

1. Explizite Eingaben: Quellen, die der Nutzer aufführt (sources, source_dirs, positionelle Eingaben). Eine, die den Namen eines Clause-Moduls trägt, ersetzt es, mit einer Warnung, die beide Dateien nennt.
2. Clause-Module: die Bibliotheksmodule, bereitgestellte Ersatzmodule eingeschlossen.
3. source_search_paths, wie unter Projekte beschrieben.

Der Name eines fehlenden Moduls ist reserviert: Eine gleichnamige Datei auf einem Suchpfad (zum Beispiel erts/preloaded/src/prim_file.erl von OTP) wird nicht verwendet, und die Diagnose sagt, dass Clause das Modul nicht bereitstellt. Eine explizite Eingabe darf es dennoch bereitstellen, mit der Ersetzungswarnung.

ignore_modules gilt auch für Clause-Module: Ein ignoriertes Clause-Modul fehlt im Batch, und eine explizite Eingabe kann es dann ohne Warnung bereitstellen, da nichts ersetzt wird.

Dateien

• Bibliotheksmodule liegen in library/<application>/, benannt nach der OTP-Anwendung, der das Modul in OTP gehört: erts (Gegenstücke der vorgeladenen Module und erlang), kernel, stdlib. Die privaten Hilfsmodule von Clause (clause_socket, clause_re, clause_unicode, clause_zlib, clause_receive, clause_maps, clause_hashed, clause_array, clause_features, clause_io_lib, clause_disk_log, clause_dets) liegen neben den Modulen, denen sie dienen. Die Suche in der Bibliothek durchsucht jedes Anwendungsverzeichnis; ein Modulname existiert in höchstens einem davon.
• library/modules.terms listet jedes Modul auf, über das Clause entscheidet: {Module, Application, provided}. oder {Module, Application, missing, "reason"}. Der Compiler liest es, um zu wissen, welche Namen Clause-Module und welche reserviert sind.
• Jedes bereitgestellte Modul hat daneben ein Inventar <module>.terms: {Name, Arity, Group, Status}. pro Export von OTP 29, sortiert nach Name und Stelligkeit, wobei Group die Entscheidungsgruppe nennt (zum Beispiel stdlib, distribution, beam). erlang.terms behält sein eigenes Format ({Name, Arity, Flags, Status}, Modul erlang).
• Exportlisten werden an einem OTP 29 des Hosts beobachtet (M:module_info(exports)); kein OTP-Quelltext wird kopiert. Ergebnisse und Fehlerterme implementierter Funktionen entsprechen OTP 29; bewusste Abweichungen stehen unter Unterschiede.

Dokumentierte Funktionen

library/documented.terms listet die öffentlichen Funktionen auf, die OTP 29 für erts, kernel, stdlib, crypto und public_key dokumentiert: {Module, Application, Name, Arity}. pro Funktion, deren Modul- und Funktionsdokumentation nicht verborgen ist und die nicht veraltet ist, beobachtet aus den Doc-Chunks des Host-OTP durch tests/compiler/library/observe_docs.escript (explizit auszuführen). Undokumentierte Exporte bleiben in den Inventaren, dürfen aber Stubs bleiben.

• library_inventory prüft, dass jede dokumentierte Funktion eines bereitgestellten Moduls in dessen Inventar steht und kein Stub ist, ausgenommen Module, die library_modules.py als teilweise implementiert mit dem abschließenden Plan-Step aufführt.
• python tests/compiler/library/library_modules.py coverage . gibt für jedes dokumentierte Modul die Anzahl implementierter und dokumentierter Funktionen aus.

Typen

Weil Clause-Module gegenüber denen von OTP gewinnen, muss OTP-Code, der in seinen Specs file:filename() oder erlang:time_unit() nennt, diese Typen in den Clause-Modulen finden. Jedes bereitgestellte Modul, dessen Gegenstück in OTP Typen exportiert, bindet <module>.types.hrl aus seinem eigenen Verzeichnis ein: die Liste -export_type, dann die exportierten Typen und die lokalen Typen und Records, die sie verwenden, so wie OTP sie definiert (die Dokumentation zeigt dieselben Definitionen; die installierte Dokumentation enthält keine Typdefinitionen, daher stammen sie aus der Implementierung: den Debug-Informationen der Beam-Datei oder dem mitgelieferten Quelltext eines vorgeladenen Moduls wie erlang). escript tests/compiler/library/observe_types.escript LIBRARY APP MODULE schreibt den Header aus dem OTP des Hosts, und --check vergleicht seine Formen mit einer frischen Beobachtung (CTest library_freshness); library_modules.py check verlangt, dass jedes Modul seinen Header einbindet. Typen, die die Header aus Modulen außerhalb des Programms nennen (unicode:chardata(), calendar:datetime()), und die breiten Unions von OTP (file:posix() hat mehr Glieder, als der Typgraph behält) werden ohne Warnung zu term() aufgelöst: Die Diagnosen gehören zur Bibliothek von Clause, nicht zum Programm des Nutzers.

Kernel-Dienste beim Start

file, io und code von OTP rufen registrierte Server auf (file_server_2, code_server, den I/O-Server eines Group Leaders), die die Anwendung kernel beim Booten startet. Eine ausführbare Datei von Clause startet keinen davon: file und io von Clause brauchen keinen Server, logger von Clause startet seinen Server beim ersten Gebrauch, und ein OTP-Modul, das einen braucht, scheitert so, wie es unter OTP ohne diesen Server scheitert (noproc). OTP-Code, der zur Laufzeit code aufruft, funktioniert daher nicht. Das Booten der ganzen Anwendung kernel ist nicht geplant.

Anwendungen

• Spezifikationen stammen aus dem Programm, nicht aus einem Code-Pfad: clau kompiliert jede *.app und *.app.src neben den Quellen des Batches, jede *.app im danebenliegenden Verzeichnis ebin und ebin/Name.app oder src/Name.app.src jedes Eintrags in [targets.options.applications] in das erzeugte Modul clause_applications, das immer hinzugefügt wird, wenn der Batch application_controller enthält. Die erste Datei eines Anwendungsnamens gewinnt. Eine Ressource, die keine Module auflistet, erhält die danebenliegenden Module des Batches. Diagnosen verweisen in die Ressourcendatei.
• application:load/1 akzeptiert auch Terme {application, Name, Keys}. Ein Name ohne Ressource ergibt {error, {"no such file or directory", "Name.app"}}, wie OTP bei einer fehlenden Datei antwortet.
• kernel (11.0.4) und stdlib (8.1) sind von Anfang an geladen und laufen, wie OTP 29.1.1 sie auflistet, ohne Anwendungsmaster; kernel hat die Standardumgebung seiner kernel.app.
• Eine Anwendung mit einem Startmodul erhält einen Master, der die Gruppe ihrer Prozesse führt (sodass get_application/0, get_env/1 und start_type/0 darin antworten), ihre I/O-Anfragen an die Standard-I/O weiterleitet und beim Stoppen prep_stop/1 ausführt, den obersten Prozess herunterfährt, stop/1 ausführt und den Rest der Gruppe beendet. Eine permanente Anwendung, die endet, oder eine transiente, die abnormal endet, hält das Programm mit der Meldung von OTP und Exit-Status 1 an.
• logger und clause_logger erreichen application über einen Laufzeitnamen, daher linken es nur Programme, die application verwenden.

Ledger

Der Projektplan sieht jedes dokumentierte Modul von erts, kernel und stdlib vor; echte Programme (zuerst luerl) setzen die Prioritäten. Es kompilieren und ausführen, jeden Fehler klassifizieren (unknown module, undefined function M:F/A, nicht unterstützte Syntax oder Features, anderes) und jeden einem Plan-Step, einem anderen Backlog-Eintrag oder einer festgehaltenen Ablehnung zuordnen. Ist das stderr des Laufs in einer Datei gespeichert, gibt python tests/compiler/library/library_modules.py report FILE die Klassifikation als Tabellen aus: jedes unbekannte Modul mit seiner Fehleranzahl, aufrufenden Modulen und aufgerufenen Funktionen mit Stelligkeiten; undefinierte Funktionen nach Modul; andere Meldungen mit ihren Anzahlen.

Werkzeuge

Alle liegen in tests/compiler/library/:

• escript observe_module.escript LIBRARY APP MODULE schreibt LIBRARY/APP/MODULE.terms aus MODULE:module_info(exports) des OTP des Hosts und behält dabei Gruppe und Status jedes bereits vorhandenen Eintrags; ein neuer Export beginnt als {Name, Arity, default, stub}.
• python library_modules.py generate LIBRARY APP MODULE schreibt die Moduldatei einmalig, jeder Export ein Stub; danach wird die Datei von Hand bearbeitet.
• python library_modules.py check ROOT (CTest library_inventory, ohne OTP) meldet jede Unstimmigkeit: ein bereitgestelltes Modul ohne seine Dateien, ein fehlendes Modul mit einer Datei, ein Inventar, das nicht als bereitgestellt aufgeführt ist, ein Export, der nicht im Inventar steht, oder umgekehrt, ein stub/declined-Eintrag, der kein not_implemented-Stub ist, ein implemented/refused-Eintrag ohne Rumpf oder Katalog-Builtin. library_rejects belegt das an einer absichtlich inkonsistenten Fixture-Bibliothek.
• CTest library_freshness (Labels host_otp, full_only) beobachtet jedes Inventar neu und verlangt, dass es unverändert ist, und beobachtet, erzeugt, prüft und kompiliert dann ein neues Modul von Anfang bis Ende. library_report führt clau auf einem Fixture-Programm aus und prüft die Zeilen des Berichts.