Modules de bibliothèque

Clause livre ses propres versions des modules d'OTP qu'appellent les programmes, écrites en Erlang d'après le comportement documenté d'OTP (et non copiées depuis les sources d'OTP) au-dessus des builtins du runtime, et les compile avec les programmes qui les utilisent.

Contenu

Chaque module fourni exporte la liste complète d'OTP 29 pour son nom ; son inventaire <module>.terms (fichiers) consigne quelles fonctions sont implémentées et lesquelles sont des bouchons (stubs).

Les résultats et les raisons d'erreur correspondent à OTP 29, y compris les formes d'erreur des implémentations Erlang d'OTP (lists:map(F, x) donne {case_clause, x}, lists:nth(0, L) function_clause, lists:seq(1, 10, 0) badarg) et de ses BIF (lists:member/2, lists:keyfind/3, lists:reverse/2, les fonctions maps : badarg, {badmap, M}, {badkey, K}). lists:member/2 compare avec =:=, lists:keyfind/3 avec ==. lists:sort/1 est un builtin stable du runtime (comparaison et ordre). Les traces de pile nomment les fonctions de la bibliothèque, pas celles d'OTP.

Shell interactif

shell:start_interactive/0,1 démarre le shell Erlang sur les flux standard, et clau --shell le lie dans un exécutable dont il est le point d'entrée sauf si --entry en nomme un autre (compilation). Le processus clause_shell tient la place du user_drv d'OTP : il affiche la version du système, démarre le serveur de shell et en démarre un nouveau lorsqu'un shell se termine (exit().). Le serveur lit chaque commande via le serveur d'entrée standard d'io, en réaffichant l'invite pour chaque ligne supplémentaire d'une commande, conserve l'historique et démarre l'évaluateur, qui vérifie chaque expression avec erl_lint, développe les records et l'évalue avec erl_eval. Les résultats s'affichent avec les records du shell via le moteur d'affichage formaté du runtime (clause_io_lib:pretty/2, io_lib). La fin de l'entrée termine le programme avec le code 0 après *** Terminating erlang (nonode@nohost).

Les commandes appellent les modules par leur nom, donc un programme démarrant le shell a besoin que chaque export soit appelable : --shell les conserve (exports conservés) et lie chaque module de bibliothèque ; un programme compilé sans cette option n'atteint que les modules qu'il nomme. Les lignes d'entrée sont lues telles que le terminal les fournit, éditées par le terminal lui-même : il n'y a ni édition de ligne edlin, ni touches d'historique, ni complétion par tabulation (différences).

Comment les programmes les obtiennent

• Lorsqu'un lot (entrées positionnelles ou une cible de projet) nomme un module avec un atome littéral — M:F(...) avec M littéral, fun M:F/A, apply(M, F, Args) avec M littéral, -behaviour(M) ou -import(M, ...) — qu'aucune entrée ne définit, le compilateur cherche M.erl dans les répertoires d'applications de la bibliothèque, puis dans les source_search_paths du projet (projets), analyse et compile le premier trouvé dans le lot, puis recommence pour les modules que les fichiers ajoutés nomment (à quel module un nom se résout). Un appel M:F(...) d'un builtin du catalogue (io:format/2, os:type/0) ne nomme aucun module. --print-inputs liste les entrées ainsi ajoutées.
• La bibliothèque est library/ de l'arborescence de build, trouvée relativement à clau comme l'archive du runtime, avec un répertoire par application OTP (erts, kernel, stdlib), puis library-asn1/ de l'arborescence de build, les modules générés à la compilation à partir des spécifications ASN.1 de la bibliothèque (public_key). -include_lib("kernel/include/logger.hrl"), file.hrl, eep48.hrl et inet.hrl (#hostent{}) se résolvent vers les propres en-têtes de la bibliothèque sauf si le projet nomme une application kernel ; stdlib/include/ zip.hrl, qlc.hrl, ms_transform.hrl (nomme la transformation, qui s'exécute sur l'OTP de l'hôte : transformations) et assert.hrl sauf s'il nomme une application stdlib. assert.hrl contient les macros, termes d'erreur et commutateurs NOASSERT, NODEBUG, ASSERT d'OTP. Les en-têtes internes d'OTP (erl_bits.hrl, erl_compile.hrl) et ceux de distribution (dist.hrl, dist_util.hrl, net_address.hrl) ne sont pas fournis, ni inet_sctp.hrl (pas de SCTP).
• Un module du lot portant le même nom remplace le module de bibliothèque, avec un avertissement ; les builtins du catalogue de ce nom l'emportent toujours (enregistrement).
• Les modules de bibliothèque sont des modules ordinaires du lot : ils sont liés dans les exécutables et, pour une sortie objet ou IR, produisent leurs propres artefacts. Ce sont du code Erlang, ils cèdent donc la main comme le reste du code.
• Un module atteint uniquement par des noms d'exécution (M:F(...) avec M une variable) n'est pas ajouté : un tel appel lève undef à moins que quelque chose d'autre ne nomme le module.

