Módulos de biblioteca

O Clause inclui as suas próprias versões dos módulos do OTP que os programas chamam, escritas em Erlang a partir do comportamento documentado do OTP (não copiadas das fontes do OTP) sobre builtins do runtime, e compila-as juntamente com os programas que as usam.

Conteúdo

Cada módulo fornecido exporta a lista completa do OTP 29 para o seu nome; o seu inventário <module>.terms (ficheiros) regista que funções estão implementadas e quais são stubs.

Os resultados e as razões de erro coincidem com o OTP 29, incluindo as formas de erro das implementações em Erlang do OTP (lists:map(F, x) dá {case_clause, x}, lists:nth(0, L) function_clause, lists:seq(1, 10, 0) badarg) e dos seus BIFs (lists:member/2, lists:keyfind/3, lists:reverse/2, as funções de maps: badarg, {badmap, M}, {badkey, K}). lists:member/2 compara com =:=, lists:keyfind/3 com ==. lists:sort/1 é um builtin estável do runtime (comparação e ordem). Os stack traces indicam as funções da biblioteca, não as do OTP.

Shell interativa

shell:start_interactive/0,1 inicia a shell Erlang nos fluxos padrão, e clau --shell liga-a num executável de que é o ponto de entrada, salvo se --entry nomear outro (compilação). O processo clause_shell ocupa o lugar do user_drv do OTP: apresenta a versão do sistema, inicia o servidor de shell e inicia um novo quando uma shell termina (exit().). O servidor lê cada comando através do servidor de entrada padrão de io, repetindo o prompt em cada linha adicional de um comando, mantém o histórico e inicia o avaliador, que verifica cada expressão com erl_lint, expande records e avalia-a com erl_eval. Os resultados são apresentados com os records da shell pelo formatador de apresentação do runtime (clause_io_lib:pretty/2, io_lib). O fim da entrada termina o programa com estado 0 após *** Terminating erlang (nonode@nohost).

Os comandos chamam módulos pelo nome, pelo que um programa que inicia a shell precisa de poder chamar todos os exports: --shell mantém-nos (exports em uso) e liga todos os módulos da biblioteca; um programa compilado sem essa opção alcança apenas os módulos que nomeia. As linhas de entrada são lidas tal como o terminal as entrega, editadas pelo próprio terminal: não há edição de linha edlin, teclas de histórico nem completamento com Tab (diferenças).

Como os programas os obtêm

