Development documentation · Some APIs may be unreleased Published release →

Guides

Foreign-function attributes

Development, interpreter execution: System.Runtime.InteropServices contains NativeImportAttribute, MarshalAsAttribute, NativeCallingConvention, NativeStringMarshalling and NativeType. Matching source compiler/runtime changes are required; installed bundles and general JIT/AOT imports are not yet qualified. A separate bounded scalar AOT profile supports numeric/pointer C imports and scalar JIT execution.

API Contract
NativeImportAttribute(libraryName: string) Metadata for an extern namespace function or static method. The name/path is required and must contain no NUL when used as an import. Construction does not load native code.
LibraryName: string (read-only) Supplied library loader name/path.
EntryPoint: string (read/write) Exact export; omission uses the source name. Explicit empty/NUL names are rejected at emission.
CallingConvention: NativeCallingConvention (read/write) Cdecl (0, default) or System (1). System uses stdcall on 32-bit Windows and C elsewhere.
StringMarshalling: NativeStringMarshalling (read/write) None (0, default), Utf8 (1), Utf16 (2). Applies only to otherwise unannotated String parameters.
MarshalAsAttribute(nativeType: NativeType) Overrides one parameter or result. No conversion occurs when constructing the attribute object.
MarshalAsAttribute.Value: NativeType (read-only) Utf8 (0), Utf16 (1), Bool8 (2), Bool32 (3).

Utf8/Utf16 support input String parameters only. Buffers are NUL-terminated and live through one call. Embedded NULs fault before entry; buffers must not be modified, retained, freed or returned by native code. UTF-16 means native-endian 16-bit code units, not platform wchar_t. Empty strings have a non-null terminator-only buffer.

Bool8/Bool32 support Boolean parameters and [return: MarshalAs(...)] results. Input is 0/1; any nonzero result is true. Without a descriptor Boolean is rejected. Parameter overrides win over the function's string default. Scalar/pointer arguments use their declared ABI directly; incompatible descriptors are rejected.

Diagnostics reject unsupported conventions, signatures, attribute owners, duplicate or invalid attributes, generics, instance imports, managed bodies and unspecified string/boolean conversion. Runtime validation also checks descriptors, parameter indices and body/entry-point restrictions. Missing library/export produces a terminal Fault on first invocation. Incorrect actual native signatures or lifetimes can corrupt memory or crash; they are not generally discoverable from export metadata.

See the tested source shape and full contract and website guide. Returned strings, buffers with declared length/ownership, record layout, platform-error capture and retained callbacks remain open. The generated type/member reference includes all five types; no API is excluded.

Raven callback parameters (development, 2026-10-22)

A NativeImport parameter may be a structural function, such as (int) -> int or (int) -> unit. The callback uses the import's convention. Numeric scalar arguments and numeric/no-result returns are supported; native code must invoke it synchronously on the calling thread and must not retain it. Captures and receivers remain rooted through the call. Callback faults are delivered after native code returns.

Raven retains unit syntax, mapping logical values to System.Void. For a unit callback the native emitter generates a managed source-facing wrapper and an internal C import with a true no-result Function parameter. The adapter invokes the managed Function and discards its unit value. This also preserves a generic return closed over unit. The source-facing wrapper is an ordinary managed method in emitted metadata; NativeImport metadata belongs to the internal thunk. The adapter currently allocates per call; no allocation-free callback claim is made. There are no new guest attributes. An import may also return (int) -> int or (int) -> unit, mapping the native function pointer to an ordinary Raven Function. The runtime retains loaded libraries through that binding; it does not own foreign context/state. Null or tracked-data addresses fault at binding. For unit results, the compiler emits an adapter around the returned no-result Function, materializing System.Void after each invocation. That adapter and binding allocate once per returned result; ordinary numeric results need no additional compiler adapter. The result can itself be passed as a call-scoped callback. Callback strings, Boolean widths, pointers, nested callbacks, retained registration lifetimes and JIT/AOT callable execution remain open.

