====== FPC Solution Manager ======

Upravljanje projektov, Build-System, Debugging in Form Designer za Free Pascal / Lazarus v Visual Studio Code.

**Package-ID:** ''wvds.wvds-fpc-solution-manager''

===== Pregled =====

Solution Manager je osrednja razširitev za razvoj v Free Pascalu v VSCode. Ponuja:

  * **Tree View** — Hierarhični prikaz projektnih skupin, projektov, enot in obrazcev
  * **Build-System** — Build, Rebuild, Clean prek ''lazbuild'' ali FPC Direct
  * **Form Designer** — Vizualni LFM-urejevalnik s podporo za skine
  * **Debugger** — Integrirano razhroščevanje z ''fpdserver'' / GDB
  * **Language Server** — Code Completion, Go to Definition, Hover prek ''pasls''
  * **Code Formatter** — ''ptop'' ali ''jcf'' integracija

===== Odkrivanje projektov =====

Razširitev samodejno odkrije projekte v odprtem Workspace:

| Datoteka | Vrsta projekta |
^ ''.lpi'' | Lazarus-projekt (konzola, GUI, knjižnica) |
^ ''.lpg'' | Projektna skupina (več projektov) |
^ ''.lpk'' | Lazarus-paket |
^ ''package.json'' | VSCode Extension (pas2js, virtualni projekt) |
^ ''.iss'' | InnoSetup Installer-skripta |

Multi-Root Workspaces so podprti — vsaka mapa Workspace se pregleda ločeno.

===== Tree View =====

Tree View se pojavi v Activity Bar (leva stran) z ikono FPC Solution Manager.

==== Hierarhija ====

<code>
Workspace Folder
├── Projektna skupina (.lpg)
│   ├── Projekt (.lpi)        ← z Inline Build/Run gumbi
│   │   ├── Enote (.pas)
│   │   ├── Obrazci (.pas + .lfm)
│   │   ├── Build načini (Debug, Release, ...)
│   │   ├── Odvisnosti (Required Packages)
│   │   └── Viri (.rc)
│   └── Projekt 2 ...
├── Paket (.lpk)
│   ├── Enote
│   └── Required Packages
├── Extension (package.json)  ← Virtualni pas2js-projekt
│   ├── Enote
│   └── npm Dependencies
└── Setup (.iss)              ← InnoSetup projekt
    └── Sekcije ([Files], [Run], ...)
</code>

==== Kontekstni meni ====

Desni klik na elemente drevesa prikaže kontekstno odvisna dejanja:

**Projekt:**
  * Build / Rebuild / Clean
  * Build and Run / Run / Stop
  * Properties (F4)
  * Select Build Mode
  * Add Unit / Form / Existing File
  * Navigate (Dependencies, Call Hierarchy)

**Projektna skupina:**
  * Build All / Rebuild All / Clean All
  * Set Active Project
  * Add New/Existing Project

**Enota / Obrazec:**
  * Open File (Enter)
  * Reveal in File Explorer
  * Copy Path / Copy Relative Path
  * Remove from Project
  * Show Dependencies / Call Hierarchy

==== Kontekstni meni urejevalnika ====

Desni klik v Pascal-urejevalniku (''.pas'', ''.pp'', ''.lpr'') prikaže podmeni **FPC Solution Manager**:

  * Sort and Remove Unused Units
  * Show Call Hierarchy
  * Show Dependency Explorer
  * Add Watch (le pri izbiri)

===== Build-System =====

==== Build-načini ====

Vsak projekt ima lahko več build-načinov:

| Način | Opis |
^ Debug | Informacije za razhroščevanje, brez optimizacije |
^ Release | Optimizirano, brez informacij za razhroščevanje |
^ Custom | Uporabniško definirane možnosti prevajalnika |

Zamenjava build-načina: Desni klik na projekt → **Select Build Mode** ali ''Ctrl+Shift+M''.

==== Build-ukazi ====

| Ukaz | Opis | Bližnjica |
^ Build Project | Inkrementalni build | ''Ctrl+Shift+B'' |
^ Rebuild Project | Celotna ponovna gradnja | ''Shift+F9'' |
^ Clean Project | Brisanje build-artefaktov | ''Ctrl+Shift+C'' |
^ Build and Run | Prevedi in zaženi | ''F9'' |
^ Compile (Syntax Check) | Samo preverjanje sintakse, brez povezovanja | — |
^ Build All | Prevedi vse projekte v skupini | — |
^ Build in Dependency Order | Prevedi projekte po odvisnostih | — |

==== Pre/Post-Build ukazi ====

