Skip to content

Commit b636ae6

Browse files
authored
feat: Add dotnet10-pack-tool skill for .NET 10 hybrid AOT packaging (#2096)
* feat: Add dotnet10-pack-tool skill for .NET 10 hybrid AOT packaging Adds a new Claude Code skill that teaches developers how to build hybrid .NET 10 tool packages combining Native AOT performance with CoreCLR compatibility fallback. Key features: - Quick Start guide for ToolPackageRuntimeIdentifiers pattern - Complete build script reference with container builds - GitHub Actions CI/CD example with matrix strategy - Troubleshooting for common mistakes Based on: https://github.com/richlander/dotnet10-hybrid-tool Closes #2095 * fix: Add ImplicitUsings to .csproj examples The C# examples use Console.WriteLine without explicit using statements, which requires ImplicitUsings to be enabled for compilation to succeed. Found during code review.
1 parent 5111b26 commit b636ae6

File tree

3 files changed

+785
-0
lines changed

3 files changed

+785
-0
lines changed
Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
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

Comments
 (0)