Structural pointer binding experiment

Main includes development interpreter/neoIL address mapping through function.bind.native. It produces the existing structural Function type, not a delegate. Contract and restrictions. No new guest attribute or RavenDoc type is introduced.

The Rust metadata API adds metadata::NativeAbi and Instruction::BindNativeFunction { function_type: Type, abi: NativeAbi }. The ABI record has public fields calling_convention: CallingConvention, string_marshalling: Optional<NativeStringMarshalling>, parameter_marshalling: BTreeMap<String, NativeMarshalling> and return_marshalling: Optional<NativeMarshalling>. From<&NativeImport> copies only ABI/conversion fields, excluding library/export identity. Validation uses the same rules as named imports; zero-based keys must be canonical decimal strings. The function_type must be a supported structural Function signature. The instruction consumes a pointer and produces that signature's Function value. Unsupported shapes, conversions and output contracts fail validation; null/tracked data addresses fail at binding. Loading metadata never resolves the pointer.

Trusted execution is required both to bind and invoke. Native wrappers retain the loaded library owners, but external pointers still need an explicit host lifetime guarantee. Clones share binding identity; independent mappings are distinct. Direct scheduler submission requires a managed wrapper. The independent C# metadata API and Raven emitter do not yet author this instruction; public AOT exports and sidecar generation remain design work.

Callable ABI metadata

Both Rust metadata::NativeImport and metadata::NativeAbi additionally expose:

Field Type and meaning
callback_parameters BTreeMap<String, NativeAbi>: canonical zero-based parameter index to that callable's independent ABI. Empty by default and omitted in serialization.
function_return Optional<Box<NativeAbi>>: ABI of a returned native pointer mapped to the declared structural Function. None by default and omitted in serialization.

From<&NativeImport> copies these fields as well. The new public fields require updates to Rust struct literals; wire records without them retain their previous meaning. A matching runtime is required for records containing them. No new guest attribute or generated RavenDoc type is introduced; this manual entry documents the experimental Rust API. The independent C# metadata API now authors the bounded scalar subset through NativeCallbackDefinition, CallbackParameters and FunctionReturn; see host API reference.

Callback parameters require an exact non-null Function and a scalar callable shape. Numeric types, explicit Bool8/Bool32 and void/no-result returns are supported. The runtime retains the captured receiver, generates a call-duration entry stub and reenters the same managed invocation on the calling thread. Managed faults are caught at the stub, return zero/false to native code and propagate when the foreign call returns. Later callbacks in that call do not execute guest code after a fault. Native code must not retain the pointer. Retention beyond the call needs a future explicit ownership/release contract. The author's extern examples illustrate callable parameters and results; they do not prescribe registration behavior. Suspension and other-thread entry are unsupported.

A returned pointer becomes a library-retaining Function using function_return. Null, tracked-data and current temporary callback addresses are rejected. Provider library retention cannot guarantee arbitrary native state/code lifetime. Callable ABI nesting is limited to eight; native callback reentry is limited to 32 and the remaining managed frame budget. See the tested example and complete boundaries.

NativeMemory.Copy (development)

The System.Runtime.InteropServices.NativeMemory module adds two unsafe overloads, implemented by System.Runtime.dll and currently executable in the interpreter:

unsafe func Copy(source: ReadOnlySlice<byte>, destination: *System.Void, destinationByteCount: nuint)
unsafe func Copy(source: *System.Void, sourceByteCount: nuint, destination: Slice<byte>)

The first copies all source bytes; destinationByteCount is the available capacity and must be at least source.Length. The second copies exactly sourceByteCount bytes and leaves the rest of the destination unchanged. Memory windows project through existing slice conversions; String.Utf8Bytes can be used as read-only input. These operations create no intermediate managed transfer array and retain neither buffer. They perform explicit copies; they do not pin managed storage or transfer ownership.

