Development documentation · Some APIs may be unreleased Published release →

Guides

Native compilation

Ahead-of-time compilation turns a supported Raven application into a native executable. AOT is the intended deployment path; the development CLI also supports JIT execution and an interpreter for testing and constrained environments.

Development: default method inlining

JIT and AOT enable the backend’s speed optimizations and independently inline small, safe integer/Boolean leaf methods. Instruction selection follows the target architecture. MethodImplOptions.NoInlining opts out; AggressiveInlining permits a larger candidate budget but cannot bypass safety limits. There is no Inlining flag. Calls, branches, allocation, virtual dispatch and faulting operations currently remain ordinary calls. Small SDK helpers benefit without annotations. These are unreleased development changes; see the contract and validation.

Choose an execution mode

Mode Use it for Compilation happens
JIT Development and running bytecode with the matching native backend During execution
Interpreter Portable execution and checking interpreter behavior No native code compilation
AOT Publishing a target-specific executable Before deployment

A matching development JIT bundle selects JIT by default. Select interpreter mode explicitly when needed. API support in one mode does not automatically establish support in every other mode or target.

Development: lazy JIT

Post-Preview-18 source builds have an opt-in lazy backend (NEOCLR_JIT_LAZY=1). Method bodies are lowered and compiled to machine code on first call through stable trampolines; metadata verification remains eager. This can reduce preparation work but adds cold-call latency and retains an indirect call after warmup. Eager compilation and synchronous GC remain the defaults. This is not a published Preview 18 capability.

Design and matched startup/HTTP measurements cover synchronous and concurrent GC separately, including limitations.

The development follow-up uses a bounded arena with system fallback for lazy JIT on macOS ARM64. It improves measured warm HTTP throughput while retaining first-use compilation waits. A compiler worker does not yet let other managed tasks proceed during that wait. Profiling and workload tradeoffs compare both collectors and explain why startup, tail latency, CPU and sustainable load must be considered separately.

Shared native selection and generic expansion reuse temporary immutable metadata indexes, preserving verification and lazy method counts. The paired startup follow-up records improvements and regressions separately for eager/lazy JIT and both collectors.

Build a native application

Raven produces neoCLR metadata and instructions. The AOT tool lowers them to object code and links the required runtime services and libraries. The executable does not need a separately installed neoCLR or .NET runtime, though it still uses host system libraries. Build tooling requires the matching SDKs and native toolchain.

Target Console profile HTTP profile Native tools
macOS ARM64 console http Apple's macOS tools
Windows x64 windows-console windows-http MSVC x64 tools

The macOS development kit supports project builds without a source checkout or Cargo. Its development HTTP profile includes a prebuilt native TLS provider needed by the current networking code; explicit HTTPS-server configuration remains source-only. Windows currently uses a source-checkout workflow. Windows ARM64 is not qualified. See development setup and the project-to-executable instructions.

Keep application code asynchronous

The HTTP server uses an ordinary async entry point:

async func Main() -> Task<()> {
    let Ok(server) = HttpServer.Listen("127.0.0.1", 8080, 64) else {
        Panic("Could not listen")
    }
    let result = await server.Serve(Handle)
    server.Close()
    if let Failure(error) = result {
        Panic(error.ToString())
    }
}

The host drives completions while the program awaits I/O. Application entry points do not need explicit completion callbacks. Arguments can be accepted through Main(arguments: string[]); they exclude the executable name and preserve Unicode.

HTTP client and server guide · Complete server case

Retain metadata used dynamically

Directly referenced code is visible to the compiler. Reflection and object mapping also need the types and members they discover at runtime. Development JIT accepts --reflection-roots roots.json to retain them; packaged sample runners prepare the appropriate roots. The interpreter does not accept that option.

Development native project builds now read <project>.retention.json beside the .rvnproj file. Each entry declares an exact type name and the capabilities needed:

{
  "schemaVersion": 1,
  "types": [
    {
      "name": "Examples.DependencyInjection.Greeter",
      "retain": ["constructors"]
    }
  ]
}

This is the checked-in policy used by the native DI sample. Supported modes are constructors (checked activation), properties (construction plus property getters/setters for object mapping), and methods (inspection only). They can be combined. --retention-file config/native.json selects a different file relative to the project directory. Invalid declarations and conflicts with legacy reflection-policy arguments fail the build. Generic definitions retain only the supported closed shapes known to compilation. This does not add automatic JIT file discovery.

Development DynamicallyAccessedMembers analysis can now infer constructor/property retention from known type tokens passed through annotated TypeInfo parameters, returns, fields, properties and method receivers, or supplied to annotated type/method generic parameters. Parameterless constructor/property introspection declares receiver requirements. JSON deserialization and DI registration APIs carry corresponding requirements. Unknown flows produce diagnostics. Additional member categories, arbitrary closed generic reflection targets and dynamic implementation analysis remain incomplete. Explicit files are still needed for unsupported flows. Attribute API reference. Inferred constructors and property accessors are also analyzed for further annotated calls, including cycles; types discovered through arbitrary storage or reflection descriptors still need explicit retention. Executable bodies admitted by project retention files also seed annotation analysis; metadata-only policies do not gain invocation rights. Nongeneric class/interface parameter annotation mismatches are reported as DAM2005. Nongeneric reference-class overrides are checked against their nearest base declaration with DAM2006; generic mappings, generic derived classes and value-type overrides remain outside these checks. Closed generic base classes of nongeneric derived classes are included in DAM2006; this does not add generic-parameter annotations.

