Skip to content

Contributing

Jump to bottom
Nanook edited this page Sep 24, 2026 · 1 revision

How to build NKit from source, run the tests, and submit changes.

Note: This documentation is a first draft and will be improved over time.

Source Code

The source is at github.com/Nanook/NKit.

Bug reports and feature requests: open a GitHub Issue.
Code contributions: open a Pull Request against the main branch.

Prerequisites

Tool Version Notes
.NET SDK 10.0+ dot.net/download
Visual Studio 2022+ or Rider — Or any editor that supports .slnx
Docker (optional) — Required for legacy Linux builds only

Building

Development build (Debug)

dotnet build NKit.slnx

Note: NKit.UI and NKDS.UI may show Avalonia NuGet warnings — this is a pre-existing issue that does not affect the core libraries or CLI apps.

Release AOT builds

Release builds produce native single-file executables. Use the build scripts:

Windows:

.\build\build.ps1 -Runtime win-x64 -Version 3.0.0 -Apps "console,nkds"

Linux (via WSL + Docker):

wsl -d Ubuntu-22.04 -- bash -lc "cd /mnt/path/to/NKit && VERSION=3.0.0 ./build/wsl-docker-build.sh"

Output lands in build-output/. See Architecture for the full build documentation.

Running Tests

Fast unit-test gate (~2 minutes)

Runs ~14,900 unit tests. Excludes the heavy end-to-end suites that need real disc images.

Windows:

$exe = "NKit.Tests/bin/Debug/net10.0/NKit.Tests.exe"
dotnet build NKit.Tests/NKit.Tests.csproj -f net10.0 -c Debug --nologo
& $exe -notrait "Area=Full" -notrait "Speed=Slow"

Linux (via Docker — same container as builds):

wsl -d Ubuntu-22.04 -- bash -lc "cd /mnt/path/to/NKit && bash build/test.sh"

Full test suite (~40 minutes)

Requires real disc image fixtures in ../WipedImages and ../NKitExternalTestFiles.

bash build/test.sh --full

Specific test class

# Windows — run one class
$exe = "NKit.Tests/bin/Debug/net10.0/NKit.Tests.exe"
& $exe -method "*CliParserTests*"
# Linux
bash build/test.sh --trait "Group=ImageReading"

Test projects

Project Scope
NKit.Tests CLI parser, configuration, engine unit tests, DataStore tests
NKitDataStore.Tests DataStore storage, compaction, crash recovery, VFS
NKDS.Tests NKDS operations, dat verification
NKitCore.Tests Pipeline section engine
NKitStream.Tests BufferStream, file scanning

Code Conventions

  • No reflection in any format I/O or processing path — all code must be AOT-safe
  • Explicit endianness — use ReadUInt32B/L helpers, never raw BitConverter
  • Forward-reading streams — format readers must not seek backwards in sources
  • #nullable disable in test projects; enable in library code
  • Match surrounding style; avoid reformatting unrelated code in a PR

Pull Request Guidelines

  1. Keep PRs focused — one logical change per PR
  2. Add tests for new behaviour; regression tests for bug fixes
  3. Run the fast unit-test gate before submitting — PRs with failing tests won't be merged
  4. Describe what the change does and why in the PR description
  5. Reference the relevant GitHub Issue if applicable

Project Structure

NKit/               ← Core processing engine (disc images)
NKitDataStore/      ← Block storage engine (shards, index, compaction)
NKitCore/           ← Generic async section pipeline (StreamBlockCore)
NKitStream/         ← BufferStream and streaming primitives
NKDS/               ← DataStore product (sets, VFS, session management)
Shared/             ← Shared CLI utilities (SpectrePrompter)
NKitApp/            ← nkit CLI
NKDSApp/            ← nkds CLI
NKit.UI/            ← nkit-ui (Avalonia GUI)
NKDS.UI/            ← nkds-ui (Avalonia GUI)
NKit.SampleProcessingApp/ ← Embedding example
Tmds.Fuse/          ← FUSE mount support (Linux)
build/              ← Build scripts

See Architecture for how the libraries fit together.

Related

Clone this wiki locally