Skip to content

USAGE_GUIDE.md

Latest commit

 

History

History
226 lines (168 loc) · 6.95 KB

USAGE_GUIDE.md

File metadata and controls

226 lines (168 loc) · 6.95 KB
Raw

Usage Guide

Configuration patterns for the LVCompare GitHub Action.

The examples below intentionally pin the latest supported stable release (v0.6.6). Use newer stable v0.6.x tags after they are published; use v0.6.x-rc tags only when you are deliberately evaluating a future release candidate.

lvCompareArgs

The lvCompareArgs input accepts a raw string or array of flags passed directly to LVCompare. Quotes and spaces are preserved. The action now defaults to full-detail compares; provide lvCompareArgs only when you need to reapply noise filters.

Common noise filters:

lvCompareArgs: "-noattr -nofp -nofppos -nobd -nobdcosm"
  • -nobdcosm – ignore block diagram cosmetic changes.
  • -nofppos – ignore front panel position/size changes.
  • -noattr – ignore VI attribute changes.

Specify a LabVIEW path:

lvCompareArgs: '-lvpath "C:\\Program Files\\National Instruments\\LabVIEW 2025\\LabVIEW.exe"'

Log to a temporary path:

lvCompareArgs: '--log "${{ runner.temp }}\\lvcompare.log"'

Arrays keep each element as a single token, useful when mixing strings and script blocks.

Working directory

If your VIs live under a subfolder, set working-directory to avoid long relative paths:

- name: Compare VIs
  uses: LabVIEW-Community-CI-CD/compare-vi-cli-action@v0.6.6
  with:
    working-directory: my-project
    base: src/VI1.vi
    head: src/VI2.vi
    lvCompareArgs: "-noattr -nofp -nofppos -nobd -nobdcosm"

Compare timeout

If a self-hosted compare lane can hang on a stuck LVCompare process, set compare-timeout-seconds so the action fails closed with exit code 124 instead of waiting indefinitely:

- name: Compare VIs
  uses: LabVIEW-Community-CI-CD/compare-vi-cli-action@v0.6.6
  with:
    base: VI1.vi
    head: VI2.vi
    compare-timeout-seconds: 1200
    fail-on-diff: false

Use 0 to disable the timeout and preserve the unbounded legacy wait. Choose the bound for your real compare duration; the specialized LV32 workflow in this repo now uses 1200 seconds because a successful native compare can take several minutes on that lane.

Path resolution tips

  • base and head are resolved to absolute paths before invoking LVCompare.
  • Relative paths respect working-directory (defaults to repository root).
  • UNC paths (\\server\share) pass through unchanged; no extra escaping required.
  • For long paths on Windows, consider mapping a drive or shortening workspace paths.

HTML comparison reports

Generate a standalone HTML diff via LabVIEWCLI (LabVIEW 2025 Q3+):

LabVIEWCLI -OperationName CreateComparisonReport `
    -VI1 "C:\path\VI1.vi" -VI2 "C:\path\VI2.vi" `
    -ReportType HTMLSingleFile -ReportPath "CompareReport.html" `
  -noattr -nofp -nofppos -nobd -nobdcosm

Benefits: artefact-friendly, visual review, honours noise filters.

Repository helper:

pwsh -File scripts/Render-CompareReport.ps1 `
  -Command $env:COMPARE_COMMAND `
  -ExitCode $env:COMPARE_EXIT_CODE `
  -Diff $env:COMPARE_DIFF `
  -CliPath $env:COMPARE_CLI_PATH `
  -DurationSeconds $env:COMPARE_DURATION_SECONDS `
  -OutputPath compare-report.html

NI Windows container compare (local)

Use the local helper when you want deterministic compare execution against NI's Windows image without changing the composite action default path.

Preflight Docker mode/image:

node tools/npm/run-script.mjs compare:docker:ni:windows:probe

Expected probe prerequisites:

  • Docker Desktop daemon mode is windows.
  • Image is present locally (default: nationalinstruments/labview:2026q1-windows).

Run compare (base/head provided by environment):

$env:LV_BASE_VI = (Resolve-Path .\VI1.vi).Path
$env:LV_HEAD_VI = (Resolve-Path .\VI2.vi).Path
node tools/npm/run-script.mjs compare:docker:ni:windows

Direct invocation with optional overrides:

pwsh -File tools/Run-NIWindowsContainerCompare.ps1 `
  -BaseVi .\VI1.vi `
  -HeadVi .\VI2.vi `
  -Image nationalinstruments/labview:2026q1-windows `
  -ReportType html `
  -TimeoutSeconds 600

The helper injects -Headless automatically for container runs unless you already provide it in -Flags.

The helper writes deterministic artifacts beside the report:

  • ni-windows-container-capture.json
  • ni-windows-container-stdout.txt
  • ni-windows-container-stderr.txt

Capture diagnostics include:

  • classification (ok, diff, timeout, preflight-error, labview-cli-connection, run-error)
  • labviewCliErrorCode (parsed NI CLI error code when present)
  • recommendation (actionable remediation text for known failure classes)
  • reportExists (whether the expected report file was produced)

Exit semantics:

  • 0: no differences (or probe success).
  • 1: differences detected (or CLI-level compare error; inspect capture status/message).
  • 2: preflight/configuration error (mode/image/path).
  • 124: timeout.

Known runtime issue:

  • If capture classification is labview-cli-connection with labviewCliErrorCode=-350000, the NI image runtime on that host could not establish LabVIEW CLI connectivity for the operation. Use the emitted stdout/stderr artifacts for remediation and image validation.

Workflow branching

Basic success/failure handling:

- name: Compare VIs
  id: compare
  uses: LabVIEW-Community-CI-CD/compare-vi-cli-action@v0.6.6
  with:
    base: VI1.vi
    head: VI2.vi
    fail-on-diff: false

- name: React to differences
  if: steps.compare.outputs.diff == 'true'
  run: echo "Differences found"

Exit code switch:

- name: Inspect exit code
  shell: pwsh
  run: |
    $code = [int]'${{ steps.compare.outputs.exitCode }}'
    switch ($code) {
      0 { "No differences" }
      1 { "Differences found" }
      default { Write-Error "LVCompare error" }
    }

Short-circuit detection (base == head):

- name: Check shortcut
  if: steps.compare.outputs.shortCircuitedIdentical == 'true'
  run: echo "Comparison skipped (identical paths)"

Related docs

Composite action limitations

  • The composite action always invokes LVCompare directly; it does not honor LVCI_COMPARE_MODE or LVCI_COMPARE_POLICY. Those toggles apply to harness/workflow helpers only.
  • LVCompare cannot compare two different files that share the same filename (e.g., .../A/Thing.vi vs .../B/Thing.vi). The composite action will surface this limitation. Use the CLI‑based harness workflows if you need to handle same‑filename compares (they generate an HTML report via LabVIEW CLI).