====== WvdS VSCode Core ======

The Core extension forms the foundation of the WvdS FPC RAD Studio suite. It provides central services used by all other extensions.

===== Function and Purpose =====

The Core extension is **mandatory** for all other WvdS extensions. It provides:

  * **Toolchain Management** - Central management of all compiler paths
  * **Auto-Detection** - Automatic discovery of installed tools
  * **Shared Services** - Common services for logging, configuration, RPC
  * **WSL Integration** - Cross-compilation on Windows

===== Commands =====

^ Command ^ Keyboard Shortcut ^ Description ^
| ''WVDS: Toolchain Configuration...'' | - | Opens the toolchain configuration dialog |
| ''WVDS: Show Log'' | - | Shows the WvdS Output Channel |
| ''WVDS: Clear Log'' | - | Clears the log content |
| ''WVDS: Show Version Info'' | - | Shows version information for all components |
| ''WVDS: Hello'' | - | Test command to verify installation |

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

==== The Configuration Dialog ====

The dialog shows all supported tools in a clear table:

{{ :de:int:vsce:fpc:p:toolchain-dialog.png?600 |Toolchain Dialog}}

^ Column ^ Meaning ^
| Tool | Name of the tool |
| Status | Green = Found, Red = Not found, Yellow = Version outdated |
| Path | Current path to the executable |
| Version | Detected version |
| Actions | Buttons: Browse, Auto-Detect, Clear |

==== Auto-Detection ====

Auto-detection searches typical installation paths:

**Windows:**
  * ''%LAZARUS%\fpc\*''
  * ''%PROGRAMFILES%\Free Pascal\*''
  * ''%LOCALAPPDATA%\Programs\FPC\*''
  * PATH environment variable

**Linux:**
  * ''/usr/lib/fpc/*''
  * ''/usr/local/lib/fpc/*''
  * ''~/.fpc/*''
  * PATH environment variable

**macOS:**
  * ''/usr/local/lib/fpc/*''
  * ''/opt/homebrew/lib/fpc/*''
  * PATH environment variable

==== Supported Tools ====

^ Tool ^ File ^ Usage ^
| Free Pascal Compiler | fpc / fpc.exe | Native Pascal compilation |
| pas2js | pas2js / pas2js.exe | Pascal-to-JavaScript transpilation |
| lazbuild | lazbuild / lazbuild.exe | Compile Lazarus projects without IDE |
| Inno Setup | ISCC.exe | Create Windows installers |
| GNU make | make / make.exe | Execute Makefiles |

===== Settings =====

All settings begin with ''wvds.toolchain.'' or ''wvds.core.'':

==== Toolchain Settings ====

<code json>
{
  // Compiler paths
  "wvds.toolchain.fpcPath": "",
  "wvds.toolchain.pas2jsPath": "",
  "wvds.toolchain.lazbuildPath": "",
  "wvds.toolchain.innoSetupPath": "",
  "wvds.toolchain.makePath": "",

  // WSL configuration (Windows only)
  "wvds.toolchain.wslEnabled": false,
  "wvds.toolchain.wslDistribution": ""
}
</code>

==== Core Settings ====

<code json>
{
  // Log level: debug, info, warn, error
  "wvds.core.logLevel": "info"
}
</code>

^ Log Level ^ Description ^
| debug | All messages, including debug information |
| info | Information, warnings, errors |
| warn | Warnings and errors only |
| error | Errors only |

===== Logging =====

The Core extension provides a central logging service.

==== Output Channel ====

All WvdS extensions write to the shared Output Channel "WvdS".

To open:
  - ''View'' -> ''Output''
  - Select "WvdS" from the dropdown
  - Or: Run ''WVDS: Show Log''

==== Log Format ====

<code>
[2024-01-15 14:30:22] [INFO] Toolchain: FPC detected at %LAZARUS%\fpc\3.2.2\bin\i386-win32\fpc.exe
[2024-01-15 14:30:22] [INFO] Toolchain: Version 3.2.2
[2024-01-15 14:30:23] [WARN] Toolchain: pas2js not found in PATH
</code>

<note>The displayed paths correspond to the resolved values of your local environment.</note>

===== WSL Integration =====

On Windows, WSL integration enables cross-compilation for Linux.

==== Prerequisites ====

  - Windows 10/11 with WSL 2
  - A Linux distribution installed (e.g., Ubuntu)
  - FPC installed in the WSL environment

==== Setup ====

  - Install FPC in WSL: <code bash>
sudo apt update
sudo apt install fpc
</code>
  - Enable WSL in settings: <code json>
{
  "wvds.toolchain.wslEnabled": true,
  "wvds.toolchain.wslDistribution": "Ubuntu-22.04"
}
</code>
  - Restart VS Code

==== Usage ====

With WSL enabled, you can:
  * Create Linux binaries on Windows
  * Use Linux-specific units
  * Generate both targets (Windows + Linux) from one project

===== API for Extension Developers =====

Other extensions can use Core services. See [[..:i:core-api|Core API Reference]] for details.

===== Troubleshooting =====

==== Extension Is Not Activated ====

**Symptom:** "WVDS: Hello" shows no output.

**Solution:**
  - Check the VS Code Developer Console (''Help'' -> ''Toggle Developer Tools'')
  - Search for error messages containing "wvds"
  - Ensure VS Code >= 1.85.0

==== Toolchain Dialog Does Not Open ====

**Symptom:** The command shows no response.

**Solution:**
  - Check if the Core extension is activated
  - In Extensions: Search for "WvdS Core", check the status
  - Disable and re-enable the extension

==== Auto-Detection Finds Nothing ====

**Symptom:** All tools remain marked red.

**Solution:**
  - Verify the tools are actually installed
  - Ensure the paths are readable
  - Configure paths manually

===== Technical Details =====

^ Property ^ Value ^
| Extension ID | wvds.wvds-vscode-core |
| Activation | onStartupFinished |
| Dependencies | None |
| Min. VS Code | 1.85.0 |

===== See Also =====

  * [[.:installation|Installation and Configuration]]
  * [[.:build|Build Extension]]
  * [[.:projects|Projects Extension]]
  * [[..:i:core-api|Core API for Developers]] (Internal)