Use matching compiler and library builds for native JSON, attributes and reflection. Qualified examples cover specific supported shapes; they do not imply unrestricted .NET reflection or support for arbitrary library code.

Qualified HTTP workloads

The shared HTTPS/JSON consumer and failure checks cover macOS ARM64 and Windows x64 in interpreter, JIT and AOT modes, including certificate rejection, recovery, deadlines and cancellation. Windows also has TLS 1.2/1.3 interoperability checks.

Coverage depends on the exact runtime, compiler and async lowering. See the qualification record and runtime-await qualification for tested builds. Downloads identify published availability.

Measured output and installation size

Development measurements from 21 October 2026, on macOS ARM64. These are real outputs from two tested programs, not promised sizes for every application.

Application neoCLR application assembly Complete AOT executable
Unicode console greeting 85.04 KiB 94.96 KiB
JSON object-mapping sample 380.28 KiB 9.37 MiB

Both executables ran successfully and depend only on macOS libSystem. The AOT column includes linked runtime services and selected application/library code. The assembly column excludes the shared class libraries and execution engine it needs to run; it is not a complete deployment size. These builds use the release backend and the default clang -O2 link configuration, with no extra stripping step. The JSON sample retains its object-mapping metadata.

Build tools are a separate installation cost

Development package Installed file bytes Compressed archive
Raven SDK: compiler and language server 89.98 MiB 31.69 MiB
Complete neoCLR JIT toolchain bundle, including that SDK 151.93 MiB 53.48 MiB

The complete bundle also includes the runtime/backend, class libraries, editor extension, samples and documentation. Its class-library directory accounts for 19.14 MiB, including documentation. These are overlapping quantities, not amounts to add together. Sizes use logical file lengths (1 KiB = 1,024 bytes; 1 MiB = 1,048,576 bytes), excluding filesystem block rounding and generated caches. External .NET SDKs and Apple build tools are prerequisites and are not included in these installation figures. Neither SDK is needed to run the AOT executables.

The JSON example is substantially larger than the greeting: this baseline makes that cost visible rather than implying that every native application is tiny. Further size optimization needs its own measurements. This study does not qualify HTTP workloads or establish Windows output sizes.

Exact byte counts, hashes and build inputs · Measurement method and reproduction

Current limits

Development after Preview 16: the native backend and matching host now admit up to 4,096 selected methods. The rebuilt macOS ARM64 HTTP JSON sample uses 2,055 methods and passes server requests and a client/server exchange in both JIT and standalone AOT. This is source-build validation; refreshed installed packages and Windows qualification remain pending. The bound is an experimental backend limit, not a Raven language rule.

Native support remains experimental. Generic virtual dispatch and some runtime services have incomplete target coverage. The HTTP showcases are bounded HTTP/1.1 applications, not a promise of arbitrary concurrent server support. HTTPS needs explicit credentials and trust, and qualification depends on the host and build kit. See the TLS contracts.

AOT does not remove allocation, garbage collection, scheduling or I/O costs. Workload, startup and deployment size should be measured separately.

General execution benchmarks · HTTP benchmark matrix · Runtime architecture

Native interoperability direction

Native compilation is the primary deployment direction for Raven on neoCLR; JIT and interpretation remain useful execution options. Development NativeImport support covers the interpreter and an opt-in macOS ARM64 scalar AOT proof for free Int32/native-sized-integer/pointer C functions, now qualified from Raven source with explicit metadata dependencies and C allocation/release. The development scalar JIT probe now reuses the same import path behind explicit opt-in, including Raven source metadata with explicit verification dependencies. Full managed-program AOT imports, managed JIT imports and managed-memory pinning remain gaps. Current scope.

The development interpreter also provides explicit NativeMemory.Copy overloads for slices and tracked native allocations, including Memory windows and UTF-8 byte views. These avoid an intermediate managed transfer array; they still copy bytes. Copy contract and limitations

The next foundation connects native calls with pointers, stack and heap allocation, and explicitly scoped access to managed buffers. A true pin must retain existing storage at a stable native-compatible address; an explicit copy is a separate operation.

Longer term, referenceable metadata for native implementations, an extended native hosting API and dynamic dispatch should let different languages use runtime services and each other's components. Those languages need not share one memory-management strategy. These are future directions, not available component APIs. Trusted native imports also remain distinct from sandboxed VM execution.

Interop direction and completion gates

A source-only development experiment runs 1–4 isolated HTTP application workers against one listening socket. Heaps, statics and async state remain per worker; shared-object GC qualification is a separate gate before shared-heap parallelism. This provides server primitives, with no new application framework or change to the default host. Experimental contract and evidence.

The private worker experiment tests concurrent native reads and separately synchronized native mutations of shared objects. GC waits for active phases to yield, retaining explicitly published roots. An opt-in compiler profile now also runs synchronous generated callbacks on one shared heap, with participant root publication and coordinated GC. Optimized/UBSan tests cover four active participants, disjoint graph mutation and isolated faults. Allocation/helpers remain serialized; shared async HTTP and throughput qualification remain open. Development evidence.