Provide prebuilt native libraries by NuGet Packages.

[ha-ves]

Summary

Continues from #245. Implements CI-driven distribution of prebuilt native binary dependencies.

• Download size: ~112 MB
• Extracted size: ~429 MB

Need to Follow-Up

• DOCS: instructions for referencing prebuilt packages in projects
• DOCS: fallback build guide for unsupported platforms or custom RIDs
• FIX MACOS CI TEST:

dotnet test Tests/NetCord.Natives.Tests/ -tl:off -clp:NoSummary,Verbosity=normal -v normal -bl

and then use https://github.com/JanKrivanek/MSBuildStructuredLog

AllLibraryImportsExistInBinary tests are skipped on OSX due to ProcessModule limitation with dyld.

Included in This PR

✓ CI multi-platform native package build and publish
✓ Per-RID targeted package distribution
✓ Direct integration usage
✓ Custom vcpkg overlay ports for libdave and mlspp &
✓ Dependencies pinning
✓ Basic Unit & Integration tests

Overview

This PR provides prebuilt native libraries via NuGet as per-RID packages. Each package bundles:

• Runtime binaries for standard .NET consumption
• Static libraries for NativeAOT compilation
• MSBuild integration to transparently resolve native paths based on target platform
• Bundled licenses for all included dependencies

Packages are published automatically on successful CI builds to the configured NuGet feed.

Structure & Packaging Model

Per-RID Distribution Model:

• Packages are produced per target RID (local or CI builds)
• Package ID format: NetCord.Natives.{win|linux|osx}-{x64|arm64}
• Example: NetCord.Natives.linux-x64, NetCord.Natives.win-arm64

Package Contents (per-RID package):

runtimes/{rid}/native/              ← Runtime binaries for standard .NET
staticlibs/{rid}/                   ← Static libraries for NativeAOT builds
build/NetCord.Natives.{rid}.*       ← MSBuild props/targets per platform
licenses/                           ← Copyright files from vcpkg ports

What Changed

CI Pruning:

• .github/workflows/build.yml & .github/workflows/build-and-publish.yml: Remove redundancies and make lean
• .github/workflows/build-natives.yml: Parallel multi-platform CI matrix (6 RIDs), artifact caching, NuGet publishing pipeline

Core Build & Packaging

• NetCord.Natives.csproj: VCPKG build and use integration project
• Custom vcpkg ports (natives-ports/):
  • libdave/portfile.cmake — discord/libdave with MSVC ARM64 patch
  • mlspp/portfile.cmake — cisco/mlspp, libdave's dependency

NuGet Package build files

• NetCord.Natives.props: dynamic library exclusion list & staticlib directory resolution via $(RuntimeIdentifier)
• NetCord.Natives.targets: NativeAOT static library linking, dynamic library exclusion

Accessible Metadata

• NativesHelper.cs: NativeLibraryVersionAttribute for runtime version discovery of bundled native libs

For issue tracking, refer to nativelibs versions in NuGet package description.

How to Use

Refer to docs included with this PR.

Maintainer Notes: vcpkg Baseline & Dependency Pinning

All native dependencies are pinned to a specific vcpkg baseline (vcpkg.json) to ensure reproducible builds.

Current constraint: openssl==3.0.7

When upgrading native library versions:

1. Update version constraints in vcpkg.json
2. Run local vcpkg build to validate against all RID triplets
3. Verify if licenses are still viable

Resource requirements:

• Build Runner Availability: On github hosted runner, first-time (cold cache) run can take up to ~30 min

Testing

Comprehensive native library validation via Tests/NetCord.Natives.Tests/:

Unit Tests (NativesBuildTests.cs)

Framework: MSTest with method-level parallelization
Target: .NET 10.0

NativeLoaded — Runtime Library Resolution

[TestMethod]
[DataRow("libdave")]
[DataRow("libsodium")]
[DataRow("opus")]
[DataRow("zstd")]
public void NativeLoaded(string libName)

• Validates each of the four core native libraries can be successfully loaded via NativeLibrary.Load()
• Catches load failures, missing binaries, or corrupted artifacts

AllLibraryImportsExistInBinary — P/Invoke Symbol Verification

Note: Skipped on OSX due to ProcessModule limitation with dyld preventing export enumeration. NativeAOT static linking tests still validate symbol presence on OSX.

[TestMethod]
[OSCondition(ConditionMode.Exclude, OperatingSystems.OSX)]
[DataRow("libdave", "NetCord.Gateway.Voice.Dave")]
[DataRow("libsodium", "NetCord.Gateway.Voice.Encryption.XChaCha20Poly1305")]
[DataRow("opus", "NetCord.Gateway.Voice.Opus")]
[DataRow("zstd", "NetCord.Gateway.Compression.Zstandard")]
public void AllLibraryImportsExistInBinary(string libName, string className)

• Reflects over managed P/Invoke wrapper classes to extract all [LibraryImport] entry points
• Loads each native binary and validates every exported symbol exists via NativeLibrary.TryGetExport()
• Catches missing entry points or mismatched P/Invoke declarations

