====== Installation and Configuration ======

This guide describes the complete setup of WvdS FPC RAD Studio for VS Code.

===== Prerequisites =====

==== Visual Studio Code ====

Install VS Code from [[https://code.visualstudio.com/|code.visualstudio.com]]. Minimum version: 1.85.0.

Check your installed version:
<code>
code --version
</code>

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

**Option A: Lazarus Bundle (recommended)**

The Lazarus IDE includes FPC. Download: [[https://www.lazarus-ide.org/|lazarus-ide.org]]

Typical installation paths:
  * 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''

**Option B: Standalone FPC**

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

Verification:
<code bash>
fpc -iV
</code>
Expected output: ''3.2.2'' or higher.

==== pas2js (for Web Projects) ====

pas2js is the Pascal-to-JavaScript transpiler for browser and Node.js applications.

**Installation via Lazarus:**

Search for "pas2js" in the Lazarus Online Package Manager and install it.

**Manual Installation:**

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

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

==== Optional Tools ====

^ Tool ^ Usage ^ Download ^
| lazbuild | Compile Lazarus projects (.lpi) without IDE | Included in Lazarus |
| Inno Setup | Create Windows installers | [[https://jrsoftware.org/isinfo.php|jrsoftware.org]] |
| GNU make | Execute Makefiles | Included in MinGW/MSYS2 |

===== Extension Installation =====

==== Method 1: VS Code Marketplace ====

  - Open VS Code
  - Click on the Extensions icon (''Ctrl+Shift+X'')
  - Search for "WvdS FPC"
  - Install the desired extensions:
    * **WvdS VSCode Core** - Required
    * **WvdS VSCode Build** - Recommended
    * **WvdS VSCode Projects** - Recommended
    * **WvdS VSCode UI Designer** - For PXAML development
    * **WvdS VSCode UI Meta** - For IntelliSense
    * **WvdS VSCode UI Preview** - For live preview
    * **WvdS VSCode Packaging** - For VSIX creation

==== Method 2: Command Line ====

<code bash>
# Basic installation
code --install-extension wvds.wvds-vscode-core
code --install-extension wvds.wvds-vscode-build
code --install-extension wvds.wvds-vscode-projects

# UI development
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>

==== Method 3: VSIX File ====

For offline installation or internal distribution:

  - Download the .vsix files
  - In VS Code: ''Extensions'' -> ''...'' -> ''Install from VSIX...''
  - Select the .vsix file

===== Toolchain Configuration =====

After installing the Core extension, the compiler paths must be configured.

==== Automatic Detection ====

The suite attempts to automatically find installed tools:

  - Open the Command Palette: ''Ctrl+Shift+P''
  - Run: ''WvdS: Toolchain Configuration...''
  - The dialog shows detected tools with green checkmarks
  - Tools not found are marked in red

==== Manual Configuration ====

If automatic detection fails, paths can be set manually:

**Via Settings UI:**

''File'' -> ''Preferences'' -> ''Settings'' -> Search for "wvds.toolchain"

**Via settings.json:**

<note tip>Use environment variables instead of absolute paths for better portability.</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>

==== Settings in Detail ====

^ Setting ^ Description ^ Default ^
| ''wvds.toolchain.fpcPath'' | Path to fpc.exe / fpc | Auto-detection |
| ''wvds.toolchain.pas2jsPath'' | Path to pas2js.exe / pas2js | Auto-detection |
| ''wvds.toolchain.lazbuildPath'' | Path to lazbuild.exe / lazbuild | Auto-detection |
| ''wvds.toolchain.innoSetupPath'' | Path to ISCC.exe | Auto-detection |
| ''wvds.toolchain.makePath'' | Path to make.exe / make | Auto-detection |
| ''wvds.toolchain.wslEnabled'' | WSL for Linux cross-compilation | false |
| ''wvds.toolchain.wslDistribution'' | WSL distribution (e.g. Ubuntu-22.04) | "" |

===== WSL Support (Windows) =====

For cross-compilation on Windows, WSL can be enabled:

==== Prerequisites ====

  - WSL 2 with a Linux distribution installed (Ubuntu recommended)
  - FPC installed in the WSL environment

==== Activation ====

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

==== Usage ====

With WSL enabled, the Linux FPC is used for Linux targets, while the Windows FPC remains active for Windows targets.

===== Verification =====

Verify your installation:

  - Open the Command Palette: ''Ctrl+Shift+P''
  - Run: ''WVDS: Show Version Info''
  - The Output Channel shows all detected tools and versions

Expected output (paths vary by installation):
<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>

===== Troubleshooting =====

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

**Cause:** FPC is not installed or the path is incorrect.

**Solution:**
  - Install FPC or Lazarus
  - Set ''wvds.toolchain.fpcPath'' manually
  - Ensure the path points to the .exe/.bin, not the folder

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

**Cause:** pas2js was not installed with Lazarus.

**Solution:**
  - Install pas2js via the Lazarus Package Manager
  - Or download pas2js manually
  - Set ''wvds.toolchain.pas2jsPath''

==== Extension Does Not Start ====

**Cause:** Dependencies not met.

**Solution:**
  - Ensure ''wvds-vscode-core'' is installed
  - Check VS Code version (minimum 1.85.0)
  - Restart VS Code

==== Compilation Fails ====

**Cause:** Missing units or incorrect paths.

**Solution:**
  - Check the FPC output in the Terminal
  - Ensure all unit paths are correct
  - Check project settings

===== Next Steps =====

  * [[.:projects|Create Your First Project]]
  * [[.:build|Understanding Build Configuration]]
  * [[.:core|Core Extension in Detail]]