• Quando um lote (entradas posicionais ou um alvo de projeto) nomeia um módulo com um átomo literal — M:F(...) com M literal, fun M:F/A, apply(M, F, Args) com M literal, -behaviour(M) ou -import(M, ...) — que nenhuma entrada define, o compilador procura M.erl nos diretórios de aplicações da biblioteca e depois nos source_search_paths do projeto (projetos), analisa e compila no lote o primeiro que encontrar, repetindo depois para os módulos que os ficheiros acrescentados nomeiam (a que módulo um nome é resolvido). Uma chamada M:F(...) de um builtin do catálogo (io:format/2, os:type/0) não nomeia nenhum módulo. --print-inputs lista as entradas que isto acrescenta.
• A biblioteca é library/ da árvore de compilação, encontrada em relação a clau tal como o arquivo do runtime, com um diretório por aplicação OTP (erts, kernel, stdlib), depois library-asn1/ da árvore de compilação, os módulos que a compilação gera a partir das especificações ASN.1 da biblioteca (public_key). -include_lib("kernel/include/logger.hrl"), file.hrl, eep48.hrl e inet.hrl (#hostent{}) resolvem-se para os cabeçalhos da própria biblioteca, salvo se o projeto nomear uma aplicação kernel; stdlib/include/ zip.hrl, qlc.hrl, ms_transform.hrl (nomeia a transformação, que se executa no OTP do anfitrião: transformações) e assert.hrl, salvo se nomear uma aplicação stdlib. assert.hrl tem as macros, termos de erro e opções NOASSERT, NODEBUG, ASSERT do OTP. Os cabeçalhos internos do OTP (erl_bits.hrl, erl_compile.hrl) e de distribuição (dist.hrl, dist_util.hrl, net_address.hrl) não são fornecidos, nem inet_sctp.hrl (sem SCTP).
• Um módulo do lote com o mesmo nome substitui o módulo da biblioteca, com um aviso; os builtins do catálogo com esse nome continuam a prevalecer (registo).
• Os módulos de biblioteca são módulos de lote comuns: são ligados aos executáveis e, para saída em objeto ou IR, produzem os seus próprios artefactos. São código Erlang, pelo que cedem a execução (yield) como qualquer outro código.
• Um módulo alcançado apenas através de nomes em tempo de execução (M:F(...) com M uma variável) não é acrescentado: essa chamada lança undef, a menos que outra coisa nomeie o módulo.

Substituições de módulos do runtime

O Clause substitui os módulos do OTP que o ERTS implementa em C (NIFs, BIFs, drivers de portas, os módulos pré-carregados de erts/preloaded/src) e os módulos que o OTP gera durante a sua compilação (unicode_util). O kernel e o stdlib do OTP são Erlang simples, mas chamam esses módulos.

Fornecido ou em falta

Tudo o que precisa do runtime e não pode ser escrito em Erlang simples é decidido por módulo, e por grupo de funções quando um módulo mistura responsabilidades:

• Fornecido: o Clause inclui o módulo com a lista de exports exata do OTP 29. Cada função tem um de quatro estados: implemented (um builtin do runtime ou um corpo Erlang sobre serviços do runtime existentes), refused (devolve ou lança o que os chamadores do OTP já tratam quando uma funcionalidade está ausente, como {error, enotsup}), stub (lança error({not_implemented, F, A}) com M:F/A no topo da pilha, como fazem os stubs de erlang; ainda não feito) ou declined (um stub que fica, com uma razão como a distribuição ou o carregamento de código). Um módulo novo começa com todas as funções como stubs, para que seja detetável e os seus chamadores compilem; os grupos passam depois ao estado decidido.
• Marcadores de posição de builtins: uma função implementada por um builtin do catálogo mantém o seu export e o corpo F(_, ...) -> clause_builtin_placeholder., que nunca é executado: o registo associa o builtin no seu lugar, e uma chamada qualificada M:F(...) compila para a ponte. Só uma chamada não qualificada dentro do módulo chegaria ao marcador de posição, pelo que o módulo chama os seus próprios builtins de forma qualificada; library_inventory rejeita um marcador de posição que não nomeie nenhum builtin do catálogo, um builtin do catálogo que permaneça como stub not_implemented e uma chamada não qualificada de um marcador de posição.
• Em falta: o Clause não inclui módulo nenhum, possivelmente para sempre, e regista porquê e que módulos do Clause de nível mais alto tomam o lugar dos seus chamadores (library/modules.terms). As camadas de ficheiros e de sockets prim_* de baixo nível (prim_file, prim_buffer, prim_socket, prim_net, prim_inet, socket_registry) e socket são os módulos em falta: os programas usam antes file, gen_tcp, gen_udp, inet e net do Clause e, como os módulos do Clause prevalecem sobre os do OTP (ver abaixo), os chamadores do OTP de um módulo em falta (gen_tcp_socket, inet_tcp, ... do OTP) nunca entram num lote. Um módulo em falta nunca recebe um stub, pelo que uma referência a ele é um erro em tempo de compilação, nunca uma surpresa em tempo de execução.

As funções triviais para o runtime são implementadas sem uma decisão separada.

A que módulo um nome é resolvido

O OTP é opcional na máquina do utilizador; quando presente, não pode alterar o que uma compilação compila. Um nome de módulo é resolvido por esta ordem:

1. Entradas explícitas: os códigos-fonte que o utilizador lista (sources, source_dirs, entradas posicionais). Uma que tenha o nome de um módulo do Clause substitui-o, com um aviso que indica ambos os ficheiros.
2. Módulos do Clause: os módulos da biblioteca, incluindo as substituições fornecidas.
3. source_search_paths, tal como descrito em projetos.

O nome de um módulo em falta está reservado: um ficheiro com o mesmo nome num caminho de pesquisa (por exemplo erts/preloaded/src/prim_file.erl do OTP) não é usado, e o diagnóstico indica que o Clause não fornece o módulo. Uma entrada explícita pode ainda fornecê-lo, com o aviso de substituição.

ignore_modules aplica-se também aos módulos do Clause: um módulo do Clause ignorado fica em falta no lote, e uma entrada explícita pode então fornecê-lo sem aviso, uma vez que nada é substituído.

Ficheiros

• Os módulos de biblioteca ficam em library/<application>/, com o nome da aplicação OTP a que o módulo pertence no OTP: erts (os equivalentes pré-carregados e erlang), kernel, stdlib. Os módulos auxiliares privados do 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) ficam ao lado dos módulos que servem. A consulta da biblioteca procura em todos os diretórios de aplicações; um nome de módulo existe no máximo num deles.
• library/modules.terms lista todos os módulos sobre os quais o Clause decide: {Module, Application, provided}. ou {Module, Application, missing, "reason"}. O compilador lê-o para saber que nomes são módulos do Clause e quais estão reservados.
• Cada módulo fornecido tem um inventário <module>.terms ao seu lado: {Name, Arity, Group, Status}. por export do OTP 29, ordenado por nome e aridade, em que Group indica o grupo de decisão (por exemplo stdlib, distribution, beam). erlang.terms mantém o seu próprio formato ({Name, Arity, Flags, Status}, módulo erlang).
• As listas de exports são observadas a partir de um OTP 29 do anfitrião (M:module_info(exports)); nenhum código-fonte do OTP é copiado. Os resultados e os termos de erro das funções implementadas coincidem com o OTP 29; as diferenças deliberadas vão para diferenças.