V nastavitvah lahko definirate lupinske ukaze, ki se zaženejo pred/po vsakem buildu:

<code>
fpc-solution-manager.preBuildCommand: "echo Building {projectName} in {buildMode}"
fpc-solution-manager.postBuildCommand: "copy {outputPath} D:\\Deploy\\"
</code>

Razpoložljive spremenljivke: ''{projectName}'', ''{buildMode}'', ''{projectDir}'', ''{outputPath}''

===== Zagon projektov =====

| Ukaz | Bližnjica | Opis |
^ Run Project | ''F5'' | Zaženi prevedeni program |
^ Build and Run | ''F9'' | Prevedi in takoj zaženi |
^ Stop Process | ''Shift+F5'' / ''Ctrl+F2'' | Prekini tekoči proces |

===== Razhroščevanje =====

==== Predpogoji ====

Razhroščevalnik potrebuje ''fpdserver'' (Free Pascal Debug Server) kot zaledje.

**Pridobitev fpdserver:**

  * **Lazarus-Bundle (od 3.0):** ''fpdserver'' je že vključen (''<lazarus>/tools/fpdserver'')
  * **Ročna gradnja:** Iz izvorne kode FPC:

<code bash>
cd <fpc-source>/packages/fcl-passrc/utils/fpdserver
lazbuild --bm=Release fpdserver.lpi
</code>

**Nastavitev:**

  * ''fpc-solution-manager.fpdserverPath'' — Pot do ''fpdserver.exe'' (prazno = samodejna zaznava)

<note>Brez ''fpdserver'' integracija razhroščevanja ne deluje. Razširitev samodejno išče v namestitvenem imeniku Lazarusa.</note>

==== launch.json ====

Ustvarite ''launch.json'' v mapi ''.vscode'' delovnega prostora:

<code javascript>
{
  "type": "lazarus",
  "request": "launch",
  "name": "Debug MyApp",
  "program": "${command:fpcse2.getExecutablePath}",
  "cwd": "${workspaceFolder}",
  "stopOnEntry": false,
  "args": []
}
</code>

**Namig:** ''${command:fpcse2.getExecutablePath}'' samodejno določi izhodno pot iz nastavitev projekta.

==== Konfiguracijski atributi ====

| Atribut | Tip | Opis | Privzeto |
^ ''program'' | String | Pot do prevedenega programa (obvezno) | — |
^ ''cwd'' | String | Delovni imenik | ''${workspaceFolder}'' |
^ ''args'' | Array | Argumenti ukazne vrstice | ''[]'' |
^ ''stopOnEntry'' | Boolean | Ustavi se ob zagonu programa | ''false'' |

==== Funkcionalnosti ====

  * **Breakpoints** v ''.pas'' in ''.inc'' datotekah
  * **Step In/Out/Over** — Koračno izvajanje
  * **Variables** — Pregled lokalnih in globalnih spremenljivk
  * **Watches** — Spremljanje izrazov (''Ctrl+Alt+W'' pri izbiri)
  * **Call Stack** — Prikaz klicne verige
  * **Immediate Window** — Vrednotenje izrazov med izvajanjem

==== Točke prekinitve ====

  * **Vrstične točke prekinitve** — Klik na rob vrstice v ''.pas'' in ''.inc'' datotekah
  * **Pogojne točke prekinitve** — Desni klik na točko prekinitve → ''Edit Breakpoint'' → vnesite pogoj (npr. ''i > 100'')
  * **Števec zadetkov** — Točka prekinitve se sproži šele po N zadetkih
  * **Logpoints** — Izpis sporočila v konzolo brez prekinitve programa

==== Watches ====

Spremljanje izrazov med izvajanjem:

  * **Dodajanje:** ''Ctrl+Alt+W'' pri izbranem besedilu v Pascal-urejevalniku
  * **Panel:** V spodnjem delu pod **FPC Solution Manager → Watches**
  * **Izrazi:** Spremenljivke, polja zapisov (''MyRecord.Field''), indeksi polj (''MyArray[0]'')

==== Immediate Window ====

Interaktivno vrednotenje med sejo razhroščevanja:

  * **Odpri:** Panel **FPC Solution Manager → Immediate**
  * Vnesite izraz in pritisnite ''Enter''
  * Podpira: vrednosti spremenljivk, pretvorbe tipov, preproste aritmetične izraze

==== Paneli za razhroščevanje ====

V spodnjem panelu (področje FPC):

  * **Immediate** — Interaktivno vrednotenje izrazov
  * **Watches** — Spremljani izrazi/spremenljivke

==== Build-način za razhroščevanje ====

