====== WvdS VSCode Projects ======

The Projects extension manages Pascal projects in VS Code. It provides project templates, configuration dialogs, and solution management.

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

The Projects extension enables:

  * **Project Templates** - Quick creation of new projects
  * **Project Management** - Open, configure, manage
  * **Multi-Project Solutions** - Multiple projects in one workspace
  * **Project Settings** - GUI for compiler options

===== Commands =====

^ Command ^ Description ^
| ''WvdS Projects: New Project (Quick)'' | Creates a project with default settings |
| ''WvdS Projects: New Project from Template...'' | Shows the template selection dialog |
| ''WvdS Projects: Open Project'' | Opens an existing project |
| ''WvdS Projects: Project Settings...'' | Opens the project settings dialog |

===== Project Templates =====

The extension includes predefined templates for various project types:

==== Desktop Console ====

Simple console application for command-line tools and services.

**Generated Files:**
<code>
MyProject/
  MyProject.lpr     -- Main program
</code>

**Example Code:**
<code pascal>
program MyProject;

{$mode objfpc}{$H+}

uses
  SysUtils;

begin
  WriteLn('Hello, World!');
end.
</code>

**Use Cases:**
  * CLI tools and utilities
  * Batch processing
  * Server services
  * Build scripts

==== Desktop GUI ====

Native desktop application with LCL (Lazarus Component Library).

**Generated Files:**
<code>
MyProject/
  MyProject.lpr     -- Main program
  MainForm.pas      -- Main form unit
  MainForm.lfm      -- Form design
</code>

**Prerequisites:**
  * Lazarus installed (for LCL)
  * lazbuild available

**Use Cases:**
  * Desktop applications
  * Database frontends
  * Utility programs with GUI

==== Desktop Library ====

Shared library (DLL/SO) for plugin systems or external integration.

**Generated Files:**
<code>
MyProject/
  MyProject.lpr     -- Library project
</code>

**Example Code:**
<code pascal>
library MyProject;

{$mode objfpc}{$H+}

uses
  SysUtils;

procedure HelloWorld; cdecl;
begin
  WriteLn('Hello from library!');
end;

exports
  HelloWorld;

begin
end.
</code>

**Use Cases:**
  * Plugins for other applications
  * Shared code between projects
  * Integration with other languages (C, Python, etc.)

==== TUI App ====

Terminal User Interface - text-based user interface.

**Generated Files:**
<code>
MyProject/
  MyProject.lpr     -- Main program
  TuiMain.pas       -- TUI main unit
</code>

**Use Cases:**
  * Server administration
  * SSH-capable tools
  * Resource-efficient applications
  * Cross-platform without GUI dependencies

==== Web PWA ====

Progressive Web App with pas2js - runs in the browser.

**Generated Files:**
<code>
MyProject/
  MyProject.lpr     -- Main program (becomes JS)
  index.html.tmpl   -- HTML template
  manifest.json.tmpl-- PWA manifest
  sw.js             -- Service Worker
</code>

**Prerequisites:**
  * pas2js installed

**Use Cases:**
  * Web applications
  * Cross-platform apps
  * Offline-capable applications

==== VSCode Extension ====

VS Code extension in Pascal, transpiled with pas2js.

**Generated Files:**
<code>
MyExtension/
  extension_main.pas   -- Entry point
  package.json.tmpl    -- Extension manifest
</code>

**Prerequisites:**
  * pas2js installed
  * Node.js for vsce (packaging)

**Use Cases:**
  * Custom VS Code extensions
  * IDE tools and automation
  * Integration with WvdS Suite

==== Installer (Inno Setup) ====

Windows installer for desktop applications.

**Generated Files:**
<code>
MyInstaller/
  MyInstaller.iss    -- Inno Setup script
</code>

**Prerequisites:**
  * Inno Setup installed

**Use Cases:**
  * Windows installation packages
  * Automatic updates
  * Enterprise deployment

===== Project Settings =====

The ''WvdS Projects: Project Settings...'' dialog provides a graphical interface for:

==== General Settings ====

  * **Project Name** - Name of the project
  * **Output Directory** - Where compiled files are written
  * **Unit Paths** - Additional search paths for units

==== Compiler Options ====

  * **Target Platform** - windows-x86, windows-x64, linux-x64, ...
  * **Optimizations** - Level 0-3
  * **Debug Symbols** - Enable for debugging
  * **Assertions** - Runtime checks

==== Dependencies ====

  * **Uses Clauses** - Automatically managed units
  * **Library Paths** - Paths to external libraries

===== Multi-Project Workspaces =====

VS Code workspaces can contain multiple projects:

<code>
MyWorkspace.code-workspace
  MyApp/          -- Desktop application
  MyLib/          -- Shared library
  MyTests/        -- Unit tests
</code>

==== Creating a Workspace ====

  - ''File'' -> ''Add Folder to Workspace...''
  - Add all project folders
  - ''File'' -> ''Save Workspace As...''

==== Selecting a Project ====

With multiple projects:
  - Open a file from the desired project
  - Or: Select the project in the Project Explorer

===== Context Menu =====

Right-click on .lpi/.lpr files in the Explorer shows:

  * ''WvdS Projects: Project Settings...''

===== Troubleshooting =====

==== Template Dialog Does Not Open ====

**Cause:** Extension not activated or error.

**Solution:**
  - Check if the extension is installed
  - Check the Developer Console for errors
  - Restart VS Code

==== Project Not Recognized ====

**Cause:** No .lpr, .dpr, or .pas file in the folder.

**Solution:**
  - Ensure a main file exists
  - Open the folder with ''File'' -> ''Open Folder...''

==== Project Settings Not Saved ====

**Cause:** No write permissions or faulty configuration.

**Solution:**
  - Check write permissions in the project folder
  - Check settings.json for syntax errors

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

^ Property ^ Value ^
| Extension ID | wvds.wvds-vscode-projects |
| Activation | workspaceContains:/*.lpr, onLanguage:pascal |
| Dependencies | wvds-vscode-core |
| Min. VS Code | 1.85.0 |

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

  * [[.:core|Core Extension - Toolchain Configuration]]
  * [[.:build|Build Extension - Compiling]]
  * [[.:designer|UI Designer - PXAML Development]]