Installation

libopx -- Installation Guide

After completing this guide you will have the libopx library, CLI tool, and GUI applications built and ready to use.

---

Simple View

Plain English overview -- what to do, no commands or paths.

1. Prerequisites (Summary)

You need the .NET SDK installed and Git for cloning. The library itself has no external runtime dependencies. The GUI apps target .NET 10 and pull their own NuGet packages during build.

flowchart LR
    subgraph Required["Required"]
        direction TB
        NET[".NET 9+ SDK"]
        GIT["Git"]
    end

    subgraph Optional["Optional (for GUI apps)"]
        direction TB
        NET10[".NET 10 SDK"]
    end

    Required --> BUILD["Build library and CLI"]
    Optional --> GUIBUILD["Build Blazor and Avalonia apps"]

    style Required fill:#e8f5e9,stroke:#4CAF50
    style Optional fill:#f5f5f5,stroke:#9E9E9E

Loading

Legend: Green = required for core library and CLI. Grey = optional, only needed for GUI applications.

2. Installation Steps (Summary)

Clone the repository, build the solution, and run tests to verify. For the CLI, publish a self-contained executable. For NuGet consumption, just add the package to your project.

flowchart TB
    subgraph Row1["Get Source"]
        direction LR
        S1["1. Clone repo"] --> S2["2. Check SDK version"]
    end

    subgraph Row2["Build"]
        direction LR
        S3["3. Build solution"] --> S4["4. Run tests"]
    end

    subgraph Row3["Deploy"]
        direction LR
        S5["5a. Publish CLI"] --> S6["5b. Or add NuGet package"]
    end

    Row1 --> Row2
    Row2 --> Row3

    style Row1 fill:#e8f5e9,stroke:#4CAF50
    style Row2 fill:#e3f2fd,stroke:#2196F3
    style Row3 fill:#fff3e0,stroke:#FF9800

Loading

Legend: Green = setup, Blue = build and verify, Orange = deploy/consume

3. Configuration (Summary)

No configuration files to edit. The SDK version is pinned in global.json. All runtime settings are passed via CLI arguments or API parameters.

flowchart TB
    subgraph SDKPin["SDK Version"]
        direction LR
        GJ["global.json pins .NET 9"] --> ROLL["rollForward: latestMajor"]
    end

    subgraph Runtime["Runtime Settings"]
        direction LR
        CLI["CLI: command-line arguments"]
        API["Library: fluent API parameters"]
        GUI["GUI: UI controls"]
    end

    SDKPin --> Runtime

    style SDKPin fill:#f3e5f5,stroke:#9C27B0
    style Runtime fill:#e3f2fd,stroke:#2196F3

Loading

Legend: Purple = build-time config, Blue = runtime config (no files to edit)

4. Verification (Summary)

Run the test suite. All tests should pass. Optionally run the CLI with a sample file to confirm end-to-end functionality.

flowchart LR
    TEST["Run tests"] --> PASS{"All pass?"}
    PASS -->|Yes| DONE["Ready to use"]
    PASS -->|No| CHECK["Check .NET SDK version"]
    CHECK --> RETRY["Rebuild and retest"]

    style PASS fill:#fff3e0,stroke:#FF9800
    style DONE fill:#e8f5e9,stroke:#4CAF50
    style CHECK fill:#fce4ec,stroke:#e94560

Loading

Legend: Green = success, Orange = decision point, Red = troubleshoot

---

Detailed View

Exact commands, file paths, and config values.

1. Prerequisites (Detailed)

Prerequisite	Version	Purpose
.NET SDK	9.0+	Build library and CLI
.NET SDK	10.0+	Build Blazor and Avalonia apps (optional)
Git	Any	Clone the repository

Install .NET SDK:

# Windows (winget)
winget install Microsoft.DotNet.SDK.9

# Linux (Ubuntu/Debian)
sudo apt-get install -y dotnet-sdk-9.0

# macOS (Homebrew)
brew install dotnet-sdk

Verify:

dotnet --version

2. Installation Steps (Detailed)

Option A: From source

git clone https://github.com/nathanpbutler/libopx.git
cd libopx
dotnet build libopx.sln

Option B: NuGet package only

dotnet add package libopx

Publish CLI as self-contained executable:

dotnet publish apps/opx -c Release -r win-x64 --self-contained
dotnet publish apps/opx -c Release -r linux-x64 --self-contained
dotnet publish apps/opx -c Release -r osx-x64 --self-contained

Published output lands in apps/opx/bin/Release/net9.0/<rid>/publish/.

3. Configuration (Detailed)

global.json -- SDK version pin:

{
  "sdk": {
    "version": "9.0.0",
    "rollForward": "latestMajor",
    "allowPrerelease": true
  }
}

No appsettings.json, no environment variables, no config files required. The rollForward: latestMajor setting means any .NET 9+ SDK will work.

Test sample files: Downloaded automatically on first test run. To pin a specific sample version:

export OPX_SAMPLES_VERSION=v1.0.0
dotnet test tests/libopx.Tests.csproj

4. Verification (Detailed)

Run the full test suite:

dotnet test tests/libopx.Tests.csproj

Expected: all tests pass. Pre-existing CS0618 warnings in MXF.cs are expected (deprecated SMPTE API usage).

Run memory benchmarks:

dotnet test --filter "MemoryBenchmarkTests"

Verify CLI works:

dotnet run --project apps/opx -- --help

Verify Blazor GUI starts:

dotnet run --project apps/opxBlazor
# Open http://localhost:5000 in a browser

If tests fail, check:

1. .NET SDK version is 9.0 or later (dotnet --version)
2. Network access is available for sample file downloads
3. No conflicting global.json in a parent directory