====== WvdS VSCode Build ======

The Build extension integrates the Free Pascal Compiler (FPC) and pas2js into VS Code. It enables compilation, cleanup, and uses-clause formatting directly from the editor.

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

The Build extension provides:

  * **FPC Integration** - Native Pascal compilation for desktop and server
  * **pas2js Integration** - Transpilation to JavaScript for web applications
  * **Problem Matcher** - Compiler errors are displayed in the Problems panel
  * **Uses Formatter** - Automatic formatting of uses clauses

===== Commands =====

^ Command ^ Keyboard Shortcut ^ Description ^
| ''WvdS: Build Project'' | ''Ctrl+Shift+B'' | Compiles the current project |
| ''WvdS: Clean Build'' | - | Deletes build artifacts |
| ''WvdS: Rebuild Project'' | - | Clean + Build in one step |
| ''WvdS: Format Uses Clauses'' | ''Ctrl+Alt+U'' | Formats uses clauses in the current file |
| ''WvdS: Remove Unused Units'' | - | Removes unused units from uses |

===== Build Workflow =====

==== Compiling a Project ====

  - Open a Pascal file (.pas, .lpr, .dpr)
  - Press ''Ctrl+Shift+B'' or run ''WvdS: Build Project''
  - The compiler runs in the Terminal
  - Errors appear in the Problems panel

==== Build Types ====

^ Type ^ Description ^ Usage ^
| Build | Incremental build, only changed units | Normal development |
| Clean | Deletes all .o, .ppu, .exe files | For problems, before release |
| Rebuild | Clean + Build | Complete recompilation |

==== Compiler Selection ====

The extension automatically selects the correct compiler:

^ File Extension ^ Compiler ^ Output ^
| .lpr, .pas (with .lpi) | FPC via lazbuild | Native Binary |
| .dpr, .dpk | FPC | Native Binary |
| .pas (with pas2js.cfg) | pas2js | JavaScript |

===== Uses Clause Formatter =====

The formatter organizes and cleans up uses clauses.

==== Features ====

  * **Sorting** - Alphabetical, by length, or none
  * **Grouping** - Optional: RTL, LCL, Custom Units
  * **Indentation** - Configurable indentation width
  * **Line Length** - Automatic wrapping when exceeded
  * **Unused Removal** - Removal of unused units

==== Example ====

**Before:**
<code pascal>
uses
  SysUtils,Classes,Forms, Dialogs,
    StdCtrls, Windows,
  MyUnit;
</code>

**After (alphabetical, 2 spaces, 80 characters):**
<code pascal>
uses
  Classes, Dialogs, Forms, MyUnit, StdCtrls, SysUtils, Windows;
</code>

==== Context Menu ====

Right-click in a Pascal file shows the "Uses Clauses" submenu:
  * Format Uses Clauses
  * Remove Unused Units

===== Settings =====

==== Build Settings ====

<code json>
{
  "wvds.build.fpcPath": "",
  "wvds.build.pas2jsPath": ""
}
</code>

<note>These settings are inherited from the Core extension if left empty.</note>

==== Uses Formatter Settings ====

<code json>
{
  // Sort order
  // "alphabetical" | "lengthAsc" | "lengthDesc" | "none"
  "wvds.usesFormatter.sortOrder": "alphabetical",

  // Indentation (number of spaces)
  "wvds.usesFormatter.indentSize": 2,

  // Maximum line length
  "wvds.usesFormatter.maxLineLength": 80,

  // Group by type (RTL, LCL, Custom)
  "wvds.usesFormatter.groupByType": false,

  // Automatically remove unused units
  "wvds.usesFormatter.removeUnused": false
}
</code>

==== Sorting Options in Detail ====

^ Option ^ Description ^ Example ^
| alphabetical | A-Z sorting (default) | Classes, Dialogs, Forms, SysUtils |
| lengthAsc | Shortest first | DB, Forms, Classes, SysUtils |
| lengthDesc | Longest first | SysUtils, Classes, Forms, DB |
| none | Keep original order | - |

==== Grouping ====

With grouping enabled (''groupByType: true''):

<code pascal>
uses
  // RTL
  Classes, SysUtils,
  // LCL
  Forms, StdCtrls,
  // Custom
  MyUnit, AnotherUnit;
</code>

===== Problem Matcher =====

The extension parses compiler output and shows errors in the Problems panel.

==== Supported Formats ====

**FPC Format:**
<code>
myunit.pas(42,10) Error: Identifier not found "TFoo"
</code>

**pas2js Format:**
<code>
myunit.pas(42,10) Error: identifier "TFoo" not found
</code>

==== Navigation ====

  * Click on an error to open the file at that location
  * ''F8'' jumps to the next error
  * ''Shift+F8'' jumps to the previous error

===== Per-Project Build Configuration =====

Create a ''build.cfg'' in the project folder for project-specific settings:

<code ini>
[build]
compiler=fpc
target=windows-x64
mode=debug

[debug]
optimizations=off
symbols=on
assertions=on

[release]
optimizations=3
symbols=off
assertions=off
</code>

==== Available Options ====

^ Option ^ Values ^ Description ^
| compiler | fpc, pas2js, lazbuild | Compiler to use |
| target | windows-x64, linux-x64, web, ... | Target platform |
| mode | debug, release | Build mode |
| optimizations | off, 1, 2, 3 | Optimization level |
| symbols | on, off | Generate debug symbols |
| assertions | on, off | Enable assertions |

===== Keyboard Shortcuts =====

^ Action ^ Windows/Linux ^ macOS ^
| Build Project | ''Ctrl+Shift+B'' | ''Cmd+Shift+B'' |
| Format Uses | ''Ctrl+Alt+U'' | ''Cmd+Alt+U'' |

===== Troubleshooting =====

==== "Compiler not found" ====

**Cause:** FPC/pas2js not configured.

**Solution:**
  - Open ''WvdS: Toolchain Configuration...''
  - Configure the compiler path
  - Alternatively: Set ''wvds.build.fpcPath'' in settings.json

==== Errors Not Shown in Problems Panel ====

**Cause:** Compiler output deviates from expected format.

**Solution:**
  - Check the Terminal output for errors
  - Ensure the compiler version is compatible
  - Report the issue on GitHub

==== Uses Formatter Does Nothing ====

**Cause:** No uses clause found or file not supported.

**Solution:**
  - Ensure the file is a .pas, .pp, .lpr, .dpr, or .inc
  - Check if a uses clause exists
  - Check the settings

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

^ Property ^ Value ^
| Extension ID | wvds.wvds-vscode-build |
| Activation | onCommand, onLanguage:pascal |
| Dependencies | wvds-vscode-core |
| Min. VS Code | 1.85.0 |

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

  * [[.:core|Core Extension - Toolchain Configuration]]
  * [[.:projects|Projects Extension - Project Templates]]
  * [[.:packaging|Packaging Extension - Create VSIX]]