Módulos de biblioteca

Clause incluye sus propias versiones de los módulos de OTP a los que llaman los programas, escritas en Erlang a partir del comportamiento documentado de OTP (no copiadas de los fuentes de OTP) sobre los builtins del runtime, y las compila junto con los programas que las usan.

Contenido

Cada módulo proporcionado exporta la lista completa de OTP 29 para su nombre; su inventario <module>.terms (archivos) registra qué funciones están implementadas y cuáles son stubs.

Los resultados y las razones de error coinciden con OTP 29, incluidas las formas de error de las implementaciones en Erlang de OTP (lists:map(F, x) es {case_clause, x}, lists:nth(0, L) function_clause, lists:seq(1, 10, 0) badarg) y de sus BIF (lists:member/2, lists:keyfind/3, lists:reverse/2, las funciones de maps: badarg, {badmap, M}, {badkey, K}). lists:member/2 compara con =:=, lists:keyfind/3 con ==. lists:sort/1 es un builtin estable del runtime (comparación y orden). Las trazas de pila nombran las funciones de la biblioteca, no las de OTP.

Shell interactivo

shell:start_interactive/0,1 inicia el shell de Erlang sobre los flujos estándar, y clau --shell lo enlaza en un ejecutable del que es el punto de entrada salvo que --entry nombre otro (compilación). El proceso clause_shell ocupa el lugar de user_drv de OTP: imprime la versión del sistema, inicia el servidor de shell e inicia uno nuevo cuando un shell termina (exit().). El servidor lee cada comando mediante el servidor de entrada estándar de io, reimprime el indicador en cada línea adicional de un comando, conserva el historial e inicia el evaluador, que comprueba cada expresión con erl_lint, expande records y la evalúa con erl_eval. Los resultados se imprimen con los records del shell mediante el impresor con formato del runtime (clause_io_lib:pretty/2, io_lib). El fin de la entrada termina el programa con estado 0 después de *** Terminating erlang (nonode@nohost).

Los comandos llaman a módulos por nombre, por lo que un programa que inicia el shell necesita que todas las exportaciones sean invocables: --shell las conserva (vigencia de exportaciones) y enlaza todos los módulos de biblioteca; un programa compilado sin él solo alcanza los módulos que nombra. Las líneas de entrada se leen tal como las entrega el terminal, editadas por el propio terminal: no hay edición de línea con edlin, teclas de historial ni completado con tabulador (diferencias).

Cómo los obtienen los programas

