DEV Community

CrabPascal
CrabPascal

Posted on

Configuring CrabPascal with crabpascal.toml | Configurando com crabpascal.toml

#pascal #rust #compiler #delphi

Bilingual post · Post bilíngue

Jump to: English · Português

English {#english}

Configuring CrabPascal with crabpascal.toml

Every serious compiler needs project-level configuration. CrabPascal v2.22.0 reads crabpascal.toml from your project root — search paths, preprocessor symbols, Delphi vs FPC mode, output format, and runtime defaults.

Where the file lives

The compiler searches in order:

  1. crabpascal.toml (project root)
  2. .crabpascal.toml (hidden)
  3. config/crabpascal.toml

If none exist, sensible defaults apply. Add the file when your project grows beyond a single .dpr.

Starter configuration 

[compiler]
version = "2.22.0"
search_paths = ["rtl/", "lib/", "examples/"]
defines = ["CRABPASCAL", "RELEASE", "MSWINDOWS"]
mode = "DELPHI"  # or "OBJFPC"
strict = false
warnings = true

[preprocessor]
enabled = true
process_includes = true
symbols = []

[output]
error_format = "vscode"  # or "gcc", "delphi"
colors = true

[runtime]
default_http_port = 9000

[paths]
rtl_path = "rtl/"
output_path = "output/"
Enter fullscreen mode Exit fullscreen mode

Place this beside your .dpr file. All CLI commands (check, run, build-exe) pick it up automatically.

Common use cases

Delphi vs Free Pascal mode 

[compiler]
mode = "DELPHI"
defines = ["CRABPASCAL", "MSWINDOWS"]
Enter fullscreen mode Exit fullscreen mode

Switch to FPC compatibility:

[compiler]
mode = "OBJFPC"
defines = ["FPC", "UNIX"]
Enter fullscreen mode Exit fullscreen mode

Mode affects parsing rules and RTL resolution under rtl/.

Custom unit search paths

Large projects split units across folders:

[compiler]
search_paths = [
  "rtl/",
  "src/units/",
  "src/services/",
  "third_party/"
]
Enter fullscreen mode Exit fullscreen mode

This replaces hardcoded -U flags in scripts.

Preprocessor symbols

Match Delphi conditional compilation:

[preprocessor]
enabled = true
symbols = ["DEBUG", "TESTING"]
Enter fullscreen mode Exit fullscreen mode

Your Pascal code can use:

{$IFDEF DEBUG}
  WriteLn('Debug build');
{$ENDIF}
Enter fullscreen mode Exit fullscreen mode

Run crab-pascal preproc MyApp.dpr to inspect expanded source.

CI-friendly error output 

[output]
error_format = "gcc"
colors = false
show_stacktrace = false
Enter fullscreen mode Exit fullscreen mode

GitHub Actions parsers often prefer gcc-style lines. Local development can keep vscode format for the extension.

Horse API port 

[runtime]
default_http_port = 8080
Enter fullscreen mode Exit fullscreen mode

Useful when running multiple examples (crud on 9000, time-server on 9001).

Development mode

Debugging compiler issues? Enable dev artifacts:

[development]
dev_mode = true
save_ast = true
save_preprocessed = true
Enter fullscreen mode Exit fullscreen mode

AST dumps help when reporting parser bugs in sprint reviews.

Project features 

[project]
auto_detect_dproj = true
recursive_uses = true
cache_units = true
Enter fullscreen mode Exit fullscreen mode

recursive_uses mirrors Delphi's transitive unit loading — critical for examples/crud/ with multiple .pas files.

Tips

  • Commit crabpascal.toml to version control; skip generated output/.
  • Keep rtl/ in search_paths unless you provide a full custom RTL.
  • After changing config, re-run check — no restart needed.

Configuration turns CrabPascal from a demo compiler into a project-aware toolchain. One TOML file aligns CLI, CI, and VS Code extension behavior.

Português {#portugus}

Configurando o CrabPascal com crabpascal.toml

Todo compilador sério precisa de configuração por projeto. O CrabPascal v2.22.0 lê crabpascal.toml na raiz — search paths, símbolos de pré-processador, modo Delphi vs FPC, formato de saída e defaults de runtime.

Onde o arquivo fica

O compilador busca nesta ordem:

  1. crabpascal.toml (raiz do projeto)
  2. .crabpascal.toml (oculto)
  3. config/crabpascal.toml

Se nenhum existir, defaults sensatos são aplicados. Adicione o arquivo quando o projeto passar de um único .dpr.

Configuração inicial 

[compiler]
version = "2.22.0"
search_paths = ["rtl/", "lib/", "examples/"]
defines = ["CRABPASCAL", "RELEASE", "MSWINDOWS"]
mode = "DELPHI"  # ou "OBJFPC"
strict = false
warnings = true

[preprocessor]
enabled = true
process_includes = true
symbols = []

[output]
error_format = "vscode"  # ou "gcc", "delphi"
colors = true

[runtime]
default_http_port = 9000

[paths]
rtl_path = "rtl/"
output_path = "output/"
Enter fullscreen mode Exit fullscreen mode

Coloque ao lado do .dpr. Todos os comandos CLI (check, run, build-exe) carregam automaticamente.

Casos de uso comuns

Modo Delphi vs Free Pascal 

[compiler]
mode = "DELPHI"
defines = ["CRABPASCAL", "MSWINDOWS"]
Enter fullscreen mode Exit fullscreen mode

Para compatibilidade FPC:

[compiler]
mode = "OBJFPC"
defines = ["FPC", "UNIX"]
Enter fullscreen mode Exit fullscreen mode

O modo afeta regras de parsing e resolução RTL em rtl/.

Search paths customizados

Projetos grandes dividem units em pastas:

[compiler]
search_paths = [
  "rtl/",
  "src/units/",
  "src/services/",
  "third_party/"
]
Enter fullscreen mode Exit fullscreen mode

Substitui flags -U hardcoded em scripts.

Símbolos de pré-processador

Alinhe com compilação condicional Delphi:

[preprocessor]
enabled = true
symbols = ["DEBUG", "TESTING"]
Enter fullscreen mode Exit fullscreen mode

No Pascal:

{$IFDEF DEBUG}
  WriteLn('Build debug');
{$ENDIF}
Enter fullscreen mode Exit fullscreen mode

Execute crab-pascal preproc MyApp.dpr para ver o fonte expandido.

Saída de erro para CI 

[output]
error_format = "gcc"
colors = false
show_stacktrace = false
Enter fullscreen mode Exit fullscreen mode

Parsers do GitHub Actions costumam preferir linhas estilo gcc. Desenvolvimento local pode manter formato vscode para a extensão.

Porta da API Horse 

[runtime]
default_http_port = 8080
Enter fullscreen mode Exit fullscreen mode

Útil ao rodar vários exemplos (crud na 9000, time-server na 9001).

Modo desenvolvimento

Depurando o compilador? Habilite artefatos de dev:

[development]
dev_mode = true
save_ast = true
save_preprocessed = true
Enter fullscreen mode Exit fullscreen mode

Dumps de AST ajudam ao reportar bugs de parser nas reviews de sprint.

Recursos de projeto 

[project]
auto_detect_dproj = true
recursive_uses = true
cache_units = true
Enter fullscreen mode Exit fullscreen mode

recursive_uses espelha o carregamento transitivo de units do Delphi — essencial para examples/crud/ com vários .pas.

Dicas

  • Commite crabpascal.toml no controle de versão; ignore output/ gerado.
  • Mantenha rtl/ em search_paths salvo RTL customizado completo.
  • Após mudar config, rode check de novo — não precisa reiniciar.

Configuração transforma o CrabPascal de compilador demo em toolchain ciente de projeto. Um arquivo TOML alinha CLI, CI e extensão VS Code.

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

Top comments (0)