Both overloads require live, tracked NativeMemory.Alloc storage for nonempty native ranges. Empty copies do not dereference pointers and accept a null address. Invalid ranges, insufficient capacity, uninitialized source bytes, read-only output, freed storage and native allocations currently borrowed by a foreign call cause runtime faults. Validation occurs before writes for supported single-consumer use; concurrent mutation of the managed buffer is unsupported. These checks do not make arbitrary foreign addresses safe or admit foreign-owned pointers.

Foreign writes do not currently update the interpreter's initialization tracking. Initialize the native range before passing it to an imported function that will mutate it; a C output write alone does not qualify an uninitialized range for Copy. The built-in native-buffers fixture copies input first, invokes an in-place C byte increment, and copies back into a Memory subview. JIT/AOT execution, true pinning and persistent native-backed Memory ownership remain open.

Bounded AOT import execution (development)

neoclr-codegen --native-imports enables the macOS ARM64 scalar AOT backend's existing NativeImport descriptors for nongeneric free functions with at most 16 parameters, using Int32/UInt32, Int64/UInt64, Single/Double, IntPtr/UIntPtr or raw pointer metadata to Void, Byte or Int32 for parameters and results, or no-result Void returns, without marshalling. Pointer locals and helper calls preserve native address width. Explicit pointer casts, implicit void-pointer erasure and null/default pointer values are supported within the same pointee set. Casts retain address bits without reading storage. Raven's local-address/default initialization is lowered only for exact scalar locals; managed local addresses cannot escape as native pointers. Unsupported layouts, mismatched types and integer-to-pointer conversion still reject. IntPtr/UIntPtr transport uses 64-bit registers/storage on this target. Unchecked integer widening/narrowing is supported for native sizes, including unsigned widening and low-bit truncation; native-width arithmetic, checked conversions and pointer/integer conversion remain rejected in this profile. The public Ptr<T> wrapper is not automatically projected yet. Managed/value profiles, class members, other types, callbacks, managed JIT and SDK integration remain unsupported. The flag is required; the default still rejects imports.

Development source qualification accepts explicit --system, --module and --object-root inputs to verify Raven's original metadata references. A load context requires --system; ordinary loader/verification errors reject before output. These libraries are verification inputs, not emitted managed code. Scalar restrictions and external-managed-call rejection remain in force. Use @entry for the Raven executable entry point. The tested Raven consumer performs C allocation, pointer transport and no-result release; no neoIL intermediary is involved.

Link runtime/native/interop/imports.c into the executable. Its private adapter neoclr_native_import_resolve_v1(const char *library, const char *symbol, void **output) returns 0 on success and 3 (RuntimeError) on failure, leaving output unchanged on failure. Inputs are valid NUL-terminated UTF-8 metadata strings; output points to writable pointer storage. This helper is a provisional runtime implementation ABI, not the future public native hosting API. Successful lookups retain code ownership until process exit, with a 256-entry library/symbol cache. Failed lookups can retry.

Generated thunks preserve the existing private managed status/result ABI while calling the native C ABI. No interpreter fallback, managed object marshalling or sandbox guarantee is provided. See reproduction and limitations.

Within this profile, imports and scalar helpers with the existing no-result Void contract produce no operand-stack value. C void calls have no return register; success leaves the private result slot untouched. Missing symbols still fault before continuation and preserve the exported caller's result. The distinct Void value carrier is not supported by this profile, and the host entry remains Int32-returning.

Development AOT pointer checks

The opt-in macOS ARM64 scalar NativeImport profile accepts pointer equality and null checks, and equality/zero tests for native-sized integers. Comparisons preserve all address bits and do not dereference memory. Raven can check a native allocation against default(*int) before use. A non-null pointer does not prove ownership, allocation lifetime or accessible bounds; ordered pointer comparisons remain outside this profile. Managed memory pinning remains unimplemented.

Development AOT native memory access