Remplacements des modules du runtime

Clause remplace les modules d'OTP qu'ERTS implémente en C (NIF, BIF, pilotes de ports, les modules préchargés de erts/preloaded/src) et les modules qu'OTP génère pendant son build (unicode_util). Les kernel et stdlib d'OTP sont de l'Erlang ordinaire, mais appellent ces modules.

Fourni ou absent

Tout ce qui a besoin du runtime et ne peut pas être écrit en Erlang ordinaire est décidé par module, et par groupe de fonctions lorsqu'un module mélange plusieurs préoccupations :

• Fourni : Clause livre le module avec la liste d'exports exacte d'OTP 29. Chaque fonction a l'un de quatre statuts : implemented (un builtin du runtime ou un corps Erlang au-dessus de services existants du runtime), refused (renvoie ou lève ce que les appelants d'OTP gèrent déjà lorsqu'une fonctionnalité est absente, comme {error, enotsup}), stub (lève error({not_implemented, F, A}) avec M:F/A au sommet de la pile, comme le font les bouchons d'erlang ; pas encore fait), ou declined (un bouchon qui reste, avec une raison comme la distribution ou le chargement de code). Un module commence avec toutes ses fonctions en bouchons, de sorte qu'il est découvrable et que ses appelants compilent ; les groupes passent ensuite à leur statut décidé.
• Corps de substitution des builtins : une fonction implémentée par un builtin du catalogue conserve son export et le corps F(_, ...) -> clause_builtin_placeholder., qui ne s'exécute jamais : l'enregistrement lie le builtin à sa place, et un appel qualifié M:F(...) est compilé vers le pont. Seul un appel non qualifié dans le module atteindrait ce corps, donc le module qualifie les appels à ses propres builtins ; library_inventory rejette un corps de substitution qui ne désigne aucun builtin du catalogue, un builtin du catalogue laissé en bouchon not_implemented et un appel non qualifié d'un corps de substitution.
• Absent : Clause ne livre aucun module, peut-être pour toujours, et consigne pourquoi et quels modules Clause de plus haut niveau prennent la place de ses appelants (library/modules.terms). Les couches bas niveau prim_* de fichiers et de sockets (prim_file, prim_buffer, prim_socket, prim_net, prim_inet, socket_registry) ainsi que socket sont les modules absents : les programmes utilisent à la place les file, gen_tcp, gen_udp, inet et net de Clause, et comme les modules de Clause l'emportent sur ceux d'OTP (ci-dessous), les appelants d'OTP d'un module absent (gen_tcp_socket, inet_tcp, ... d'OTP) n'entrent jamais dans un lot. Un module absent n'obtient jamais de bouchon, de sorte qu'une référence à celui-ci est une erreur de compilation, jamais une surprise à l'exécution.

Les fonctions triviales pour le runtime sont implémentées sans décision séparée.

À quel module un nom se résout

OTP est optionnel sur la machine de l'utilisateur ; lorsqu'il est présent, il ne doit pas changer ce qu'un build compile. Un nom de module se résout dans cet ordre :

1. Entrées explicites : les sources que l'utilisateur liste (sources, source_dirs, entrées positionnelles). Une entrée qui porte le nom d'un module Clause le remplace, avec un avertissement nommant les deux fichiers.
2. Modules Clause : les modules de bibliothèque, remplacements fournis compris.
3. source_search_paths, comme décrit dans projets.

Le nom d'un module absent est réservé : un fichier du même nom sur un chemin de recherche (par exemple erts/preloaded/src/prim_file.erl d'OTP) n'est pas utilisé, et le diagnostic indique que Clause ne fournit pas le module. Une entrée explicite peut tout de même le fournir, avec l'avertissement de remplacement.