Za uspešno razhroščevanje mora biti projekt zgrajen v načinu **Debug**:

  * Zamenjava build-načina: ''Ctrl+Shift+M'' → **Debug**
  * Informacije za razhroščevanje: zastavice prevajalnika ''-g -gl -gw'' morajo biti aktivne
  * Izklop optimizacije: brez ''-O2'' v načinu Debug

==== Odpravljanje težav ====

| Težava | Rešitev |
^ fpdserver ni najden | Nastavite ''fpc-solution-manager.fpdserverPath'' ali zgradite ''fpdserver'' (glejte zgoraj) |
^ Točke prekinitve se ne sprožijo | Zgradite projekt v načinu **Debug** (''Ctrl+Shift+M'' → Debug) |
^ Spremenljivke niso vidne | Preverite informacije za razhroščevanje: ''-g -gl -gw'' morajo biti nastavljene |
^ Korakanje nepričakovano skoči | Izklopite optimizacijo: ''-O2'' uporabljajte le v načinu Release |

===== Form Designer =====

Form Designer se samodejno odpre za ''.lfm'' datoteke.

==== Uporaba ====

| Dejanje | Bližnjica |
^ Toggle Form/Code | ''F12'' |
^ View Form as Text | ''Alt+F12'' |
^ Select Designer Skin | Command Palette |

==== Skini ====

Designer podpira skine za vizualni izgled:

  * ''fpc-solution-manager.designer.skinName'' — Aktivni skin (npr. ''WvdS-Shell'')
  * ''fpc-solution-manager.designer.skinVariant'' — Varianta (npr. ''Amber'', ''Plum'')
  * ''fpc-solution-manager.designer.defaultSkinAutoDetect'' — Samodejna Light/Dark zaznava glede na VSCode-temo

===== Custom Editors =====

| Urejevalnik | Vrsta datoteke | Opis |
^ Form Designer | ''.lfm'' | Vizualni Lazarus-urejevalnik obrazcev |
^ PO Translation Editor | ''.po'' | Urejevalnik prevodov za lokalizacijo |
^ Resource Editor | ''.rc'' | Urejevalnik virov (ikone, bitne slike, nizi) |

==== PO Translation Editor ====

Odpre se za ''.po'' datoteke (GNU gettext). Ponuja:

  * Tabelarični prikaz vseh prevodnih vnosov (izvirnik → prevod)
  * Iskanje in filtriranje po ključu ali besedilu
  * Neposredno urejanje prevodov v WebView-panelu
  * Spremembe se zapišejo nazaj v ''.po'' datoteko

==== Resource Editor ====

Odpre se za ''.rc'' datoteke. Ponuja:

  * Pregled vseh virov (ikone, bitne slike, kazalci, tabele nizov, informacije o različici)
  * Dodajanje in odstranjevanje vnosov virov
  * Urejanje poti do datotek virov

===== Language Server (pasls) =====

Opcijska integracija Pascal Language Serverja za napredne funkcije kode.

==== Aktivacija ====

  * ''fpc-solution-manager.pasls.enabled'' — ''true'' (privzeto)
  * ''fpc-solution-manager.paslsPath'' — Pot do ''pasls.exe'' (prazno = samodejna zaznava)
  * ''fpc-solution-manager.lazarusSourcePath'' — Lazarus-izvorna koda za razreševanje simbolov

==== Funkcionalnosti ====

