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

Navodila za razhroščevanje WvdS FPC RAD Studio razširitev in aplikacij.

===== Razhroščevalno beleženje =====

==== Dvostopenjska aktivacija ====

Razhroščevalno beleženje zahteva **dva pogoja**:

  - **Čas prevajanja:** Prevajanje z ''-dDEBUG''
  - **Čas izvajanja:** Zagon razširitve s parametrom ''--debug''

<code pascal>
{$IFDEF DEBUG}
procedure LogDebugTrace(const AMessage: string; const AArgs: array of const);
begin
  if not DebugEnabled then Exit;
  WriteToDebugLog(Format('[%s] %s', [
    FormatDateTime('hh:nn:ss.zzz', Now),
    Format(AMessage, AArgs)
  ]));
end;
{$ENDIF}
</code>

==== Dnevniška datoteka ====

  * Format: ''debug-yymmddhhnnss.log''
  * Lokacija: ''~/binaries/logs/''
  * **Nikoli** ne potrjujte v ''~/sources/''

==== MS format sledenja izjem ====

Za podrobno razhroščevanje s skladom klicev:

<code pascal>
procedure LogDebugTrace(const AMessage: string; const AArgs: array of const);
var
  CallStack: string;
begin
  {$IFDEF DEBUG}
  if not DebugEnabled then Exit;

  (* Sklad klicev z get_caller_frame / get_frame *)
  CallStack := GetCallStackTrace;

  WriteToDebugLog(Format(
    '[%s] %s'#13#10 +
    '   at %s'#13#10 +
    '   Parameters: %s',
    [
      FormatDateTime('yyyy-MM-dd hh:nn:ss.zzz', Now),
      Format(AMessage, AArgs),
      CallStack,
      FormatParams(AArgs)
    ]
  ));
  {$ENDIF}
end;
</code>

==== Pomočnik za sklad klicev ====

<code pascal>
function GetCallStackTrace: string;
var
  Frame: Pointer;
  Addr: Pointer;
  Info: string;
begin
  Result := '';
  {$IFDEF DEBUG}
  Frame := get_frame;
  while Frame <> nil do
  begin
    Addr := get_caller_addr(Frame);
    Info := BackTraceStrFunc(Addr);  (* Format Unit:Line *)
    if Info <> '' then
      Result := Result + '   at ' + Info + #13#10;
    Frame := get_caller_frame(Frame);
  end;
  {$ENDIF}
end;
</code>

==== Primer dnevniške datoteke ====

<code>
================================================================================
DEBUG LOG: debug-260112143022.log
Started: 2026-01-12 14:30:22.001
================================================================================

[2026-01-12 14:30:22.001] Application started with --debug
   at TWvdSApplication.Initialize(Application.Main.pas:42)
   at program.main(extension_main.pas:398)
   Parameters: (CommandLine='--debug')

[2026-01-12 14:30:22.015] Loading configuration
   at TWvdSToolchainConfigService.LoadFromSettings(Toolchain.ConfigService.pas:156)
   at TWvdSToolchainConfigService.AutoDetectAll(Toolchain.ConfigService.pas:89)
   at DoActivate(extension_main.pas:368)
   Parameters: (ConfigPath='~/.vscode/settings.json')

[2026-01-12 14:30:22.042] Service initialized
   at TWvdSBuildService.Initialize(Build.Service.pas:45)
   at DoActivate(extension_main.pas:370)
   Parameters: (ServiceName='BuildService', Mode=debug)

================================================================================
ERROR TRACE (if any):
================================================================================

[2026-01-12 14:30:24.500] ERROR: File not found
   at ValidateBuildPath(Build.Service.pas:144)
   at GenerateCleanCommand(Build.Service.pas:174)
   at OnBuildClean(extension_main.pas:112)
   Parameters: (Path='~/invalid/path', ValidationResult=False)
   Exception: EFileNotFound
   Message: The specified path does not exist
   Stack Trace:
      Build.Service.ValidateBuildPath(144)
      Build.Service.GenerateCleanCommand(179)
      extension_main.OnBuildClean(112)
      VSCode.Commands.ExecuteCommand(89)
</code>

<note>**Pomembno:** Nikoli ne beležite občutljivih podatkov (žetonov, gesel) v Parameters!</note>