NativeAotStaticLinking — NativeAOT Full Integration

[TestMethod]
[DataRow("libdave;libsodium;opus;zstd")]
public void NativeAotStaticLinking(string libName)

• Build NativeAot: Invokes dotnet publish -c Release on NativeAotApp with <PublishAot> enabled:
  • Passes current RID (e.g., win-x64, linux-x64, osx-arm64)
  • Links static libraries via <DirectPInvoke>
• Runtime validation: Executes the published AOT app:
  • All native calls are valid
  • Exit code is 0
  • Logs build and run output for debugging

[github-actions]

The documentation preview is available at https://preview.netcord.dev/257.

[AraHaan]

I feel like the best option is to do something like:
NetCord.Natives.<rid> that way only the target RID's static libraries are downloaded and used for NAOT and does not slow down the build with extracting unused native static libraries.

[ha-ves]

@AraHaan by default CI workflow will provide per-RID packages now.

But by .csproj design it will also work If anyone for some reason still needs to package all in one.

[KubaZ2]

I haven't went through all the MSBuild stuff. I kind of hate that it takes so much and I am afraid it may require changes when new versions of binaries get released. I guess there is no better way to handle that? I think most binaries just require a single make or 2 cmake commands to build, but I think most of the MSBuild stuff is just for copying the binaries in the correct place and licensing?

[ha-ves]

@KubaZ2
I haven't went through all the MSBuild stuff. I kind of hate that it takes so much and I am afraid it may require changes when new versions of binaries get released. I guess there is no better way to handle that? I think most binaries just require a single make or 2 cmake commands to build, but I think most of the MSBuild stuff is just for copying the binaries in the correct place and licensing?

Vcpkg is the least time-consuming dependency manager, it can build and put it all together in a convenient path.

The previous version of this PR was just using CMake, but it won't get the dependencies for your NativeAOT.
And it gets many times more complicated than this vcpkg version.

you can refer to this when there's new version:

When upgrading native library versions:

1. Update version constraints in vcpkg.json (or natives-port// and target specific version and patch)
2. Run local vcpkg build to validate against all RID triplets
3. Verify if licenses are still viable

[ha-ves]

@KubaZ2, there are some limitations from comments, but I think this PR is ready.

[AraHaan]

I personally think that the native libraries should each have their own packages and that it should be the Discord Bot creator's responsibility to install the native packages themselves when using NAOT. That way those who don't need the native libraries at all (don't use the voice implementation) can continue to get by without the native library packages.

[KubaZ2]

I personally think that the native libraries should each have their own packages and that it should be the Discord Bot creator's responsibility to install the native packages themselves when using NAOT. That way those who don't need the native libraries at all (don't use the voice implementation) can continue to get by without the native library packages.

@AraHaan, I am not sure what you mean here. The native packages are completely separate and they are not referenced by NetCord's core package. So it is the creator's responsibility to install the native packages. Not sure what NAOT has to do with it though.

[ha-ves]

@KubaZ2 I can't get nix to work for the workflow ...

We'll have to just use vcpkg for now,
It should be fine since it is the recommended way to build the libraries.

[KubaZ2]

@KubaZ2 I can't get nix to work for the workflow ...

We'll have to just use vcpkg for now,
It should be fine since it is the recommended way to build the libraries.

What exactly was failing?

[ha-ves]

@KubaZ2 I can't get nix to work for the workflow ...
We'll have to just use vcpkg for now,
It should be fine since it is the recommended way to build the libraries.

What exactly was failing?

workflow run available here -> https://github.com/ha-ves/NetCord/actions/runs/26461243098

[KubaZ2]

@KubaZ2 I can't get nix to work for the workflow ...
We'll have to just use vcpkg for now,
It should be fine since it is the recommended way to build the libraries.

What exactly was failing?

workflow run available here -> https://github.com/ha-ves/NetCord/actions/runs/26461243098

Seems to be a code or a compiler issue
https://github.com/ha-ves/NetCord/actions/runs/26461243098/job/77909323984#step:9:502

/nix/store/qxaq7jz61a6zkr2mq49i0zvqip2m2jj8-gcc-15.2.0/include/c++/15.2.0/variant(508,22): error GBB9135EA: ‘*(const std::__detail::__variant::_Variant_storage<false, mlspp::Add, mlspp::Update, mlspp::Remove, mlspp::PreSharedKey, mlspp::ReInit, mlspp::ExternalInit, mlspp::GroupContextExtensions>*)__result.std::__detail::__variant::_Variant_storage<false, mlspp::Add, mlspp::Update, mlspp::Remove, mlspp::PreSharedKey, mlspp::ReInit, mlspp::ExternalInit, mlspp::GroupContextExtensions>::_M_index’ may be used uninitialized [-Werror=maybe-uninitialized] [/home/runner/work/NetCord/NetCord/NetCord.Natives/NetCord.Natives.csproj]
    508 |         return this->_M_index != __index_type(variant_npos);
        |                ~~~~~~^~~~~~~~
  cc1plus: all warnings being treated as errors