====== Development Environment ======

Overview of the project structure and important paths for WvdS FPC RAD Studio.

<note>**Tilde (~)** represents the repository root (e.g. ''%WORKSPACE%/WvdS.FPC''). All paths use forward slashes.</note>

===== Project Structure =====

<code>
~/
├── sources/                    # SSOT - version controlled (SVN)
│   ├── common/                 # Shared Units/Libs (FPC + pas2js)
│   │   ├── core/               # Base units (no UI)
│   │   ├── ui/                 # UI Framework
│   │   │   ├── controls/       # Base controls
│   │   │   ├── components/     # Composite components
│   │   │   ├── runtime/        # PXAML Runtime
│   │   │   └── targets/        # Renderers (tui/gui/web)
│   │   └── web/                # Host Bridges (pas2js only)
│   │       ├── nodejs/         # Node.js APIs
│   │       └── vscode/         # VSCode Extension APIs
│   ├── extensions/             # VSIX Packs
│   ├── applications/           # Products/Demos
│   ├── tools/                  # wvds-build, pxamlc
│   └── packages/               # IDE Packages
│
├── binaries/                   # Build Outputs - NOT version controlled
│   ├── out/                    # Build outputs
│   ├── cache/                  # Compiler caches
│   ├── dist/                   # Release artifacts (.vsix)
│   └── logs/                   # Build reports, debug logs
│
└── assets/                     # Static assets
</code>

===== Project Paths =====

^ Variable ^ Path ^ Description ^
| ''~'' | Repository root | ''%WORKSPACE%/WvdS.FPC'' |
| ''~/sources'' | Source code | Single Source of Truth |
| ''~/sources/common'' | Shared code | FPC + pas2js compatible |
| ''~/sources/extensions'' | VSIX Extensions | VSCode packages |
| ''~/sources/applications'' | Applications | RAD Suite, Demos |
| ''~/binaries'' | Build output | Disposable, regenerable |
| ''~/binaries/dist'' | Release | .vsix, installers |
| ''~/binaries/logs'' | Logs | Build reports, debug logs |
| ''~/assets'' | Assets | Icons, templates |

===== Environment Variables =====

<note tip>These variables are **placeholders** and must be adapted to the local development environment. Absolute paths should be avoided in configuration files.</note>

^ Variable ^ Default Value ^ Description ^
| ''%LAZARUS%'' | Lazarus installation | e.g. ''C:\Lazarus'' or ''/opt/lazarus'' |
| ''%PROGRAMFILES%'' | Program Files | Windows: ''C:\Program Files'' |
| ''%USERPROFILE%'' | User directory | Windows: ''C:\Users\{name}'', Linux: ''~'' |
| ''%WORKSPACE%'' | Working directory | User-defined, e.g. ''E:\Workspace'' |

===== Compiler and Toolchain =====

^ Variable ^ Relative Path ^ Description ^
| FPC | ''%LAZARUS%/fpc/3.3.1/bin'' | Free Pascal Compiler |
| FPC-SRC | ''%LAZARUS%/fpc/3.3.1/source'' | FPC Source code |
| PAS2JS | ''%LAZARUS%/fpc/3.3.1/bin/pas2js.exe'' | Pascal to JavaScript |
| P2J-RTL | ''%LAZARUS%/fpc/pas2js-windows-2.2.0/packages/rtl'' | pas2js RTL |
| P2J-NODE | ''%LAZARUS%/fpc/pas2js-windows-2.2.0/packages/nodejs'' | Node.js Bindings |
| P2J-VSCODE | ''%LAZARUS%/fpc/pas2js-windows-2.2.0/packages/vscode'' | VSCode Bindings |

===== External References =====

<note>These paths are **optional** and only relevant for developers who want to study reference implementations.</note>

^ Variable ^ Relative Path ^ Description ^
| DXVCL | ''%WORKSPACE%/3rd/DevExpress/VCL'' | DevExpress VCL (Delphi) |
| DXNET | ''%PROGRAMFILES%/DevExpress 25.1/Components/Sources'' | DevExpress .NET |
| NODEJS-SRC | ''%WORKSPACE%/3rd/node-main'' | Node.js Source code |
| VSCODE-SRC | ''%WORKSPACE%/3rd/vscode-main'' | VSCode Source code |

===== Documentation =====

^ Variable ^ Relative Path ^ Description ^
| DOKUWIKI | ''%DOKUWIKI_DATA%/pages/de/int/vsce/fpc'' | DokuWiki Pages |
| SKILLS | ''%WORKSPACE%/WvdS.Rihtlinien'' | Skill definitions |

===== SSOT Rules =====

<note warning>**Single Source of Truth** - These rules are binding!</note>

  - **''~/sources/''** is the only source for version-controlled code
  - **''~/binaries/''** is completely disposable and regenerable
  - **Never** duplicate runtime code in ''~/sources/extensions/''
  - **Never** commit generated files to ''~/sources/''

===== Build Output Structure =====

<code>
~/binaries/out/{app}/{target}/{mode}/
├── gen/              # Generated code (ui.generated.pas)
├── bin/              # Executables / JS Bundle
├── assets/           # PXAML, Images, Themes
├── build-plan.json   # Build configuration
└── build-report.md   # Build log
</code>

^ Target ^ Compiler ^ Output ^
| ''tui'' | FPC | Native Console (Windows/Linux) |
| ''gui'' | FPC | Native Desktop (LCL/WinAPI) |
| ''web'' | pas2js | JavaScript Bundle |

^ Mode ^ Description ^
| ''debug'' | Debug symbols, no optimization |
| ''release'' | Optimized, stripped symbols |
| ''profile'' | Release + Profiling |

===== Extension Structure =====

<code>
~/sources/extensions/wvds.vscode.{name}/
├── pas/
│   ├── extension_main.pas     # Entry Point (REQUIRED)
│   ├── {Feature}.Models.pas   # Data structures
│   ├── {Feature}.Service.pas  # Business logic
│   └── {Feature}.Dialog.pas   # UI (optional)
│
├── dist/
│   ├── extension_main.js      # Compiled JS
│   └── extension_main.js.map  # Source Map
│
├── templates/                  # WebView Templates
├── images/                     # Icons
├── package.json               # VSCode Manifest
├── build.cfg                  # Build configuration
└── README.md                  # Documentation
</code>

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

  * [[.:architektur|Architecture Overview]]
  * [[.:build-pipeline|Build Pipeline]]
  * [[.:extension-entwicklung|Extension Development]]