====== Gradbeni cevovod ======

Opis gradbenega procesa za WvdS FPC RAD Studio.

===== Pregled =====

<code>
┌─────────────────────────────────────────────────────────────┐
│                      BUILD PIPELINE                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. PRE-BUILD                                                │
│     ├── Policy-Check (wvds-lint)                             │
│     ├── Dependency Resolution                                │
│     └── Asset Preparation                                    │
│                                                              │
│  2. COMPILE                                                  │
│     ├── pas2js / FPC invocation                              │
│     ├── Unit Resolution                                      │
│     └── Code Generation                                      │
│                                                              │
│  3. POST-BUILD                                               │
│     ├── Bundle Assets                                        │
│     ├── Generate Source Maps                                 │
│     └── Copy to dist/                                        │
│                                                              │
│  4. PACKAGE (optional)                                       │
│     ├── VSIX Creation                                        │
│     └── Version Stamping                                     │
│                                                              │
└─────────────────────────────────────────────────────────────┘
</code>

===== Pre-Build =====

==== Preverjanje politik ====

<code bash>
wvds-lint policy --path sources/
</code>

Preverja:
  * P0: Brez duplikatov v razširitvah
  * P1: Brez .ts ali ročno pisanih .js datotek
  * P2: Ovojnice samo v common/
  * P3: Samozadosten izhod

==== Razreševanje odvisnosti ====

Odvisnosti se razrešijo iz ''build.cfg'' in ''package.json'':

<code ini>
# build.cfg
[build]
compiler=pas2js
entry=extension_main.pas

[dependencies]
core=../../common/core
vscode=../../common/web/vscode
</code>

===== Prevajanje =====

==== pas2js prevajanje ====

<code bash>
pas2js \
  -Jc \                    # Kompaktni izhod
  -Jirtl.js \              # RTL kot zunanji modul
  -Jm \                    # Generiraj izvorne mape
  -Tbrowser \              # Cilj: brskalnik
  -Fu../../common \        # Poti do enot
  -FE./dist \              # Izhodni imenik
  pas/extension_main.pas   # Vstopna točka
</code>

==== FPC prevajanje ====

<code bash>
fpc \
  -Mobjfpc \               # Object Pascal način
  -Sh \                    # Ansi nizi
  -O3 \                    # Optimizacija stopnja 3
  -Fu../../common \        # Poti do enot
  -FE./bin \               # Izhodni imenik
  project.lpr              # Projektna datoteka
</code>

==== Možnosti prevajalnika ====

^ Možnost ^ pas2js ^ FPC ^ Opis ^
| Debug | -Jc -Jm | -g -O0 | Razhroščevalni simboli, brez optimizacije |
| Release | -Jc -O3 | -O3 -Xs | Optimizirano, brez simbolov |
| Profile | -Jc -Jm | -g -O2 -pg | Profilirna instrumentacija |

===== Post-Build =====

==== Združevanje virov ====

Viri se kopirajo v ''dist/'':