ignore_modules s'applique aussi aux modules Clause : un module Clause ignoré est absent du lot, et une entrée explicite peut alors le fournir sans avertissement, puisque rien n'est remplacé.

Fichiers

• Les modules de bibliothèque vivent dans library/<application>/, nommé d'après l'application OTP qui possède le module dans OTP : erts (équivalents des modules préchargés et erlang), kernel, stdlib. Les modules auxiliaires privés de 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) se trouvent à côté des modules qu'ils servent. La recherche dans la bibliothèque parcourt chaque répertoire d'application ; un nom de module existe dans au plus l'un d'eux.
• library/modules.terms liste chaque module sur lequel Clause statue : {Module, Application, provided}. ou {Module, Application, missing, "reason"}. Le compilateur le lit pour savoir quels noms sont des modules Clause et lesquels sont réservés.
• Chaque module fourni a un inventaire <module>.terms à côté de lui : {Name, Arity, Group, Status}. par export d'OTP 29, trié par nom et arité, où Group nomme le groupe de décision (par exemple stdlib, distribution, beam). erlang.terms garde son propre format ({Name, Arity, Flags, Status}, module erlang).
• Les listes d'exports sont observées sur un OTP 29 de l'hôte (M:module_info(exports)) ; aucune source d'OTP n'est copiée. Les résultats et les termes d'erreur des fonctions implémentées correspondent à OTP 29 ; les différences délibérées vont dans différences.

Fonctions documentées

library/documented.terms liste les fonctions publiques qu'OTP 29 documente pour erts, kernel, stdlib, crypto et public_key : {Module, Application, Name, Arity}. par fonction dont les documentations de module et de fonction ne sont pas masquées et qui n'est pas obsolète, observée dans les blocs de documentation de l'OTP de l'hôte par tests/compiler/library/observe_docs.escript (exécuté explicitement). Les exports non documentés restent dans les inventaires mais peuvent rester des bouchons.

• library_inventory vérifie que chaque fonction documentée d'un module fourni figure dans son inventaire et n'est pas un bouchon, sauf dans les modules que library_modules.py liste comme partiels avec l'étape du plan qui les achève.
• python tests/compiler/library/library_modules.py coverage . affiche les nombres de fonctions implémentées et documentées de chaque module documenté.

Types

Comme les modules de Clause l'emportent sur ceux d'OTP, le code OTP qui nomme file:filename() ou erlang:time_unit() dans ses specs doit trouver ces types dans les modules de Clause. Chaque module fourni dont l'équivalent OTP exporte des types inclut <module>.types.hrl depuis son propre répertoire : la liste -export_type, puis les types exportés et les types locaux et records qu'ils utilisent, tels qu'OTP les définit (la documentation montre les mêmes définitions ; la documentation installée ne contient aucune définition de type, elles proviennent donc de l'implémentation : les informations de débogage du beam, ou le source livré d'un module préchargé comme erlang). escript tests/compiler/library/observe_types.escript LIBRARY APP MODULE écrit l'en-tête à partir de l'OTP de l'hôte, et --check compare ses formes avec une observation fraîche (CTest library_freshness) ; library_modules.py check exige que chaque en-tête soit inclus par son module. Les types que les en-têtes nomment depuis des modules extérieurs au programme (unicode:chardata(), calendar:datetime()) et les larges unions d'OTP (file:posix() a plus de membres que le graphe de types n'en garde) se résolvent en term() sans avertissement : les diagnostics relèvent de la bibliothèque de Clause, pas du programme de l'utilisateur.

Services du kernel au démarrage

