78 lines
3.5 KiB
Markdown
78 lines
3.5 KiB
Markdown
# PR-07.3 - IRVM Entrypoint Export Emission for Runtime Loader Compatibility
|
|
|
|
## Briefing
|
|
|
|
Hoje um cartridge pode compilar com `entrypoint: "frame"` no `manifest.json` e `pub fn frame()` no `mod.barrel`, mas ainda falhar em runtime com `EntrypointNotFound`.
|
|
|
|
A causa observada e que o `program.pbx` pode ser emitido sem secao `exports` (section kind `4`), enquanto o loader resolve entrypoint nominal usando `program.exports`.
|
|
|
|
## Motivation
|
|
|
|
### Dor atual que esta PR resolve
|
|
|
|
1. Build aparentemente valido, mas falha de bootstrap em runtime.
|
|
2. Divergencia entre contrato de manifesto (`entrypoint` nominal) e artefato PBX emitido.
|
|
3. Falta de evidencia automatizada para evitar regressao de exports no caminho `IRBackend -> IRVM -> Bytecode`.
|
|
|
|
## Target
|
|
|
|
Corrigir o pipeline backend para sempre emitir export nominal do entrypoint no PBX de preload, garantindo compatibilidade com o loader quando o `manifest.json` declara entrypoint por nome.
|
|
|
|
## Dependencies
|
|
|
|
Prerequisitos diretos:
|
|
|
|
1. `PR-05.3` (politica deterministica de entrypoint no indice `0`).
|
|
2. `PR-05.4` (coerencia unica entre IRVM e EmissionPlan).
|
|
|
|
## Scope
|
|
|
|
1. `LowerToIRVMService` deve preencher `EmissionPlan.exports` com o simbolo do entrypoint apontando para `func_idx = 0`.
|
|
2. Adicionar regressao dedicada para garantir que `coherentEmissionPlan()` preserva export do entrypoint.
|
|
3. Validar serializacao PBX com secao `exports` presente quando houver entrypoint nominal.
|
|
4. Cobrir cenario de integracao onde `manifest.entrypoint = "frame"` inicializa VM sem `EntrypointNotFound`.
|
|
|
|
## Non-Goals
|
|
|
|
1. Nao exportar toda a superficie de funcoes executaveis neste passo.
|
|
2. Nao alterar formato binario PBX alem da presenca correta da secao `exports`.
|
|
3. Nao mudar semantica de resolucao por indice numerico de entrypoint.
|
|
|
|
## Method
|
|
|
|
### O que deve ser feito explicitamente
|
|
|
|
1. No `LowerToIRVMService`, construir `BytecodeEmitter.EmissionPlan` com `exports` contendo, no minimo, `Export(entryPointCallableName, 0)`.
|
|
2. Garantir determinismo do export do entrypoint a partir da mesma politica que fixa `func_id = 0`.
|
|
3. Adicionar teste unitario em `LowerToIRVMServiceTest` para verificar export nominal do entrypoint no plano coerente.
|
|
4. Adicionar teste de emissao/link para verificar secao `exports` no modulo serializado.
|
|
5. Adicionar teste de integracao runtime-backed para falhar se regressar para `EntrypointNotFound` em cartridge com entrypoint nominal valido.
|
|
|
|
## Acceptance Criteria
|
|
|
|
1. Build de projeto PBS com entrypoint `frame` gera PBX com secao `exports`.
|
|
2. O simbolo `frame` aponta para `func_idx = 0` no artefato emitido.
|
|
3. Execucao de cartridge com `manifest.entrypoint = "frame"` nao falha por `EntrypointNotFound` quando o programa contem o entrypoint admitido.
|
|
4. Rebuilds equivalentes produzem mapping de export deterministico.
|
|
|
|
## Tests
|
|
|
|
1. Novos testes de backend:
|
|
- `:prometeu-compiler:prometeu-build-pipeline:test`
|
|
2. Reexecucao de compatibilidade runtime-backed:
|
|
- `:prometeu-compiler:prometeu-build-pipeline:test --tests *Runtime*`
|
|
3. Smoke local recomendado:
|
|
- `./runtime/prometeu build .`
|
|
- `./runtime/prometeu run cartridge`
|
|
|
|
## Affected Documents
|
|
|
|
1. `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
|
|
2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
|
|
3. `docs/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
|
4. `docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`
|
|
|
|
## Open Questions
|
|
|
|
1. Em evolucao futura, devemos exportar apenas o entrypoint ou tambem funcoes explicitamente marcadas para linking externo?
|