Funções documentadas

library/documented.terms lista as funções públicas que o OTP 29 documenta para erts, kernel, stdlib, crypto e public_key: {Module, Application, Name, Arity}. por função cuja documentação do módulo e da função não está oculta e que não está obsoleta, observada nos blocos de documentação do OTP do anfitrião por tests/compiler/library/observe_docs.escript (executado explicitamente). Os exports não documentados mantêm-se nos inventários mas podem continuar como stubs.

• library_inventory verifica que cada função documentada de um módulo fornecido está no seu inventário e não é um stub, exceto nos módulos que library_modules.py lista como parciais com o passo do plano que os completa.
• python tests/compiler/library/library_modules.py coverage . imprime as contagens de funções implementadas e documentadas de cada módulo documentado.

Tipos

Como os módulos do Clause prevalecem sobre os do OTP, o código OTP que nomeia file:filename() ou erlang:time_unit() nas suas specs tem de encontrar esses tipos nos módulos do Clause. Cada módulo fornecido cujo equivalente OTP exporta tipos inclui <module>.types.hrl do seu próprio diretório: a lista -export_type, depois os tipos exportados e os tipos locais e records que eles usam, tal como o OTP os define (a documentação mostra as mesmas definições; a documentação instalada não traz definições de tipos, pelo que estas vêm da implementação: a informação de depuração do beam, ou o código-fonte distribuído de um módulo pré-carregado como erlang). escript tests/compiler/library/observe_types.escript LIBRARY APP MODULE escreve o cabeçalho a partir do OTP do anfitrião, e --check compara as suas formas com uma observação nova (CTest library_freshness); library_modules.py check exige que cada cabeçalho seja incluído pelo seu módulo. Os tipos que os cabeçalhos nomeiam a partir de módulos fora do programa (unicode:chardata(), calendar:datetime()) e as uniões largas do OTP (file:posix() tem mais membros do que o grafo de tipos mantém) resolvem-se para term() sem aviso: os diagnósticos pertencem à biblioteca do Clause, não ao programa do utilizador.

Serviços do kernel no arranque

