diff --git a/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/04-nuget-package-guide.mdx b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/04-nuget-package-guide.mdx new file mode 100644 index 00000000..cbdf435d --- /dev/null +++ b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/04-nuget-package-guide.mdx @@ -0,0 +1,264 @@ +--- +title: "NuGet Package Guide" +description: "Guide to building and testing the SplashKit NuGet package for .NET" +--- + +import { FileTree, Steps } from "@astrojs/starlight/components"; + +## 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](https://www.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). + +:::note + +**Prerequisite:** Ensure [.NET SDK](https://dotnet.microsoft.com/en-us/download) is installed. + +::: + +## Building the Package + + + +1. #### Download the SplashKit native libraries + + Download the latest stable libraries from [SKM](https://github.com/splashkit/skm.git). 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`. + + :::note + + SKM does not include pre-compiled libraries for Linux. It instead uses a script to install + dependencies and builds based on the detected distro. + + ::: + +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** + + ```shell + dotnet build --configuration Debug -p:version=YOUR_VERSION-debug + ``` + + **For release** + + ```shell + 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](#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. + + + +- tools + - scripts + - test + - Main/ + - 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. + +:::note + +For more information on SplashKit core integration tests, see +[here](https://thoth-tech.netlify.app/products/splashkit/documentation/splashkit-expansion/#building-the-test-programs). + +::: + +### 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. + + :::caution + + Ensure **every** listed version of .NET is installed. + + ::: + +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`. + + ```shell + dotnet run -f + ``` + + :::note + + To aid testing and ensure consistency, the test runner lists the target and runtime .NET + framework, along with the NuGet package version. These should be checked on every run to ensure + alignment with the intended targets: + + ![Run NuGet Tests](images/nuget-testing/1-test-runner.png) + + ::: + +5. #### Select test + + Input a number to build and run the corresponding test. + + :::caution + + **Known issue:** The included graphics test currently produces inconsistent results in a + MSYS2/Windows environment. This behaviour is consistent with SplashKit installed via SKM and is + being investigated. + + ::: + +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](#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: + + ```shell + mkdir MyTest + ``` + +2. Inside the new directory, create a new project with + + ```shell + dotnet new console + ``` + +3. Edit the project's `.csproj` file to remove any `` 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. + + ```cs + SetResourcesPath(GlobalSettings.ResourcePath); + ``` + + + +:::note + +The test runner checks the solution directory for any `.csproj` files on input. Therefore, new tests +are detected by the runner automatically, and can even be added without closing the runner. + +::: + +### 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: + +```cs +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 + + ```shell + 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: + + ```xml + + + + ``` + +4. Add `using static SplashKitSDK.SplashKit;` to `Program.cs` + + diff --git a/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/nuget-testing/1-test-runner.png b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/nuget-testing/1-test-runner.png new file mode 100644 index 00000000..6255fcec Binary files /dev/null and b/src/content/docs/Products/SplashKit/Documentation/SplashKit Expansion/images/nuget-testing/1-test-runner.png differ