Bilingual post · Post bilíngue

Jump to: English · Português

English {#english}

Sprint 2 Review: System.* Namespaces

Part 2 of our Mintlify docs tour — after Sprint 1 diagnostics, we walk through each sprint review in the official docs.

Sprint 1 gave CrabPascal trustworthy error locations. Sprint 2 (v2.10.0) tackled the first line of almost every modern Delphi program: uses System.SysUtils. If unit resolution fails there, nothing else matters.

What shipped in v2.10.0

The sprint closed on 2026-05-26 with four concrete deliverables documented in Sprint 2 Review:

1. rtl/sys/System.pas and System.SysUtils.pas — namespace shims that mirror Embarcadero's layout.
2. UnitResolver — prefers System.SysUtils.pas over legacy SysUtils.pas; resolves via rtl/sys and CARGO_MANIFEST_DIR for stable tests.
3. ProjectConfig — puts rtl/sys before rtl/ in search paths so namespaced shims win.
4. Tests — unit_resolver::test_resolve_system_sysutils_rtl_sys and tests/system_units.rs.

This was deliberately layout + resolution, not a SysUtils rewrite. The existing rtl/SysUtils.pas implementation stayed; the win was making dotted filenames first-class.

Why search path order matters

Consider a program that mixes styles during migration:

program Demo;
uses
  SysUtils,              // legacy: rtl/SysUtils.pas
  System.Classes;        // namespaced: rtl/sys/System.Classes.pas

begin
  WriteLn(UpperCase('crabpascal'));
end.

If rtl/ came before rtl/sys, the resolver might pick the wrong file or fail silently. Sprint 2 codified the rule: namespaced shims take priority. The shim pattern keeps maintenance cheap:

unit System.SysUtils;
interface
uses SysUtils;
implementation
end.

You get Delphi-style uses without duplicating thousands of lines of RTL.

Validating locally

From the v2.10.0 release notes:

cargo test
crab-pascal run tests/fixtures/system_sysutils_ok.pas

If resolution fails in your project, verify search paths include CrabPascal's rtl/sys directory. CI uses env!("CARGO_MANIFEST_DIR") so tests do not depend on your current working directory — a lesson the team documented for future sprints.

Retrospective highlights

Three learnings from the review ceremony:

1. Incremental RTL strategy — namespace fidelity first, fill behavior sprint by sprint.
2. Path order is policy — not an implementation detail; document it in ProjectConfig.
3. Stable test roots — resolver tests must not flake when run from arbitrary directories.

Known debt carried forward

The System unit shim does not yet export types beyond implicit re-exports via uses. Open VSX extension publishing for v2.10.0 was deferred — optional when the PO returns. Neither blocked the tag.

What's next in the docs tour

Sprint 3 adds System.Classes with TMemoryStream and TStringList. Sprint 4 brings structured exceptions. In our blog series we jump to Sprint 4 next — exceptions are where Delphi developers feel compatibility most acutely.

Full sprint table: Sprints → Versions · Mintlify: Roadmap → Sprint 2 Review.

Português {#portugus}

Review Sprint 2: namespaces System.*

Parte 2 do tour pela documentação Mintlify — depois dos diagnósticos do Sprint 1, percorremos cada review de sprint nos docs oficiais.

O Sprint 1 deu ao CrabPascal localização confiável de erros. O Sprint 2 (v2.10.0) atacou a primeira linha de quase todo programa Delphi moderno: uses System.SysUtils. Se a resolução de units falha aí, nada mais importa.

O que entrou no v2.10.0

O sprint fechou em 2026-05-26 com quatro entregas documentadas em Sprint 2 Review:

1. rtl/sys/System.pas e System.SysUtils.pas — shims de namespace espelhando o layout Embarcadero.
2. UnitResolver — prefere System.SysUtils.pas ao legado SysUtils.pas; resolve via rtl/sys e CARGO_MANIFEST_DIR para testes estáveis.
3. ProjectConfig — coloca rtl/sys antes de rtl/ nos search paths para os shims namespaced vencerem.
4. Testes — unit_resolver::test_resolve_system_sysutils_rtl_sys e tests/system_units.rs.

Foi layout + resolução de propósito, não reescrita do SysUtils. A implementação em rtl/SysUtils.pas permaneceu; o ganho foi tornar nomes pontuados de primeira classe.

Por que a ordem dos search paths importa

Considere um programa que mistura estilos durante migração:

program Demo;
uses
  SysUtils,              // legado: rtl/SysUtils.pas
  System.Classes;        // namespaced: rtl/sys/System.Classes.pas

begin
  WriteLn(UpperCase('crabpascal'));
end.

Se rtl/ viesse antes de rtl/sys, o resolver poderia escolher o arquivo errado. O Sprint 2 codificou a regra: shims namespaced têm prioridade. O padrão shim mantém manutenção barata:

unit System.SysUtils;
interface
uses SysUtils;
implementation
end.

Você obtém uses estilo Delphi sem duplicar milhares de linhas de RTL.

Validando localmente

Das notas de release v2.10.0:

cargo test
crab-pascal run tests/fixtures/system_sysutils_ok.pas

Se a resolução falhar no seu projeto, verifique se os search paths incluem rtl/sys do CrabPascal. O CI usa env!("CARGO_MANIFEST_DIR") para testes não dependerem do diretório atual — lição documentada para sprints futuros.

Destaques da retrospectiva

Três aprendizados da cerimônia de review:

1. RTL incremental — fidelidade de namespace primeiro, comportamento sprint a sprint.
2. Ordem de paths é política — não detalhe de implementação; documentar em ProjectConfig.
3. Raízes de teste estáveis — testes do resolver não podem falhar intermitentemente por cwd.

Débito conhecido

O shim da unit System ainda não exporta tipos além de reexport implícito via uses. Publicação Open VSX da extensão v2.10.0 ficou adiada — opcional. Nada bloqueou a tag.

Próximo no tour de docs

O Sprint 3 adiciona System.Classes com TMemoryStream e TStringList. O Sprint 4 traz exceções estruturadas. Na série do blog pulamos para o Sprint 4 em seguida — exceções são onde desenvolvedores Delphi sentem compatibilidade com mais força.

Tabela completa: Sprints → Versões · Mintlify: Roadmap → Sprint 2 Review.

Published on dev.to/@crabpascal · Código em CrabPascal