Les file, io et code d'OTP appellent des serveurs enregistrés (file_server_2, code_server, le serveur d'E/S d'un group leader) que l'application kernel démarre au boot. Un exécutable Clause n'en démarre aucun : les file et io propres à Clause n'ont besoin d'aucun serveur, le logger de Clause démarre son serveur à la première utilisation, et un module OTP qui en a besoin échoue comme il échoue sous OTP sans ce serveur (noproc). Le code OTP qui appelle code à l'exécution ne fonctionne donc pas. Démarrer toute l'application kernel n'est pas prévu.

Applications

• Les spécifications viennent du programme, pas d'un chemin de code : clau compile chaque *.app et *.app.src à côté des sources du lot, chaque *.app du répertoire ebin voisin, et ebin/Name.app ou src/Name.app.src de chaque entrée [targets.options.applications] dans le module généré clause_applications, ajouté dès que le lot contient application_controller. Le premier fichier d'un nom d'application l'emporte. Une ressource ne listant aucun module reçoit les modules du lot voisins. Les diagnostics pointent dans le fichier de ressource.
• application:load/1 accepte aussi des termes {application, Name, Keys}. Un nom sans ressource donne {error, {"no such file or directory", "Name.app"}}, comme la réponse d'OTP pour un fichier manquant.
• kernel (11.0.4) et stdlib (8.1) sont chargés et en cours d'exécution dès le départ tels qu'OTP 29.1.1 les liste, sans maîtres d'application ; kernel possède l'environnement par défaut de son kernel.app.
• Une application avec un module de démarrage obtient un maître qui dirige le groupe de ses processus (pour que get_application/0, get_env/1 et start_type/0 y répondent), relaie leurs requêtes d'E/S vers les E/S standard et, à l'arrêt, exécute prep_stop/1, arrête le processus principal, exécute stop/1 et tue ce qui reste du groupe. Une application permanente qui se termine, ou transitoire qui se termine anormalement, arrête le programme avec le slogan d'OTP et le code de sortie 1.
• logger et clause_logger atteignent application par un nom à l'exécution, donc seuls les programmes utilisant application le lient.

Registre

Le plan du projet programme chaque module documenté de erts, kernel et stdlib ; les programmes réels (luerl en premier) fixent les priorités. Le compiler et l'exécuter, classer chaque erreur (unknown module, undefined function M:F/A, syntaxe ou fonctionnalité non prise en charge, autre), et affecter chacune à une étape du plan, à un autre élément du backlog ou à un refus consigné. Avec la sortie d'erreur de l'exécution enregistrée dans un fichier, python tests/compiler/library/library_modules.py report FILE affiche la classification sous forme de tableaux : chaque module inconnu avec son nombre d'erreurs, les modules appelants et les fonctions appelées avec leurs arités ; les fonctions non définies par module ; les autres messages avec leurs nombres.

Outils

Tous se trouvent dans tests/compiler/library/ :

• escript observe_module.escript LIBRARY APP MODULE écrit LIBRARY/APP/MODULE.terms à partir de MODULE:module_info(exports) de l'OTP de l'hôte, en conservant le groupe et le statut de chaque entrée déjà présente ; un nouvel export commence sous la forme {Name, Arity, default, stub}.
• python library_modules.py generate LIBRARY APP MODULE écrit le fichier du module une fois, chaque export étant un bouchon ; ensuite, le fichier est édité à la main.
• python library_modules.py check ROOT (CTest library_inventory, sans OTP) signale chaque désaccord : un module fourni sans ses fichiers, un module absent avec un fichier, un inventaire non listé comme fourni, un export absent de l'inventaire ou l'inverse, une entrée stub/declined qui n'est pas un bouchon not_implemented, une entrée implemented/refused sans corps ni builtin du catalogue. library_rejects le démontre sur une bibliothèque de fixtures délibérément incohérente.
• Le test CTest library_freshness (étiquettes host_otp, full_only) observe à nouveau chaque inventaire et exige qu'il soit inchangé, puis observe, génère, vérifie et compile un nouveau module de bout en bout. library_report exécute clau sur un programme de fixture et vérifie les lignes du rapport.