• Cuando un lote (entradas posicionales o un destino de proyecto) nombra un módulo con un átomo literal — M:F(...) con M literal, fun M:F/A, apply(M, F, Args) con M literal, -behaviour(M) o -import(M, ...) — que ninguna entrada define, el compilador busca M.erl en los directorios de aplicaciones de la biblioteca y después en los source_search_paths del proyecto (proyectos), analiza y compila dentro del lote el primero que encuentra, y luego repite el proceso con los módulos que nombran los archivos añadidos (a qué módulo se resuelve un nombre). Una llamada M:F(...) a un builtin del catálogo (io:format/2, os:type/0) no nombra ningún módulo. --print-inputs enumera las entradas que esto añade.
• La biblioteca es library/ del árbol de compilación, que se localiza de forma relativa a clau, igual que el archivo del runtime, con un directorio por aplicación de OTP (erts, kernel, stdlib), y después library-asn1/ del árbol de compilación, los módulos que la compilación genera a partir de las especificaciones ASN.1 de la biblioteca (public_key). -include_lib("kernel/include/logger.hrl"), file.hrl, eep48.hrl e inet.hrl (#hostent{}) se resuelven a las cabeceras propias de la biblioteca salvo que el proyecto nombre una aplicación kernel; stdlib/include/ zip.hrl, qlc.hrl, ms_transform.hrl (nombra la transformación, que se ejecuta en el OTP del anfitrión: transformaciones) y assert.hrl, salvo que nombre una stdlib. assert.hrl tiene las macros, términos de error y conmutadores NOASSERT, NODEBUG, ASSERT de OTP. No se proporcionan las cabeceras internas de OTP (erl_bits.hrl, erl_compile.hrl) ni las de distribución (dist.hrl, dist_util.hrl, net_address.hrl), ni tampoco inet_sctp.hrl (sin SCTP).
• Un módulo del lote con el mismo nombre sustituye al módulo de biblioteca, con una advertencia; los builtins del catálogo con ese nombre siguen prevaleciendo (registro).
• Los módulos de biblioteca son módulos ordinarios del lote: se enlazan en los ejecutables y, para la salida de objetos o de IR, producen sus propios artefactos. Son código Erlang, por lo que ceden el control como el resto del código.
• Un módulo alcanzado solo mediante nombres en tiempo de ejecución (M:F(...) con M una variable) no se añade: esa llamada lanza undef salvo que otra cosa nombre el módulo.

Sustitutos de módulos del runtime

Clause sustituye a los módulos de OTP que ERTS implementa en C (NIF, BIF, drivers de puertos, los módulos precargados de erts/preloaded/src) y a los módulos que OTP genera durante su compilación (unicode_util). Los módulos kernel y stdlib de OTP son Erlang normal, pero llaman a esos módulos.

Proporcionados o ausentes

Todo lo que necesita el runtime y no puede escribirse en Erlang normal se decide por módulo, y por grupo de funciones cuando un módulo mezcla responsabilidades:

• Proporcionado: Clause incluye el módulo con la lista exacta de exportaciones de OTP 29. Cada función tiene uno de cuatro estados: implemented (un builtin del runtime o un cuerpo Erlang sobre servicios del runtime existentes), refused (devuelve o lanza lo que los llamantes de OTP ya manejan cuando falta una funcionalidad, como {error, enotsup}), stub (lanza error({not_implemented, F, A}) con M:F/A en la cima de la pila, como hacen los stubs de erlang; todavía no hecho) o declined (un stub que se queda, con un motivo como la distribución o la carga de código). Un módulo nuevo empieza con todas sus funciones como stubs, de modo que se puede descubrir y sus llamantes compilan; después los grupos pasan al estado decidido.
• Marcadores de posición de builtins: una función implementada por un builtin del catálogo conserva su exportación y el cuerpo F(_, ...) -> clause_builtin_placeholder., que nunca se ejecuta: el registro vincula el builtin en su lugar y una llamada cualificada M:F(...) se compila al puente. Solo una llamada sin cualificar dentro del módulo alcanzaría el marcador, así que el módulo llama a sus propios builtins de forma cualificada; library_inventory rechaza un marcador que no nombre ningún builtin del catálogo, un builtin del catálogo que siga como stub not_implemented y una llamada sin cualificar a un marcador.
• Ausente: Clause no incluye el módulo en absoluto, posiblemente para siempre, y registra el motivo y qué módulos de Clause de más alto nivel ocupan el lugar de sus llamantes (library/modules.terms). Las capas de bajo nivel prim_* de archivos y sockets (prim_file, prim_buffer, prim_socket, prim_net, prim_inet, socket_registry) y socket son los módulos ausentes: los programas usan en su lugar file, gen_tcp, gen_udp, inet y net de Clause y, como los módulos de Clause prevalecen sobre los de OTP (véase más abajo), los llamantes de OTP de un módulo ausente (gen_tcp_socket, inet_tcp, ... de OTP) nunca entran en un lote. Un módulo ausente nunca recibe un stub, por lo que una referencia a él es un error en tiempo de compilación, nunca una sorpresa en tiempo de ejecución.

Las funciones triviales para el runtime se implementan sin una decisión aparte.

A qué módulo se resuelve un nombre

OTP es opcional en la máquina del usuario; cuando está presente, no debe cambiar lo que compila una compilación. Un nombre de módulo se resuelve en este orden:

1. Entradas explícitas: los fuentes que enumera el usuario (sources, source_dirs, entradas posicionales). Uno que tenga el nombre de un módulo de Clause lo sustituye, con una advertencia que nombra ambos archivos.
2. Módulos de Clause: los módulos de biblioteca, incluidos los sustitutos proporcionados.
3. source_search_paths, tal como se describe en proyectos.

El nombre de un módulo ausente está reservado: un archivo con el mismo nombre en una ruta de búsqueda (por ejemplo erts/preloaded/src/prim_file.erl de OTP) no se usa, y el diagnóstico indica que Clause no proporciona el módulo. Una entrada explícita todavía puede proporcionarlo, con la advertencia de sustitución.

ignore_modules también se aplica a los módulos de Clause: un módulo de Clause ignorado está ausente del lote, y una entrada explícita puede entonces proporcionarlo sin advertencia, ya que no se sustituye nada.

Archivos

• Los módulos de biblioteca residen en library/<application>/, con el nombre de la aplicación de OTP a la que pertenece el módulo en OTP: erts (contrapartes de los precargados y erlang), kernel, stdlib. Los módulos auxiliares privados 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) están junto a los módulos a los que sirven. La búsqueda en la biblioteca recorre todos los directorios de aplicaciones; un nombre de módulo existe como mucho en uno de ellos.
• library/modules.terms enumera todos los módulos sobre los que decide Clause: {Module, Application, provided}. o {Module, Application, missing, "reason"}. El compilador lo lee para saber qué nombres son módulos de Clause y cuáles están reservados.
• Cada módulo proporcionado tiene junto a él un inventario <module>.terms: {Name, Arity, Group, Status}. por cada exportación de OTP 29, ordenado por nombre y aridad, donde Group nombra el grupo de decisión (por ejemplo stdlib, distribution, beam). erlang.terms mantiene su propio formato ({Name, Arity, Flags, Status}, módulo erlang).
• Las listas de exportaciones se observan desde un OTP 29 del anfitrión (M:module_info(exports)); no se copia ningún fuente de OTP. Los resultados y los términos de error de las funciones implementadas coinciden con OTP 29; las diferencias deliberadas van a diferencias.