file, io e code do OTP chamam servidores registados (file_server_2, code_server, o servidor de io de um group leader) que a aplicação kernel inicia no arranque. Um executável do Clause não inicia nenhum deles: os próprios file e io do Clause não precisam de servidor, o logger do Clause inicia o seu servidor na primeira utilização, e um módulo OTP que precise de um falha da mesma forma que falha no OTP sem esse servidor (noproc). O código OTP que chama code em tempo de execução não funciona, portanto. Arrancar toda a aplicação kernel não está planeado.

Aplicações

• As especificações vêm do programa, não de um caminho de código: o clau compila todos os *.app e *.app.src ao lado dos ficheiros-fonte do lote, todos os *.app no diretório ebin adjacente, e ebin/Name.app ou src/Name.app.src de cada entrada de [targets.options.applications] para o módulo gerado clause_applications, acrescentado sempre que o lote tem application_controller. Prevalece o primeiro ficheiro de cada nome de aplicação. Um recurso que não liste módulos recebe os módulos do lote ao seu lado. Os diagnósticos apontam para o ficheiro de recurso.
• application:load/1 também aceita termos {application, Name, Keys}. Um nome sem recurso dá {error, {"no such file or directory", "Name.app"}}, como a resposta do OTP para um ficheiro em falta.
• kernel (11.0.4) e stdlib (8.1) estão carregados e em execução desde o início tal como o OTP 29.1.1 os lista, sem processos mestres de aplicação; kernel tem o ambiente predefinido do seu kernel.app.
• Uma aplicação com um módulo de arranque recebe um processo mestre que lidera o grupo dos seus processos (pelo que get_application/0, get_env/1 e start_type/0 respondem dentro dele), reencaminha os seus pedidos de E/S para a E/S padrão e, ao parar, executa prep_stop/1, encerra o processo de topo, executa stop/1 e termina o que resta do grupo. Uma aplicação permanente que termina, ou uma transitória que termina de forma anormal, termina o programa com a mensagem do OTP e estado de saída 1.
• logger e clause_logger alcançam application por um nome em tempo de execução, pelo que só os programas que usam application o ligam.

Registo

O plano do projeto agenda todos os módulos documentados de erts, kernel e stdlib; os programas reais (luerl primeiro) definem as prioridades. Compile-o e execute-o, classifique cada erro (unknown module, undefined function M:F/A, sintaxe ou funcionalidade não suportada, outro) e atribua cada um a um passo do plano, a outro item pendente ou a uma recusa registada. Com o stderr da execução guardado num ficheiro, python tests/compiler/library/library_modules.py report FILE imprime a classificação em tabelas: cada módulo desconhecido com o seu número de erros, os módulos chamadores e as funções chamadas com as aridades; as funções não definidas por módulo; as outras mensagens com as suas contagens.

Ferramentas

Todas ficam em tests/compiler/library/:

• escript observe_module.escript LIBRARY APP MODULE escreve LIBRARY/APP/MODULE.terms a partir de MODULE:module_info(exports) do OTP do anfitrião, mantendo o grupo e o estado de cada entrada já existente; um novo export começa como {Name, Arity, default, stub}.
• python library_modules.py generate LIBRARY APP MODULE escreve o ficheiro do módulo uma vez, com todos os exports como stubs; a partir daí o ficheiro é editado à mão.
• python library_modules.py check ROOT (CTest library_inventory, sem OTP) comunica todas as discordâncias: um módulo fornecido sem os seus ficheiros, um módulo em falta com um ficheiro, um inventário não listado como fornecido, um export ausente do inventário ou o inverso, uma entrada stub/declined que não é um stub not_implemented, uma entrada implemented/refused sem corpo nem builtin do catálogo. library_rejects prova-o numa biblioteca de fixture deliberadamente inconsistente.
• O CTest library_freshness (etiquetas host_otp, full_only) volta a observar todos os inventários e exige-os inalterados, depois observa, gera, verifica e compila um módulo novo de ponta a ponta. library_report executa o clau num programa de fixture e verifica as linhas do relatório.