====== Ambiente di sviluppo ======

Panoramica della struttura del progetto e dei percorsi importanti per WvdS FPC RAD Studio.

<note>**Tilde (~)** indica la root del repository (es. ''%WORKSPACE%/WvdS.FPC''). Tutti i percorsi usano forward-slash.</note>

===== Struttura del progetto =====

<code>
~/
├── sources/                    # SSOT - versionato (SVN)
│   ├── common/                 # Unit/Lib condivise (FPC + pas2js)
│   │   ├── core/               # Unit base (no UI)
│   │   ├── ui/                 # UI Framework
│   │   │   ├── controls/       # Controlli base
│   │   │   ├── components/     # Componenti compositi
│   │   │   ├── runtime/        # Runtime PXAML
│   │   │   └── targets/        # Renderer (tui/gui/web)
│   │   └── web/                # Host Bridges (solo pas2js)
│   │       ├── nodejs/         # API Node.js
│   │       └── vscode/         # API estensioni VSCode
│   ├── extensions/             # Pacchetti VSIX
│   ├── applications/           # Prodotti/Demo
│   ├── tools/                  # wvds-build, pxamlc
│   └── packages/               # Pacchetti IDE
│
├── binaries/                   # Output build - NON versionato
│   ├── out/                    # Output build
│   ├── cache/                  # Cache compilatore
│   ├── dist/                   # Artefatti release (.vsix)
│   └── logs/                   # Report build, log debug
│
└── assets/                     # Asset statici
</code>

===== Percorsi del progetto =====

^ Variabile ^ Percorso ^ Descrizione ^
| ''~'' | Root repository | ''%WORKSPACE%/WvdS.FPC'' |
| ''~/sources'' | Sorgenti | Single Source of Truth |
| ''~/sources/common'' | Codice condiviso | Compatibile FPC + pas2js |
| ''~/sources/extensions'' | Estensioni VSIX | Pacchetti VSCode |
| ''~/sources/applications'' | Applicazioni | RAD Suite, Demo |
| ''~/binaries'' | Output build | Eliminabile, rigenerabile |
| ''~/binaries/dist'' | Release | .vsix, installer |
| ''~/binaries/logs'' | Log | Report build, log debug |
| ''~/assets'' | Asset | Icone, template |

===== Variabili d'ambiente =====

<note tip>Queste variabili sono **segnaposto** e devono essere adattate all'ambiente di sviluppo locale. I percorsi assoluti dovrebbero essere evitati nei file di configurazione.</note>

^ Variabile ^ Valore predefinito ^ Descrizione ^
| ''%LAZARUS%'' | Installazione Lazarus | es. ''C:\Lazarus'' o ''/opt/lazarus'' |
| ''%PROGRAMFILES%'' | Program Files | Windows: ''C:\Program Files'' |
| ''%USERPROFILE%'' | Directory utente | Windows: ''C:\Users\{name}'', Linux: ''~'' |
| ''%WORKSPACE%'' | Directory di lavoro | Definita dall'utente, es. ''E:\Workspace'' |

===== Compilatore e toolchain =====

^ Variabile ^ Percorso relativo ^ Descrizione ^
| FPC | ''%LAZARUS%/fpc/3.3.1/bin'' | Free Pascal Compiler |
| FPC-SRC | ''%LAZARUS%/fpc/3.3.1/source'' | Sorgenti FPC |
| PAS2JS | ''%LAZARUS%/fpc/3.3.1/bin/pas2js.exe'' | Pascal to JavaScript |
| P2J-RTL | ''%LAZARUS%/fpc/pas2js-windows-2.2.0/packages/rtl'' | RTL pas2js |
| P2J-NODE | ''%LAZARUS%/fpc/pas2js-windows-2.2.0/packages/nodejs'' | Binding Node.js |
| P2J-VSCODE | ''%LAZARUS%/fpc/pas2js-windows-2.2.0/packages/vscode'' | Binding VSCode |

===== Riferimenti esterni =====

<note>Questi percorsi sono **opzionali** e rilevanti solo per sviluppatori che vogliono studiare implementazioni di riferimento.</note>

^ Variabile ^ Percorso relativo ^ Descrizione ^
| DXVCL | ''%WORKSPACE%/3rd/DevExpress/VCL'' | DevExpress VCL (Delphi) |
| DXNET | ''%PROGRAMFILES%/DevExpress 25.1/Components/Sources'' | DevExpress .NET |
| NODEJS-SRC | ''%WORKSPACE%/3rd/node-main'' | Sorgenti Node.js |
| VSCODE-SRC | ''%WORKSPACE%/3rd/vscode-main'' | Sorgenti VSCode |

===== Documentazione =====

^ Variabile ^ Percorso relativo ^ Descrizione ^
| DOKUWIKI | ''%DOKUWIKI_DATA%/pages/de/int/vsce/fpc'' | Pagine DokuWiki |
| SKILLS | ''%WORKSPACE%/WvdS.Rihtlinien'' | Definizioni skill |

===== Regole SSOT =====

<note warning>**Single Source of Truth** - Queste regole sono vincolanti!</note>

  - **''~/sources/''** e l'unica fonte per il codice versionato
  - **''~/binaries/''** e completamente eliminabile e rigenerabile
  - **Mai** duplicare codice runtime in ''~/sources/extensions/''
  - **Mai** committare file generati in ''~/sources/''

===== Struttura output build =====

<code>
~/binaries/out/{app}/{target}/{mode}/
├── gen/              # Codice generato (ui.generated.pas)
├── bin/              # File eseguibili / Bundle JS
├── assets/           # PXAML, immagini, temi
├── build-plan.json   # Configurazione build
└── build-report.md   # Protocollo build
</code>

^ Target ^ Compilatore ^ Output ^
| ''tui'' | FPC | Console nativa (Windows/Linux) |
| ''gui'' | FPC | Desktop nativo (LCL/WinAPI) |
| ''web'' | pas2js | Bundle JavaScript |

^ Mode ^ Descrizione ^
| ''debug'' | Simboli debug, nessuna ottimizzazione |
| ''release'' | Ottimizzato, simboli rimossi |
| ''profile'' | Release + profiling |

===== Struttura estensione =====

<code>
~/sources/extensions/wvds.vscode.{name}/
├── pas/
│   ├── extension_main.pas     # Entry Point (OBBLIGATORIO)
│   ├── {Feature}.Models.pas   # Strutture dati
│   ├── {Feature}.Service.pas  # Logica di business
│   └── {Feature}.Dialog.pas   # UI (opzionale)
│
├── dist/
│   ├── extension_main.js      # JS compilato
│   └── extension_main.js.map  # Source Map
│
├── templates/                  # Template WebView
├── images/                     # Icone
├── package.json               # Manifesto VSCode
├── build.cfg                  # Configurazione build
└── README.md                  # Documentazione
</code>

===== Vedi anche =====

  * [[.:architektur|Panoramica architettura]]
  * [[.:build-pipeline|Pipeline di build]]
  * [[.:extension-entwicklung|Sviluppo estensioni]]