| Funkcionalnost | Tipka | Opis |
^ Code Completion | ''Ctrl+Space'' | Dopolnjevanje identifikatorjev, metod, enot |
^ Signature Help | samodejno | Seznam parametrov ob tipkanju ''('' |
^ Go to Definition | ''F12'' | Skok na definicijo/implementacijo simbola |
^ Go to Declaration | ''Ctrl+Click'' na vmesnik | Skok na deklaracijo v vmesniku (ne na implementacijo) |
^ Go to Implementation | ''Ctrl+Shift+F12'' | Skok na implementacijo (interno delegira na Definition) |
^ Document Symbols | ''Ctrl+Shift+O'' | Seznam simbolov trenutne datoteke — metode in procedure (Outline) |
^ Workspace Symbols | ''Ctrl+T'' | Iskanje simbolov v vseh datotekah delovnega prostora |
^ Find All References | ''Shift+F12'' | Iskanje vseh uporab simbola v delovnem prostoru |
^ Document Highlight | samodejno | Poudarjanje vseh pojavitev identifikatorja v trenutni datoteki |
^ Hover s tipsko informacijo | miškin kazalec | Signatura + PasDoc-dokumentacija + izvorna pozicija (glej spodaj) |

==== Hover s tipsko informacijo in PasDoc ====

Ko se z miško pomaknete nad simbol, hover-tooltip prikaže do tri ravni informacij:

  - **Signatura** — Popolna deklaracija kot sintaktično poudarjen Pascal blok kode, pridobljena iz CodeTools ''FindSmartHint'' (npr. ''private procedure TMyClass.DoSomething(const A: Integer): Boolean'') — vključno z vidnostjo, imenom razreda, modifikatorji parametrov in tipom vrnitve
  - **PasDoc-dokumentacija** — Komentarji v obliki ''(** @abstract(...) @param(...) @returns(...) *)'' neposredno iz izvorne kode, oblikovani kot Markdown
  - **Izvorna pozicija** — Ime datoteke in vrstična pozicija deklaracije (npr. ''MyUnit.pas(42,5)'')

pasls zagotavlja ''textDocument/hover'' in interno uporablja CodeTools ''FindSmartHint'' (enak mehanizem kot Lazarus IDE) za ekstrakcijo signatur. PasDoc-komentarji se preberejo prek ''GetPasDocComments'' in se na strežniški strani oblikujejo v Markdown. Če pasls ni na voljo, razširitev uporabi ''textDocument/definition'' kot nadomestek s klientskim večvrstičnim izločevanjem.

**Primer hover-a:**

<code>
┌───────────────────────────────────────────────────────────┐
│ private procedure TMyClass.DoSomething(const A: Integer); │  ← Signatura (FindSmartHint)
│ ───────────────────────────────────────────────────────── │
│ Izvede akcijo.                                            │  ← @abstract
│                                                           │
│ Parameters:                                               │
│ - A — Vrednost                                            │  ← @param
│ ───────────────────────────────────────────────────────── │
│ Source: MyUnit.pas(42,5)                                  │  ← Izvorna pozicija
└───────────────────────────────────────────────────────────┘
</code>

**Podprte PasDoc-oznake:**

| Oznaka | Opis | Primer |
^ ''@abstract'' | Kratek opis | ''@abstract(Izračuna kontrolno vsoto)'' |
^ ''@param'' | Dokumentacija parametra | ''@param(Buffer Podatki za preverjanje)'' |
^ ''@returns'' | Vrnjena vrednost | ''@returns(CRC32-vrednost kot Cardinal)'' |
^ ''@raises'' | Izjeme | ''@raises(EInvalidOperation Ob praznem bufferju)'' |

<note>PasDoc-komentarji se začnejo z ''(**'' (dvojna zvezdica). Navadni ''(*'' komentarji se ne prikažejo kot dokumentacija.</note>

==== Načrtovane funkcionalnosti ====

Naslednje funkcionalnosti zahtevajo strežniško podporo pasls in trenutno še **niso na voljo**:

  * **Rename Symbol** (''F2'') — Preimenovanje simbola v vseh datotekah. Zahteva ''textDocument/rename'' v pasls.
  * **Live Diagnostics** — Napake in opozorila med tipkanjem. Zahteva globlje vključevanje CodeTools v pasls.

<note>Razširitev že registrira ponudnika za Rename. Ko bo pasls podprl ''textDocument/rename'', bo funkcionalnost samodejno delovala.</note>

==== Workspace Symbols ====

''Ctrl+T'' odpre iskalnik simbolov delovnega prostora. Tu je mogoče iskati procedure, funkcije, tipe in spremenljivke v vseh datotekah delovnega prostora.

  * Vtipkajte iskalni izraz → pasls vrne ustrezne simbole
  * ''Enter'' navigira neposredno na mesto definicije
  * Prazno iskanje → prazen seznam (brez napake)

===== Code Formatter =====

| Nastavitev | Opis | Privzeto |
^ ''formatter.engine'' | ''ptop'', ''jcf'' ali ''none'' | ''ptop'' |
^ ''formatter.formatOnSave'' | Samodejno oblikovanje ob shranjevanju | ''false'' |

===== Cross-Compilation (WSL) =====

Linux-buildi na Windows prek WSL (Windows Subsystem for Linux).

==== Predpogoji ====

  - **Namestitev WSL:** ''wsl --install'' v PowerShell (skrbnik)
  - **Izbira distribucije:** npr. ''Ubuntu'' (privzeto) ali ''Debian''
  - **Namestitev FPC v WSL:**

<code bash>
# V WSL:
sudo apt install fpc lazarus
</code>

==== Aktivacija ====

  * ''fpc-solution-manager.wslEnabled'' — ''true''
  * ''fpc-solution-manager.wslActiveDistro'' — WSL-distribucija (npr. ''Ubuntu'')
  * ''fpc-solution-manager.wslLazbuildPath'' — Linux-pot do ''lazbuild'' (npr. ''/usr/bin/lazbuild'')
  * ''fpc-solution-manager.wslFpcPath'' — Linux-pot do ''fpc''

==== Ukazi ====

  * **Select Cross-Compile Target** — Izberi ciljno platformo (x86_64-linux, i386-linux, aarch64-linux)
  * **Configure WSL** — Odpri nastavitve WSL
  * **Build for Linux (WSL)** — Zaženi Linux-build

==== Potek ====

  - Izbira ciljne platforme: Desni klik na projekt → **Select Cross-Compile Target**
  - Zagon builda: **Build for Linux (WSL)** ali ''Ctrl+Shift+B'' (ko je WSL-cilj aktiven)
  - Razširitev preda build ''lazbuild'' / ''fpc'' znotraj WSL-instance
  - Izhodne datoteke pristanejo v nastavljeni izhodni poti

===== Raziskovalec odvisnosti =====

**Show Dependencies** — na voljo v Tree View in v kontekstnem meniju urejevalnika:

  * Prikaže odvisnosti enot kot drevo
  * Zazna krožne reference
  * Pomaga pri refaktoriranju

| Klic | Vedenje |
^ Desni klik na projekt v Tree | Prikaže odvisnosti projekta (vse enote in pakete) |
^ Desni klik na paket v Tree | Prikaže odvisnosti paketa |
^ Desni klik na enoto v Tree | Prikaže odvisnosti enote (''uses'' klavzule) |
^ Kontekstni meni urejevalnika → Show Dependencies | Prikaže odvisnosti trenutno odprte datoteke |

==== Hierarhija klicev ====

**Show Call Hierarchy** — na voljo v Tree View in v kontekstnem meniju urejevalnika:

=== Iz Tree View ===

Desni klik na enoto → **Show Call Hierarchy** odpre WebView-panel z:

  * **Incoming** — Katere funkcije kličejo ta simbol (klicatelji)
  * **Outgoing** — Katere funkcije kliče ta simbol (klicanci)
  * Klikljivi vnosi navigirajo neposredno do mesta klica

=== Iz urejevalnika (Peek-prikaz) ===

Desni klik v Pascal-urejevalniku → **FPC Solution Manager** → **Show Call Hierarchy** prikaže hierarhijo klicev kot **vgrajeni Peek-pripomoček** neposredno v urejevalniku (podobno kot ''Peek Definition''). Kazalec mora biti na imenu funkcije ali metode.

<note>Hierarhija klicev (odhodne klice) deluje prek analize razširitve. Dohodne klice (klicatelji) zahtevajo pasls-podporo za ''textDocument/references'', ki trenutno še ni na voljo.</note>

===== Bližnjice na tipkovnici =====

| Bližnjica | Dejanje | Kontekst |
^ ''Ctrl+Shift+B'' | Build Project | Tree View: Projekt |
^ ''F5'' | Run Project | Tree View: Projekt |
^ ''F9'' | Build and Run | Tree View: Projekt |
^ ''Shift+F9'' | Rebuild Project | Tree View: Projekt |
^ ''Ctrl+Shift+C'' | Clean Project | Tree View: Projekt |
^ ''F4'' | Properties | Tree View: Projekt/Paket |
^ ''F12'' | Toggle Form/Code | Pascal-urejevalnik / Form Designer |
^ ''Alt+F12'' | View Form as Text | Form Designer |
^ ''Ctrl+Shift+A'' | Add Unit | Tree View: Projekt/Mapa |
^ ''Ctrl+Shift+M'' | Select Build Mode | Tree View: Projekt |
^ ''Ctrl+Shift+R'' | Refresh Tree | Tree View fokusiran |
^ ''Shift+F5'' / ''Ctrl+F2'' | Stop Process | Tree View |
^ ''Alt+Shift+R'' | Reveal in Explorer | Tree View: Enota/Obrazec |
^ ''Enter'' | Open File | Tree View: Enota/Obrazec |
^ ''Ctrl+Alt+W'' | Add Watch | Pascal-urejevalnik z izbiro |

===== Glej tudi =====

  * [[.:start|WvdS FPC Tools pregled]]
  * [[.:installation|Namestitev in nastavitev]]
  * [[.:pas2js-studio|FPC PAS2JS Studio]]
  * [[.:iss-designer|FPC ISS Designer]]
  * [[.:faq|Pogosta vprašanja (FAQ)]]