Funciones documentadas

library/documented.terms enumera las funciones públicas que OTP 29 documenta para erts, kernel, stdlib, crypto y public_key: {Module, Application, Name, Arity}. por función cuya documentación de módulo y de función no está oculta y que no está obsoleta, observada de los bloques de documentación del OTP del anfitrión mediante tests/compiler/library/observe_docs.escript (ejecutado explícitamente). Las exportaciones no documentadas permanecen en los inventarios, pero pueden seguir siendo stubs.

• library_inventory comprueba que cada función documentada de un módulo proporcionado esté en su inventario y no sea un stub, excepto en los módulos que library_modules.py enumera como parciales con el paso del plan que los completa.
• python tests/compiler/library/library_modules.py coverage . imprime los recuentos de funciones implementadas y documentadas de cada módulo documentado.

Tipos

Como los módulos de Clause prevalecen sobre los de OTP, el código de OTP que nombra file:filename() o erlang:time_unit() en sus specs debe encontrar esos tipos en los módulos de Clause. Cada módulo proporcionado cuya contraparte de OTP exporta tipos incluye <module>.types.hrl de su propio directorio: la lista -export_type y después los tipos exportados y los tipos y records locales que usan, tal como los define OTP (la documentación muestra las mismas definiciones; la documentación instalada no contiene definiciones de tipos, por lo que proceden de la implementación: la información de depuración del beam, o el fuente incluido de un módulo precargado como erlang). escript tests/compiler/library/observe_types.escript LIBRARY APP MODULE escribe la cabecera a partir del OTP del anfitrión, y --check compara sus formas con una observación nueva (CTest library_freshness); library_modules.py check exige que cada cabecera esté incluida por su módulo. Los tipos que las cabeceras nombran de módulos ajenos al programa (unicode:chardata(), calendar:datetime()) y las uniones amplias de OTP (file:posix() tiene más miembros de los que conserva el grafo de tipos) se resuelven a term() sin advertencia: los diagnósticos corresponden a la biblioteca de Clause, no al programa del usuario.

Servicios de kernel al arrancar

