====== Installazione e configurazione ======

Questa guida descrive la configurazione completa di WvdS FPC RAD Studio per VS Code.

===== Prerequisiti =====

==== Visual Studio Code ====

Installate VS Code da [[https://code.visualstudio.com/|code.visualstudio.com]]. Versione minima: 1.85.0.

Verifica della versione installata:
<code>
code --version
</code>

==== Free Pascal Compiler (FPC) ====

**Opzione A: Bundle Lazarus (consigliato)**

L'IDE Lazarus include FPC. Download: [[https://www.lazarus-ide.org/|lazarus-ide.org]]

Percorsi di installazione tipici:
  * Windows: ''%LAZARUS%\fpc\3.2.2\bin\i386-win32\fpc.exe''
  * Linux: ''/usr/lib/fpc/3.2.2/fpc''
  * macOS: ''/usr/local/lib/fpc/3.2.2/fpc''

**Opzione B: FPC standalone**

Download: [[https://www.freepascal.org/download.html|freepascal.org]]

Verifica:
<code bash>
fpc -iV
</code>
Output atteso: ''3.2.2'' o superiore.

==== pas2js (per progetti web) ====

pas2js è il transpiler Pascal-to-JavaScript per applicazioni browser e Node.js.

**Installazione via Lazarus:**

Cercate "pas2js" nel Lazarus Online Package Manager e installatelo.

**Installazione manuale:**

Download: [[https://wiki.freepascal.org/pas2js|wiki.freepascal.org/pas2js]]

Verifica:
<code bash>
pas2js -h
</code>

==== Strumenti opzionali ====

^ Strumento ^ Utilizzo ^ Download ^
| lazbuild | Compilare progetti Lazarus (.lpi) senza IDE | Incluso in Lazarus |
| Inno Setup | Creare installer Windows | [[https://jrsoftware.org/isinfo.php|jrsoftware.org]] |
| GNU make | Eseguire Makefile | Incluso in MinGW/MSYS2 |

===== Installazione delle estensioni =====

==== Metodo 1: VS Code Marketplace ====

  - Aprite VS Code
  - Cliccate sull'icona Extensions (''Ctrl+Shift+X'')
  - Cercate "WvdS FPC"
  - Installate le estensioni desiderate:
    * **WvdS VSCode Core** - Obbligatoria
    * **WvdS VSCode Build** - Consigliata
    * **WvdS VSCode Projects** - Consigliata
    * **WvdS VSCode UI Designer** - Per sviluppo PXAML
    * **WvdS VSCode UI Meta** - Per IntelliSense
    * **WvdS VSCode UI Preview** - Per anteprima live
    * **WvdS VSCode Packaging** - Per creazione VSIX

==== Metodo 2: Riga di comando ====

<code bash>
# Installazione base
code --install-extension wvds.wvds-vscode-core
code --install-extension wvds.wvds-vscode-build
code --install-extension wvds.wvds-vscode-projects

# Sviluppo UI
code --install-extension wvds.wvds-vscode-ui-designer
code --install-extension wvds.wvds-vscode-ui-meta
code --install-extension wvds.wvds-vscode-ui-preview

# Packaging
code --install-extension wvds.wvds-vscode-packaging
</code>

==== Metodo 3: File VSIX ====

Per installazione offline o distribuzione interna:

  - Scaricate i file .vsix
  - In VS Code: ''Extensions'' -> ''...'' -> ''Install from VSIX...''
  - Selezionate il file .vsix

===== Configurazione della toolchain =====

Dopo l'installazione della Core Extension, i percorsi dei compilatori devono essere configurati.

==== Rilevamento automatico ====

La suite cerca automaticamente di trovare gli strumenti installati:

  - Aprite la palette dei comandi: ''Ctrl+Shift+P''
  - Eseguite: ''WvdS: Toolchain Configuration...''
  - Il dialogo mostra gli strumenti rilevati con segni di spunta verdi
  - Gli strumenti non trovati sono contrassegnati in rosso

==== Configurazione manuale ====

Se il rilevamento automatico fallisce, i percorsi possono essere impostati manualmente:

**Via Settings UI:**

''File'' -> ''Preferences'' -> ''Settings'' -> Cercate "wvds.toolchain"

**Via settings.json:**

<note tip>Utilizzate variabili d'ambiente invece di percorsi assoluti per una migliore portabilità.</note>

<code json>
{
  "wvds.toolchain.fpcPath": "${env:LAZARUS}/fpc/3.2.2/bin/i386-win32/fpc.exe",
  "wvds.toolchain.pas2jsPath": "${env:LAZARUS}/fpc/3.2.2/bin/i386-win32/pas2js.exe",
  "wvds.toolchain.lazbuildPath": "${env:LAZARUS}/lazbuild.exe",
  "wvds.toolchain.innoSetupPath": "${env:PROGRAMFILES(X86)}/Inno Setup 6/ISCC.exe",
  "wvds.toolchain.makePath": "${env:MSYS2}/usr/bin/make.exe"
}
</code>

==== Impostazioni nel dettaglio ====

^ Impostazione ^ Descrizione ^ Default ^
| ''wvds.toolchain.fpcPath'' | Percorso a fpc.exe / fpc | Rilevamento automatico |
| ''wvds.toolchain.pas2jsPath'' | Percorso a pas2js.exe / pas2js | Rilevamento automatico |
| ''wvds.toolchain.lazbuildPath'' | Percorso a lazbuild.exe / lazbuild | Rilevamento automatico |
| ''wvds.toolchain.innoSetupPath'' | Percorso a ISCC.exe | Rilevamento automatico |
| ''wvds.toolchain.makePath'' | Percorso a make.exe / make | Rilevamento automatico |
| ''wvds.toolchain.wslEnabled'' | WSL per cross-compilation Linux | false |
| ''wvds.toolchain.wslDistribution'' | Distribuzione WSL (es. Ubuntu-22.04) | "" |

===== Supporto WSL (Windows) =====

Per la cross-compilation sotto Windows, può essere attivato WSL:

==== Prerequisiti ====

  - WSL 2 con una distribuzione Linux (Ubuntu consigliato)
  - FPC installato nell'ambiente WSL

==== Attivazione ====

<code json>
{
  "wvds.toolchain.wslEnabled": true,
  "wvds.toolchain.wslDistribution": "Ubuntu-22.04"
}
</code>

==== Utilizzo ====

Con WSL attivato, viene utilizzato FPC Linux per i target Linux, mentre FPC Windows rimane attivo per i target Windows.

===== Verifica =====

Verificate l'installazione:

  - Aprite la palette dei comandi: ''Ctrl+Shift+P''
  - Eseguite: ''WVDS: Show Version Info''
  - L'Output Channel mostra tutti gli strumenti e le versioni rilevate

Output atteso (i percorsi variano in base all'installazione):
<code>
WvdS FPC RAD Studio v0.1.0
--------------------------
FPC: 3.2.2 (%LAZARUS%\fpc\3.2.2\bin\i386-win32\fpc.exe)
pas2js: 2.2.0 (%LAZARUS%\fpc\3.2.2\bin\i386-win32\pas2js.exe)
lazbuild: 3.4 (%LAZARUS%\lazbuild.exe)
Inno Setup: 6.2.2 (%PROGRAMFILES(X86)%\Inno Setup 6\ISCC.exe)
</code>

===== Risoluzione dei problemi =====

==== "FPC not found" ====

**Causa:** FPC non è installato o il percorso è errato.

**Soluzione:**
  - Installate FPC o Lazarus
  - Impostate ''wvds.toolchain.fpcPath'' manualmente
  - Assicuratevi che il percorso punti al file .exe/.bin, non alla cartella

==== "pas2js not found" ====

**Causa:** pas2js non è stato installato con Lazarus.

**Soluzione:**
  - Installate pas2js tramite il Lazarus Package Manager
  - Oppure scaricate pas2js manualmente
  - Impostate ''wvds.toolchain.pas2jsPath''

==== L'estensione non si avvia ====

**Causa:** Dipendenze non soddisfatte.

**Soluzione:**
  - Assicuratevi che ''wvds-vscode-core'' sia installata
  - Verificate la versione di VS Code (minimo 1.85.0)
  - Riavviate VS Code

==== La compilazione fallisce ====

**Causa:** Unit mancanti o percorsi errati.

**Soluzione:**
  - Controllate l'output FPC nel Terminal
  - Assicuratevi che tutti i percorsi delle unit siano corretti
  - Verificate le impostazioni del progetto

===== Prossimi passi =====

  * [[.:projects|Creare il primo progetto]]
  * [[.:build|Comprendere la configurazione di build]]
  * [[.:core|Core Extension nel dettaglio]]