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/"

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"]

Switch to FPC compatibility:

[compiler]

mode = "OBJFPC"

defines = ["FPC", "UNIX"]

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/"

]

This replaces hardcoded -U flags in scripts.

Preprocessor symbols

Match Delphi conditional compilation:

[preprocessor]

enabled = true

symbols = ["DEBUG", "TESTING"]

Your Pascal code can use:

{$IFDEF DEBUG}

  WriteLn('Debug build');

{$ENDIF}

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

CI-friendly error output

[output]

error_format = "gcc"

colors = false

show_stacktrace = false

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

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

AST dumps help when reporting parser bugs in sprint reviews.

Project features

[project]

auto_detect_dproj = true

recursive_uses = true

cache_units = true

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/"

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"]

Para compatibilidade FPC:

[compiler]

mode = "OBJFPC"

defines = ["FPC", "UNIX"]

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/"

]

Substitui flags -U hardcoded em scripts.

Símbolos de pré-processador

Alinhe com compilação condicional Delphi:

[preprocessor]

enabled = true

symbols = ["DEBUG", "TESTING"]

No Pascal:

{$IFDEF DEBUG}

  WriteLn('Build debug');

{$ENDIF}

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

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

Ú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

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

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