The same trusted scalar profile supports direct Byte/Int32 pointer reads and writes. Raven can dereference an imported allocation, update it and release it through the native owner. Null and misaligned Int32 access returns a runtime fault. Bounds, initialization and lifetime are the caller's responsibility; other invalid addresses can crash the process. This does not expose managed storage or provide pinning, native-backed Slice borrowing or managed-library AOT integration.

Development scalar JIT imports

--jit-scalar <input> <root> <Int32 argument> --native-imports enables the same bounded import signatures and pointer operations in the macOS ARM64 development JIT probe. It shares the AOT C resolver and library ownership; the default rejects imports. With this opt-in it accepts trailing --system, --module and --object-root inputs and @entry, using the same verification rules as AOT. Dependencies are verification-only; this does not enable imports in the ordinary managed JIT/SDK pipeline.

Qualified transport across engines

A common Raven consumer now passes in interpreter, scalar JIT and AOT for native allocation/read/release calls, pointer transport and null checks, no-result returns, and native-sized integers. Reads are performed by the C owner. Direct dereference of untracked foreign storage remains unsupported in the interpreter; a returned pointer does not establish bounds or lifetime. The separate direct Byte/Int32 memory-access example is qualified only in the trusted scalar JIT/AOT profiles. This does not establish full managed-library, callback or pinning parity.

Fixed-width 64-bit transport (development, 2026-10-22): the opt-in macOS ARM64 scalar JIT/AOT import profile now admits Int64/UInt64 parameters, results and locals, including private helper calls, defaults and equality/zero checks. The shared Raven transport consumer exercises negative signed and high-bit unsigned values against C int64_t/uint64_t functions across interpreter, JIT and AOT. This follows ordinary .NET fixed-width integer ABI semantics; it adds no wrapper, marshalling allocation or new metadata representation. Arithmetic expansion, 64-bit pointer dereference and broader managed import composition remain open.

Floating-point transport (development, 2026-10-22): the same opt-in scalar ABI now admits Single/Double parameters, returns, locals, constants and defaults. The shared Raven consumer checks negative zero, infinity, quiet-NaN payloads and finite values through helper calls and mixed C arguments, including floating-point arguments spilled to the stack. It preserves their declared F32/F64 representation, following the platform C ABI as .NET interop does; no marshalling allocations are introduced. Arithmetic, floating-point comparisons/conversions and pointer loads remain outside this bounded profile.

Unsigned 32-bit transport (development, 2026-10-22): UInt32 now shares the I32 storage ABI with Int32 while retaining its metadata type. The existing conv.u4 operation truncates wide values without changing their low bits; conv.u8/conv.u zero-extend 32-bit inputs. The Raven consumer checks a high-bit uint identifier through locals/helper calls, widening to ulong/nuint and narrowing from ulong against C uint32_t/uint64_t/uintptr_t parameters. This matches ordinary fixed-width .NET/C interop semantics without allocating wrappers or adding metadata.

Development native library exports

The backend --native-library input output.o --export Function command emits explicitly selected, nongeneric free functions using the platform C ABI on macOS ARM64. It admits the scalar numeric/pointer types listed above, with no-result returns mapped to C void. Helpers remain local; the experimental host entry is not exported. The native linker produces a library from this object. Source functions annotated with NativeExportAttribute are selected automatically; explicit CLI selection remains available for backend fixtures.

NativeExportAttribute

System.Runtime.InteropServices.NativeExportAttribute has three constructors: NativeExportAttribute(), NativeExportAttribute(entryPoint: string), and NativeExportAttribute(entryPoint: string, callingConvention: NativeCallingConvention). Its read-only EntryPoint: string and CallingConvention: NativeCallingConvention properties describe the requested boundary. An empty entry point uses versioned mangling; a nonempty name is exported exactly. Cdecl is the default; System is also accepted on macOS ARM64, where both use the same platform ABI. Duplicate attributes/symbols, null or NUL-containing names, unsupported conventions, managed signatures and instance methods reject before output.

