Skip to content
Thoth Tech

NuGet Package Guide

Introduction

NuGet is the package manager for .NET. NuGet packages are essentially zip files containing reusable code, libraries, and metadata. Packages can be distributed privately or publicly via NuGet repositories. For more information, visit nuget.org.

The SplashKit NuGet package has two primary purposes:

  • Provides C# bindings for SplashKit, translated from C++ using SplashKit Translator. The bindings allow users to create SplashKit projects with C#.
  • Provides SplashKit native libraries for Windows (x64) and macOS. These libraries allow Windows and Mac users to create and run SplashKit projects in C# without installing the libraries separately via SplashKit Manager (SKM).

Building the Package

  1. Download the SplashKit native libraries

    Download the latest stable libraries from SKM. Libraries should be placed in /tools/scripts/nuget-pkg/Libraries/win64 and /tools/scripts/nuget-pkg/Libraries/macos respectively. This step can be automated via the use of the bash script found at /tools/scripts/nuget-pkg/download-libraries.sh.

  2. Open the NuGet package directory

    Navigate to /tools/scripts/nuget-pkg. This directory contains configuration settings for the package, along with the associated icon and description.

  3. Build the package

    Run one of the below commands, ensuring to replace YOUR_VERSION with the relevant version number (e.g. 1.3.0):

    For debug

    Terminal window
    dotnet build --configuration Debug -p:version=YOUR_VERSION-debug

    For release

    Terminal window
    dotnet build --configuration Release -p:version=YOUR_VERSION

    This will build the package and output to tools/scripts/nuget-pkg/bin/ as detailed in Exploring the Output.

  4. Check the output directories

    Ensure both Release and Debug directories exist in tools/scripts/nuget-pkg/bin/. If either is missing, create the empty directory as needed. This is to ensure the test programs run without errors.

Exploring the Output

In the tools/scripts/nuget-pkg/bin/ directory, there will be a directory corresponding to the built package - either Debug or Release. This directory contains the NuGet package itself (SplashKit.X.X.X.nupkg), along with separate directories for each targeted .NET version. These directories are for referencing/testing, and can be ignored - the package itself does not depend upon them.

Testing

A suite of test programs is provided in the form of a C# solution, with a separate project/directory for each test.

  • Directorytools
    • Directoryscripts
      • Directorytest
        • DirectoryMain/
          • …
        • Directory.Build.props
        • Directory.Packages.props
        • GlobalSettings.cs
        • NuGet.config
        • NuGetTests.sln

The provided tests are translations of the SplashKit core integration tests. The tests can be run individually from their respective folders, but are best launched using the test runner located in the Main directory.

Running the Provided Tests

  1. Check local package sources

    NuGet.config sets the local NuGet package sources. If one of these directories does not exist, either create it, or comment out the corresponding entry in NuGet.config.

  2. Set target package version

    Directory.Packages.props specifies the target NuGet package version. Update this file to match the version being tested.

  3. Check target .NET versions

    Directory.Build.props specifies .NET versions for multi-targeting. These should match the .NET versions being targeted by the package build.

  4. Run the test runner

    Open the Main directory. Run the following command, replacing TARGET_FRAMEWORK with the framework to be tested, e.g. For .NET 9, use dotnet run -f net9.0.

    Terminal window
    dotnet run -f <TARGET_FRAMEWORK>

  5. Select test

    Input a number to build and run the corresponding test.

  6. Re-run as necessary

    To ensure the package is fully functional, the tests should be re-run to cover each combination of framework and architecture. Every test should produce the expected output.

Updating or Adding Tests

As noted in Running the Provided Tests, the NuGetTests solution specifies the NuGet version and target frameworks in Directory.Packages.props and Directory.Build.props respectively. These should be updated at a solution level, rather than separate configurations for each test project. This ensures ease of use and reduces room for error.

Adding New Tests to the Solution

  1. Create a new directory in /tools/scripts/test, for example:

    Terminal window
    mkdir MyTest

  2. Inside the new directory, create a new project with

    Terminal window
    dotnet new console

  3. Edit the project’s .csproj file to remove any <TargetFramework> tags, since this would override the solution’s multi-targeting.

  4. Write your new test in Program.cs

  5. If loading resources (e.g. images, fonts, etc.) use the following line to utilise existing resources from the main SplashKit test suite.

    SetResourcesPath(GlobalSettings.ResourcePath);

Updating Existing Tests

Existing tests can be updated by editing Program.cs in the corresponding project’s directory. Since the test runner (Main) builds each project before running, there is no need to rebuild the runner upon updating a test. The runner is designed to be left running during updates, to speed up development.

If loading resources (e.g. images, fonts, etc.) use the following line to utilise existing resources from the main SplashKit test suite:

SetResourcesPath(GlobalSettings.ResourcePath);

Creating Tests Outside of the Provided Solution

Normally, an end user would use dotnet add package splashkit to reference the SplashKit package. However, this will default to the latest stable SplashKit version, skipping the locally built one. Instead, do the following:

  1. Create a new project using

    Terminal window
    dotnet new console

  2. Create a NuGet.config file in the project (or solution) directory, specifying the path to the target package. An example can be found in /tools/scripts/test.

  3. Add the following to the .csproj, replacing TARGET_VERSION with the targeted NuGet package version:

    <ItemGroup>
    <PackageReference Include="splashkit" Version="<TARGET_VERSION>" />
    </ItemGroup>

  4. Add using static SplashKitSDK.SplashKit; to Program.cs