<code>
dist/
├── extension_main.js      # Prevedena koda
├── extension_main.js.map  # Izvorna mapa
└── assets/                # Kopirani viri
    ├── templates/*.html
    └── images/*.png
</code>

==== Izvorne mape ====

Izvorne mape omogočajo razhroščevanje Pascal kode:

<code json>
// extension_main.js.map
{
  "version": 3,
  "sources": ["../pas/extension_main.pas"],
  "mappings": "..."
}
</code>

===== Pakiranje =====

==== Ustvarjanje VSIX ====

<code bash>
vsce package --out binaries/dist/
</code>

Ustvari: ''wvds-vscode-{name}-{version}.vsix''

==== Označevanje verzije ====

Verzija se prebere iz ''package.json'' in vgradi v gradnjo:

<code pascal>
const
  VERSION = {$I version.inc};  // Generirano iz package.json
</code>

===== Gradbeni načini =====

^ Način ^ Uporaba ^ Optimizacija ^ Simboli ^
| debug | Razvoj | Brez | Da |
| release | Produkcija | Maksimalna | Ne |
| profile | Analiza zmogljivosti | Srednja | Da + profiliranje |

===== Inkrementalna gradnja =====

Gradnja uporablja predpomnjenje za hitrejše prevajanje:

  * ''binaries/cache/'' vsebuje prevedene enote (.ppu, .o)
  * Samo spremenjene enote se ponovno prevedejo
  * ''wvds-build clean'' izbriše predpomnilnik

===== Orodja CLI =====

Gradna veriga orodij sestoji iz dveh glavnih orodij:

==== pxamlc (PXAML prevajalnik) ====

Prevaja PXAML datoteke za določen cilj:

<code bash>
pxamlc compile \
  --target <tui|desktop|web> \
  --pxaml <file.pxaml> \
  --packs ~/packs \
  --out ~/binaries/out/<app>/<target>
</code>

^ Možnost ^ Opis ^
| ''%%--%%target'' | Ciljna platforma: tui, desktop, web |
| ''%%--%%pxaml'' | Vhodna PXAML datoteka |
| ''%%--%%packs'' | Pot do Pack registra |
| ''%%--%%out'' | Izhodni imenik |

==== wvds-build ====

Orkestrira celoten gradbeni proces:

<code bash>
wvds-build build <tui|desktop|web> \
  --app ~/sources/applications/<app> \
  --config ~/.wvds/wvds-build.json \
  --out ~/binaries/out
</code>

^ Možnost ^ Opis ^
| ''%%--%%app'' | Imenik aplikacije |
| ''%%--%%config'' | Konfiguracijska datoteka |
| ''%%--%%out'' | Izhodni imenik |

=== Dodatni ukazi ===

<code bash>
# Izbriši vse gradbene artefakte
wvds-build clean

# Namesti paket
wvds-build pack install --from <packdir> --to ~/vendor-packs --enable tui,web

# Odstrani paket
wvds-build pack uninstall --vendor <vendor> --pack <pack>

# Izpiši nameščene pakete
wvds-build pack list
</code>

==== Konfiguracijska datoteka ====

**Pot:** ''~/.wvds/wvds-build.json''

<code javascript>
{
  "compilers": {
    "fpc": "%LAZARUS%/fpc/3.3.1/bin/fpc.exe",
    "pas2js": "%LAZARUS%/fpc/3.3.1/bin/pas2js.exe"
  },
  "paths": {
    "packs": "~/packs",
    "common": "~/sources/common",
    "output": "~/binaries/out"
  },
  "defaults": {
    "target": "web",
    "mode": "debug"
  },
  "targets": {
    "tui": {
      "compiler": "fpc",
      "enabled": true
    },
    "desktop": {
      "compiler": "fpc",
      "enabled": true
    },
    "web": {
      "compiler": "pas2js",
      "enabled": true
    }
  }
}
</code>

==== VS Code opravila ====

Opravila se samodejno generirajo:

<code javascript>
// .vscode/tasks.json (generirano)
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "WVDS: Build TUI",
      "type": "shell",
      "command": "${workspaceFolder}/.wvds/bin/wvds-build",
      "args": ["build", "tui"]
    },
    {
      "label": "WVDS: Build Desktop",
      "type": "shell",
      "command": "${workspaceFolder}/.wvds/bin/wvds-build",
      "args": ["build", "desktop"]
    },
    {
      "label": "WVDS: Build Web",
      "type": "shell",
      "command": "${workspaceFolder}/.wvds/bin/wvds-build",
      "args": ["build", "web"]
    }
  ]
}
</code>

<note>Opravil ne urejajte ročno - generira jih ''wvds-build''.</note>

===== CI/CD integracija =====

<code yaml>
# .github/workflows/build.yml
build:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Install FPC
      run: sudo apt-get install fpc
    - name: Install pas2js
      run: sudo apt-get install pas2js
    - name: Build
      run: wvds-build --mode release
    - name: Package
      run: wvds-build package
</code>

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

==== "Unit not found" ====

  * Preverite poti do enot v build.cfg
  * Preverite velike/male črke (Linux)

==== "JavaScript error" ====

  * Uporabite izvorno mapo za razhroščevanje
  * Preverite pas2js izhod za opozorila

==== "VSIX invalid" ====

  * Validirajte package.json
  * README.md mora obstajati
  * Preverite pot do ikone

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

  * [[.:targets|Gradbeni cilji]]
  * [[.:release|Postopek izdaje]]
  * [[.:testing|Testiranje]]