Pass --header exports.h to emit a matching C/C++ header. It uses fixed-width integer types, native pointer types and C linkage guards. Explicit names must be C/C++ identifiers and cannot be keywords when generating a header. Existing output files are preserved; failed header creation removes the newly created object. The header identifies its macOS ARM64 target. No function-pointer parameter, closure lifetime, managed object marshalling or metadata sidecar contract is introduced by this increment.

Symbol names encode stable source identity and signature using the versioned neoclr_c_v1_ convention. The JSON build report lists exact logical EntryPoint names for NativeImport; it is not a runtime metadata sidecar. Guest faults escaping an export trap and terminate the process. Pointer bounds and lifetime remain the native caller's responsibility. Existing files and invalid export selections are not overwritten. Detailed ABI and naming contract.

Native struct layout attributes

StructLayoutAttribute(LayoutKind) applies to structs. LayoutKind.Sequential places fields in declaration order; Explicit requires FieldOffsetAttribute(int) on every instance field and permits overlap. Auto is represented in metadata but rejects at the native boundary. StructLayout.Value and FieldOffset.Value expose the constructor arguments. Pack and Size are writable integer properties.

Pack = 0 selects eight on the current macOS ARM64 backend. Explicit packs must be powers of two from one through 128. Size is a nonnegative minimum byte size; field extents and alignment can increase the actual size. Negative offsets, missing explicit offsets, unsupported packing, reference fields and incompatible field marshalling reject before native output. Generated C/C++ headers assert native size, alignment and offsets. Explicit layouts use named union views in the C header.

MarshalAsAttribute(NativeType) now accepts instance fields of value types. Boolean fields default to native four-byte BOOL; Bool8 selects one byte and Bool32 explicitly selects four. Other field conversions are not implemented. These attributes describe native storage. They do not pin or automatically copy managed instances, change managed field access, or admit by-value struct calls. Unlike .NET's broader marshalling surface, this development increment is limited to checked native struct pointers in macOS ARM64 native libraries.

import System.Runtime.InteropServices.*

[StructLayout(LayoutKind.Sequential, Pack: 1)]
public struct Packet {
    [MarshalAs(NativeType.Bool8)]
    field Flag: bool
    field Value: int
}

This native layout occupies five bytes. Caller-owned memory must have the layout, alignment and lifetime expected by the native function. The backend tests compile this declaration and explicit overlapping layouts with C11/C++17 callers.

Generated Raven imports

neoclr-codegen --native-library accepts --raven-imports Imports.rvn --import-library <loader-name-or-path> in addition to --header exports.h. Both Raven options must be supplied together. The loader name is explicit because producing an object file does not determine the final library name. Existing output files are preserved on failure.

The file imports System.Runtime.InteropServices, declares numbered free functions NativeExport0, NativeExport1, etc. with exact NativeImport entry points, and includes explicit native-layout struct declarations where required. Generated field types describe native storage widths (for example a Bool8 field is byte), rather than promising managed conversion. Symbol order follows the export report. Pointer ownership remains the caller's responsibility. This is binding source, not a runtime metadata sidecar or a general C header importer.

Generated struct consumers are qualified in the interpreter and opt-in macOS ARM64 scalar JIT/AOT executable profiles, including nested fields and recursive pointer layouts. Supply matching runtime metadata with the explicit load-context options. Executable generation verifies the full source before selecting the entry point and direct-call dependencies. This does not enable the ordinary managed JIT/AOT pipeline or automatic managed-storage conversion.

In the macOS ARM64 scalar JIT/AOT profile, each compiled import caches a successful resolved address. Warm calls bypass the resolver mutex and lookup. Cold concurrent callers may resolve redundantly; publication is atomic and failures remain retryable. Library handles remain owned by the shared resolver for process lifetime. This does not change marshalling support or enable unloading an imported library.