file, io y code de OTP llaman a servidores registrados (file_server_2, code_server, el servidor io de un líder de grupo) que la aplicación kernel arranca durante el inicio. Un ejecutable de Clause no arranca ninguno de ellos: file e io propios de Clause no necesitan servidor, logger de Clause inicia su servidor en el primer uso, y un módulo de OTP que sí lo necesita falla de la misma manera que falla en OTP sin ese servidor (noproc). Por tanto, el código de OTP que llama a code en tiempo de ejecución no funciona. No está previsto arrancar la aplicación kernel completa.

Aplicaciones

• Las especificaciones proceden del programa, no de una ruta de código: clau compila cada *.app y *.app.src junto a los fuentes del lote, cada *.app del directorio ebin junto a ellos, y ebin/Name.app o src/Name.app.src de cada entrada de [targets.options.applications] en el módulo generado clause_applications, añadido siempre que el lote tenga application_controller. Prevalece el primer archivo con un nombre de aplicación. Un recurso que no enumera módulos recibe los módulos del lote junto a él. Los diagnósticos apuntan al archivo de recursos.
• application:load/1 también acepta términos {application, Name, Keys}. Un nombre sin recurso da {error, {"no such file or directory", "Name.app"}}, como responde OTP para un archivo ausente.
• kernel (11.0.4) y stdlib (8.1) están cargadas y en ejecución desde el inicio tal como las enumera OTP 29.1.1, sin procesos maestros de aplicación; kernel tiene el entorno predeterminado de su kernel.app.
• Una aplicación con un módulo de arranque recibe un proceso maestro que lidera el grupo de sus procesos (por lo que get_application/0, get_env/1 y start_type/0 responden dentro de él), retransmite sus solicitudes de E/S a la E/S estándar y, al detenerse, ejecuta prep_stop/1, apaga el proceso superior, ejecuta stop/1 y mata lo que queda del grupo. Una aplicación permanente que termina, o una transitoria que termina de forma anormal, detiene el programa con el mensaje de OTP y estado de salida 1.
• logger y clause_logger llegan a application mediante un nombre en tiempo de ejecución, por lo que solo los programas que usan application lo enlazan.

Registro de seguimiento

El plan del proyecto programa todos los módulos documentados de erts, kernel y stdlib; los programas reales (luerl primero) fijan las prioridades. Se compila y se ejecuta, se clasifica cada error (unknown module, undefined function M:F/A, sintaxis o funcionalidad no admitida, otros) y se asigna cada uno a un paso del plan, a otro elemento pendiente o a un rechazo registrado. Con el stderr de la ejecución guardado en un archivo, python tests/compiler/library/library_modules.py report FILE imprime la clasificación como tablas: cada módulo desconocido con su recuento de errores, los módulos que lo llaman y las funciones llamadas con sus aridades; las funciones no definidas por módulo; y los demás mensajes con sus recuentos.

Herramientas

Todas residen en tests/compiler/library/:

• escript observe_module.escript LIBRARY APP MODULE escribe LIBRARY/APP/MODULE.terms a partir de MODULE:module_info(exports) del OTP del anfitrión, conservando el grupo y el estado de cada entrada ya existente; una exportación nueva empieza como {Name, Arity, default, stub}.
• python library_modules.py generate LIBRARY APP MODULE escribe el archivo del módulo una sola vez, con todas las exportaciones como stubs; a partir de entonces el archivo se edita a mano.
• python library_modules.py check ROOT (CTest library_inventory, sin OTP) informa de cada discrepancia: un módulo proporcionado sin sus archivos, un módulo ausente con un archivo, un inventario no listado como proporcionado, una exportación que no está en el inventario o al revés, una entrada stub/declined que no es un stub not_implemented, una entrada implemented/refused sin cuerpo ni builtin del catálogo. library_rejects lo demuestra con una biblioteca de fixtures deliberadamente inconsistente.
• El CTest library_freshness (etiquetas host_otp, full_only) vuelve a observar cada inventario y exige que no haya cambiado; después observa, genera, comprueba y compila un módulo nuevo de principio a fin. library_report ejecuta clau sobre un programa de fixture y comprueba las filas del informe.