Skip to content

Docs: update Native AOT support scope for v1.6 - #8701

Merged
Aaronontheweb merged 2 commits into
akkadotnet:devfrom
Aaronontheweb:docs/aot-support-scope
Oct 1, 2026
Merged

Aaronontheweb merged 2 commits into
akkadotnet:devfrom
Aaronontheweb:docs/aot-support-scope

Conversation

@Aaronontheweb

@Aaronontheweb Aaronontheweb commented Oct 1, 2026 •

Copy link
Copy Markdown
Member

Summary

docs/articles/deployment/native-aot.md dated back to #8608 and hadn't caught up with the AOT work merged since, or with how classic remoting actually behaves. This updates it to match dev.

What changed

  • What's verified today: added the Akka.Hosting canary (src/aot/Akka.Hosting.AOT.App) alongside the core one (src/aot/Akka.AOT.App) - both run in CI on every PR, each against its own warning baseline. Described what the canaries actually gate on (any Warning/Error logged at startup fails the run), not "nothing warns." Dropped the claim that a trimmed (non-AOT) publish is verified - CI only publishes with PublishAot.
  • Setup APIs: three take an instance or factory today - LoggerSetup, SerializationSetup, ExtensionsSetup - with BootstrapSetup as the optional fourth for config/scheduler. (Several other Setup types exist too - LogFilterSetup, NewtonSoftJsonSerializerSetup, DependencyResolverSetup - just not ones this page's HOCON-type-name story is about.)
  • Module serializer tables: noted that Remote, Cluster, the cluster-tools family, Persistence, and Streams now resolve their own serializer names from a built-in table, same as core. Named the real akka.extensions table entries (DistributedDataProvider, DistributedPubSubExtensionProvider, ClusterClientReceptionistExtensionProvider, ClusterMetricsExtensionProvider) instead of HOCON short names.
  • Remote/Cluster/Persistence wording - corrected after review: my first pass called this "not yet verified," which undersold a real break. Classic DotNetty remoting does not work under Native AOT: EndpointManager, FailureDetectorRegistry and TransportAdapters each resolve a HOCON type name with an unguarded Type.GetType, so a provider = remote app throws TypeLoadException: Cannot instantiate transport [...TcpTransport,Akka.Remote] at boot. Artery (akka.remote.artery.enabled = on) already ships on dev as an experimental opt-in, not a future target - it's just not covered by a CI canary yet. Akka.Cluster, Akka.Persistence and the cluster tools get their own bullet: serializers resolve from built-in tables, but downing-provider-class, the Persistence journal/snapshot plugin class, event adapters, the DData durable store, and a custom sharding state store all still go through unguarded Type.GetType - call these unsupported.
  • Remote deployment: corrected to the real site, Akka.Remote's DaemonMsgCreateSerializer.PropsFromProto (Type.GetType(protoProps.Clazz), no table, no guard), and separated it from Props.TypeName/PropsSurrogate, which is a different path - what a serializer carries a Props value through, not remote deployment specifically.
  • New gaps documented: stream refs with the switch off (SerializationTools.TypeFromString, Native AOT: 3 IL2xxx/IL3xxx warnings from the stream-ref serializer (Akka.Streams) #8667) and an uncached manifest on the base Serializer.FromBinary(byte[], string) (AOT: serializers resolve their own manifests; guard the TypeCache fallback #8697), including that Persistence's PersistentFSM.PersistentFSMSnapshot<> stays on that fallback.
  • Serialization: pointed to source-generated MessagePack serialization as the trim- and AOT-safe alternative for the default JSON serializer gap, and added a short tip on reading per-call-site trim warnings (TrimmerSingleWarn=false).

Verification

  • npx markdownlint-cli@0.31.0 "docs/articles/deployment/native-aot.md" - clean
  • Same, with --rules markdownlint-rule-titlecase@0.1.0 (matches DocsMarkdownLinting in build-system/pr-validation.yaml) - clean
  • npx cspell@6.12.0 --config ./docs/cSpell.json "docs/articles/deployment/native-aot.md" (matches DocsSpellcheck) - 0 issues
  • dotnet docfx build ./docs/docfx.json --warningsAsErrors - ran. dotnet docfx metadata fails on a fresh checkout of this worktree before anything else has built Akka.Remote - its source generator for ArteryControlMessageSerializer hasn't run yet, so docfx's own Roslyn pass sees an incomplete partial class. Not a dev-wide break; a dotnet build first would avoid it. The content build (docfx build) completed on its own with only pre-existing UidNotFound warnings from the missing API metadata; none reference native-aot.md.
  • Every claim in the "Not Supported Yet" list is backed by a direct source read, not inference: EndpointManager.cs:1036, FailureDetectorRegistry.cs:80, TransportAdapters.cs:96, ReplicatorSettings.cs:61, CustomStateStoreModeProvider.cs:36, EventAdapters.cs, Persistence.cs:106,340, DaemonMsgCreateSerializer.cs:95, SerializationTools.cs, and Serializer.cs's FromBinary(byte[], string).

native-aot.md predates several AOT milestones merged since: LoggerSetup
and ExtensionsSetup now exist, module serializer tables cover Remote,
Cluster, the cluster-tools family, Persistence and Streams, and the
Akka.Hosting.AOT.App canary now runs in CI alongside the core one.

Reword the Remote/Cluster/Persistence note from "unsupported" to "not
yet verified" - no canary boots an ActorSystem through any of them
under Native AOT yet, which is a different claim than classic DotNetty
remoting being broken. Call out Props-based remote deployment as its
own still-reflective path, and point to source-generated MessagePack
serialization as the trim-safe alternative to the default JSON
serializer for user messages.
The previous update overclaimed in both directions. Fix it against the
actual source, each site checked directly:

- Classic DotNetty remoting does not work under Native AOT, full stop:
  EndpointManager, FailureDetectorRegistry and TransportAdapters each
  resolve a HOCON type name with an unguarded Type.GetType, so startup
  throws TypeLoadException on the transport class. Artery already ships
  on dev as an experimental opt-in (akka.remote.artery.enabled, default
  off), not a future target - no CI canary covers it yet, though.
- Akka.Cluster, Akka.Persistence and the cluster tools: their own
  serializers resolve from built-in tables now, but downing-provider-class,
  the Persistence journal/snapshot plugin class, event adapters, the
  DData durable store (ReplicatorSettings) and a custom sharding state
  store (CustomStateStoreModeProvider) still go through unguarded
  Type.GetType. Call these unsupported, not "not yet verified".
- Split out remote deployment's real site, DaemonMsgCreateSerializer.
  PropsFromProto, from Props.TypeName/PropsSurrogate, which is a
  different path (what a serializer carries a Props value through).
- Added the stream-refs-with-the-switch-off case (SerializationTools.
  TypeFromString, akkadotnet#8667) and the uncached-manifest case on the base
  Serializer.FromBinary(byte[], string) (akkadotnet#8697), including Persistence's
  PersistentFSM.PersistentFSMSnapshot<> staying on that fallback.
- Setup list was wrong: three types take an instance/factory today
  (LoggerSetup, SerializationSetup, ExtensionsSetup), with BootstrapSetup
  as the optional fourth - not "four" as peers.
- Named the real akka.extensions table entries (DistributedDataProvider,
  DistributedPubSubExtensionProvider, ClusterClientReceptionistExtensionProvider,
  ClusterMetricsExtensionProvider) instead of the HOCON short names.
- Dropped the trimmed-publish claim CI doesn't check, described what the
  canaries actually gate on (a Warning/Error log at startup) instead of
  "nothing warns", and added a short tip on reading per-call-site warnings.
@Aaronontheweb
Aaronontheweb merged commit dd0de31 into akkadotnet:dev Oct 1, 2026
16 checks passed
@Aaronontheweb Aaronontheweb added docs AOT Ahead-of-Time (AOT) Compilation labels Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

AOT Ahead-of-Time (AOT) Compilation docs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant