Skip to content

packaging.md

Latest commit

 

History

History
181 lines (132 loc) · 6.23 KB

packaging.md

File metadata and controls

181 lines (132 loc) · 6.23 KB
Raw

Packaging And Native Assets

Feather publishes NuGet packages under the FeatherCompute* IDs. The package name is intentionally different from the public C# namespace: application code still uses using Feather;.

Feather separates managed packages from native runtime assets. EasyGPU is built behind Feather's C ABI, then packaged as RID-specific feather native libraries inside FeatherCompute.NativeAssets.

Projects

Project NuGet package Role
src/Feather FeatherCompute Main managed API. Includes the generator analyzer in the package.
src/Feather.Generators FeatherCompute.Generators Roslyn analyzer/source generator for kernels and shaders. Published separately for advanced analyzer-only scenarios.
src/Feather.Native FeatherCompute.Native P/Invoke declarations and native library resolver.
src/Feather.NativeAssets FeatherCompute.NativeAssets RID-specific native runtime assets.
src/Feather.Blender.RenderHost FeatherCompute.Blender.RenderHost Version-matched local .NET tool used by Feather Blender projects.

NuGet Consumption

Most users only need the main package:

dotnet add package FeatherCompute --prerelease

The main package depends on the native binding and native asset packages, and it also carries Feather.Generators.dll under analyzers/dotnet/cs so generated kernels work without a second package reference.

Feather Blender projects additionally pin the matching RenderHost as a local tool in .config/dotnet-tools.json. Blender runs dotnet tool restore on first use and then launches feather-blender-renderhost; no Feather source checkout or machine-specific SDK path is required. The tool package carries the staged native runtimes because .NET tool packages do not consume the ordinary FeatherCompute.NativeAssets runtime layout transitively.

Source Consumption

Generated kernels require the generator as an analyzer:

<ItemGroup>
  <ProjectReference Include="../Feather/src/Feather/Feather.csproj" />
  <ProjectReference Include="../Feather/src/Feather.Generators/Feather.Generators.csproj"
                    OutputItemType="Analyzer"
                    ReferenceOutputAssembly="false" />
</ItemGroup>

Window-only projects that do not define generated shader types can reference only Feather.csproj.

Native Library Resolution

The managed resolver looks for the platform native runtime library in this order:

  • FEATHER_NATIVE_LIBRARY, if set.
  • The application base directory.
  • A native/ subdirectory under the application base directory.
  • The managed assembly directory.
  • Ancestor repository folders such as native/build.
  • artifacts/native-assets/runtimes/<rid>/native.
  • runtimes/<rid>/native.

Override the resolver during development or CI with:

export FEATHER_NATIVE_LIBRARY=/absolute/path/to/libfeather.dylib

Use the platform-specific filename from the table below.

Platform file names:

OS Library name
Windows feather_native.dll
Linux libfeather.so
macOS libfeather.dylib

Build Native Assets

./eng/build-native.sh
./eng/stage-native-assets.sh

For headless builds:

cmake -S native -B native/build -DFEATHER_BUILD_WINDOW=OFF

Pack Locally

Pack all managed projects and the staged native asset for the current runtime identifier:

./eng/pack.sh

eng/stage-native-assets.sh copies the native build output to artifacts/native-assets/runtimes/<rid>/native. Feather.NativeAssets.csproj packs files from that staging directory into FeatherCompute.NativeAssets. Do not commit generated native binaries under src/.

The same staging tree is packed under the RenderHost tool's tools/net10.0/any/runtimes/<rid>/native directory. A local tool package built on one machine therefore contains only the RIDs present in staging; the release workflow assembles all supported release RIDs before packing.

Release native assets are built with SPIRV-Tools optimization enabled and the Ultra preset. On platforms where shader-toolchain libraries are dynamically linked, the staging script includes those transitive native dependencies.

Supported RID folders declared by the project:

  • win-x64
  • win-arm64
  • linux-x64
  • linux-arm64
  • osx-arm64
  • osx-x64

Build and package each RID on a compatible machine with the matching native binary.

Release CI should run the native build on each supported RID, upload the staged artifacts/native-assets/runtimes/<rid>/native directory, then run a final pack job that downloads every RID artifact before publishing FeatherCompute.NativeAssets.

Release Workflow

The repository has a manual GitHub Actions workflow named Release. It accepts a version and a publish switch:

  • publish=false builds packages and uploads them as workflow artifacts.
  • publish=true pushes the packages to nuget.org using NuGet Trusted Publishing. No long-lived API key is stored in GitHub.

Before using publish=true, create a Trusted Publishing policy on nuget.org:

Field Value
Package owner Your nuget.org user or organization that will own FeatherCompute*.
Repository owner FeatherCompute
Repository Feather
Workflow file release.yml
Environment Leave empty unless the workflow is changed to use a GitHub environment.

Then add a GitHub repository variable named NUGET_USER with the same nuget.org user or organization name used as the package owner. This is the profile name, not an email address.

The workflow currently builds packaged native assets for:

  • linux-x64
  • osx-arm64
  • win-x64

It validates that FeatherCompute.NativeAssets contains all three native files, that FeatherCompute contains the analyzer, and that the RenderHost tool carries the same three native runtimes before uploading or publishing all five packages.

For preview releases, use an immutable prerelease version such as:

0.2.0-preview.N

NuGet package versions are immutable once published, so run the workflow once with publish=false, download and inspect the package artifacts, then rerun the same version with publish=true.

Related Docs