|
| 1 | +--- |
| 2 | +name: dotnet10-pack-tool |
| 3 | +version: 1.0.0 |
| 4 | +description: Creates hybrid Native AOT + CoreCLR .NET 10 tool packages using ToolPackageRuntimeIdentifiers. Use for building high-performance CLI tools with Native AOT on supported platforms and CoreCLR fallback for universal compatibility. |
| 5 | +source_urls: |
| 6 | + - https://github.com/richlander/dotnet10-hybrid-tool |
| 7 | + - https://github.com/richlander/dotnet10-hybrid-tool/blob/main/build-packages.sh |
| 8 | +--- |
| 9 | + |
| 10 | +# .NET 10 Hybrid Pack Tool |
| 11 | + |
| 12 | +## Purpose |
| 13 | + |
| 14 | +Guides you through creating hybrid .NET 10 tool packages that combine Native AOT for maximum performance on select platforms with CoreCLR fallback for universal compatibility. |
| 15 | + |
| 16 | +## When I Activate |
| 17 | + |
| 18 | +I automatically load when you mention: |
| 19 | + |
| 20 | +- "pack .NET tool" or "dotnet pack AOT" |
| 21 | +- "Native AOT tool" or "hybrid .NET tool" |
| 22 | +- "ToolPackageRuntimeIdentifiers" |
| 23 | +- ".NET 10 tool packaging" |
| 24 | +- "cross-platform .NET tool with AOT" |
| 25 | + |
| 26 | +## What I Do |
| 27 | + |
| 28 | +1. Configure your .csproj with `ToolPackageRuntimeIdentifiers` and `PublishAot=true` |
| 29 | +2. Generate the pointer package (metapackage) |
| 30 | +3. Build Native AOT packages for each target RID |
| 31 | +4. Create CoreCLR fallback with `-r any` |
| 32 | +5. Validate package structure |
| 33 | + |
| 34 | +## Quick Start |
| 35 | + |
| 36 | +### Step 1: Configure .csproj |
| 37 | + |
| 38 | +```xml |
| 39 | +<Project Sdk="Microsoft.NET.Sdk"> |
| 40 | + <PropertyGroup> |
| 41 | + <OutputType>Exe</OutputType> |
| 42 | + <TargetFramework>net10.0</TargetFramework> |
| 43 | + <ImplicitUsings>enable</ImplicitUsings> |
| 44 | + |
| 45 | + <!-- Package as .NET Tool --> |
| 46 | + <PackAsTool>true</PackAsTool> |
| 47 | + <ToolCommandName>your-tool-name</ToolCommandName> |
| 48 | + |
| 49 | + <!-- RIDs: CoreCLR fallback + Native AOT targets --> |
| 50 | + <ToolPackageRuntimeIdentifiers>any;osx-arm64;linux-arm64;linux-x64</ToolPackageRuntimeIdentifiers> |
| 51 | + |
| 52 | + <!-- Enable Native AOT --> |
| 53 | + <PublishAot>true</PublishAot> |
| 54 | + </PropertyGroup> |
| 55 | + |
| 56 | + <!-- Native AOT optimizations --> |
| 57 | + <PropertyGroup Condition="'$(PublishAot)' == 'true'"> |
| 58 | + <InvariantGlobalization>true</InvariantGlobalization> |
| 59 | + <OptimizationPreference>Size</OptimizationPreference> |
| 60 | + <StripSymbols>true</StripSymbols> |
| 61 | + </PropertyGroup> |
| 62 | +</Project> |
| 63 | +``` |
| 64 | + |
| 65 | +### Step 2: Build Packages |
| 66 | + |
| 67 | +```bash |
| 68 | +# 1. Create pointer package (no binaries, just metadata) |
| 69 | +dotnet pack -o ./packages |
| 70 | + |
| 71 | +# 2. Build Native AOT for each target platform |
| 72 | +dotnet pack -r osx-arm64 -o ./packages # On macOS |
| 73 | +dotnet pack -r linux-arm64 -o ./packages # On Linux ARM or container |
| 74 | +dotnet pack -r linux-x64 -o ./packages # On Linux x64 or container |
| 75 | + |
| 76 | +# 3. Create CoreCLR fallback for all other platforms |
| 77 | +dotnet pack -r any -p:PublishAot=false -o ./packages |
| 78 | +``` |
| 79 | + |
| 80 | +### Step 3: Install & Run |
| 81 | + |
| 82 | +```bash |
| 83 | +dotnet tool install -g your-tool-name |
| 84 | +your-tool-name # Auto-selects best package for platform |
| 85 | +``` |
| 86 | + |
| 87 | +## Key Concepts |
| 88 | + |
| 89 | +| Concept | Description | |
| 90 | +| --------------------------------- | ----------------------------------------------------- | |
| 91 | +| **Pointer Package** | Metapackage that references RID-specific packages | |
| 92 | +| **ToolPackageRuntimeIdentifiers** | Lists RIDs, creates pointer structure (no auto-build) | |
| 93 | +| **`-r any`** | CoreCLR fallback for unlisted platforms | |
| 94 | +| **`-p:PublishAot=false`** | Disables AOT for CoreCLR fallback | |
| 95 | + |
| 96 | +## Why This Pattern Works |
| 97 | + |
| 98 | +- `PublishAot=true` disables automatic RID package generation (AOT can't cross-compile OSes) |
| 99 | +- `ToolPackageRuntimeIdentifiers` creates the pointer package structure |
| 100 | +- Manual `-r <RID>` builds produce AOT binaries per platform |
| 101 | +- `-r any -p:PublishAot=false` creates portable CoreCLR fallback |
| 102 | + |
| 103 | +## Documentation |
| 104 | + |
| 105 | +- [reference.md](./reference.md): Complete build script, container builds, CI/CD patterns |
| 106 | +- [examples.md](./examples.md): Real-world examples and troubleshooting |
| 107 | + |
| 108 | +## Requirements |
| 109 | + |
| 110 | +- .NET 10 SDK installed |
| 111 | +- Docker (for cross-platform Linux builds from macOS/Windows) |
| 112 | +- AOT-compatible container: `mcr.microsoft.com/dotnet/sdk:10.0-noble-aot` |
0 commit comments