==== Kaj beležiti? ====

^ Dovoljeno ^ Prepovedano ^
| Imena akcij | Žetoni, API ključi |
| Imena datotek/poti | Gesla |
| Sporočila napak | ID-ji sej |
| Konfiguracijski ključi | Občutljive vrednosti |

===== Razhroščevanje razširitev VS Code =====

==== Extension Development Host ====

  - Odprite projekt razširitve v VS Code
  - Pritisnite ''F5'' ali ''Run > Start Debugging''
  - Odpre se novo okno VS Code
  - Razširitev se naloži tam

==== launch.json ====

<code json>
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run Extension",
      "type": "extensionHost",
      "request": "launch",
      "args": [
        "--extensionDevelopmentPath=${workspaceFolder}"
      ],
      "outFiles": [
        "${workspaceFolder}/dist/**/*.js"
      ]
    }
  ]
}
</code>

==== Prelomne točke ====

Ker je koda transpilirana (Pascal -> JavaScript), prelomne točke delujejo samo z izvornimi kartami:

  - Prevajajte z ''-Jm'' (generiranje izvorne karte)
  - Nastavite prelomne točke v datoteki .pas
  - VS Code preslika na JavaScript pozicijo

===== Izhodni kanal =====

Izhodni kanal WvdS prikazuje sporočila med izvajanjem:

  - ''View'' -> ''Output''
  - V spustnem meniju izberite "WvdS"

<code pascal>
// V kodi
LogInfo('Informacijsko sporočilo');
LogWarn('Opozorilno sporočilo');
LogError('Napaka: %s', [E.Message]);
</code>

===== Konzola za razvijalce =====

Za nizkonivojsko razhroščevanje:

  - ''Help'' -> ''Toggle Developer Tools''
  - Odprite zavihek Console
  - Vidne so JavaScript napake in console.log

===== Pogoste težave =====

==== Razširitev se ne zažene ====

**Diagnoza:**
<code bash>
# Preverite dnevnike razširitve
code --verbose --log trace
</code>

**Pogosti vzroki:**
  * Sintaksna napaka v generiranem JavaScriptu
  * Manjkajoče odvisnosti v package.json
  * Napačna pot v "main"

==== Ukaz ne deluje ====

**Diagnoza:**
  - Odprite konzolo za razvijalce
  - Izvedite ukaz
  - Preverite napake

**Pogosti vzroki:**
  * Ukaz ni v contributes.commands
  * Obravnavalnik ni registriran
  * Izjema v obravnavalniku

==== WebView ne prikazuje ničesar ====

**Diagnoza:**
  - Desni klik v WebView -> "Inspect"
  - Odprejo se brskalniška DevTools

**Pogosti vzroki:**
  * Napačen HTML
  * CSP blokira vire
  * JavaScript napaka

===== Profiliranje =====

==== Merjenje zmogljivosti ====

<code pascal>
{$IFDEF DEBUG}
var
  StartTime: TDateTime;

procedure StartTiming(const AOperation: string);
begin
  StartTime := Now;
  LogDebug('Starting: %s', [AOperation]);
end;

procedure EndTiming(const AOperation: string);
begin
  LogDebug('Completed: %s in %d ms', [
    AOperation,
    MilliSecondsBetween(Now, StartTime)
  ]);
end;
{$ENDIF}
</code>

==== Uhajanje pomnilnika ====

pas2js/JavaScript ima zbiranje smeti, vendar bodite pozorni na:
  * Krožne reference z zaprtji
  * Neodstranjeni obravnavalci dogodkov
  * Velika polja/objekti v pomnilniku

===== Razhroščevanje testov enot =====

<code pascal>
// Test z razhroščevalnim izhodom
procedure TMyTest.TestFeature;
begin
  {$IFDEF DEBUG}
  LogDebug('Testing with input: %s', [TestInput]);
  {$ENDIF}

  Result := ProcessInput(TestInput);

  {$IFDEF DEBUG}
  LogDebug('Result: %s', [Result]);
  {$ENDIF}

  CheckEquals(Expected, Result);
end;
</code>

===== Glejte tudi =====

  * [[.:sicherheit|Varnostne smernice]]
  * [[.:testing|Testiranje]]
  * [[.:extension-entwicklung|Razvoj razširitev]]