Chapter 2: Native mode overview

Chapter 1 got a program running. This chapter steps back and explains what the two native modes, host.native and host.dual, mean to the compiler: where they sit among Loup's six modes, what they share, how they differ, and which parts of the language a native binary cannot run yet. The rest of the book builds on this picture.

Loup's six modes

Every Loup file declares a mode on its first line. The mode decides where the code runs (a browser, an operating-system process, or bare metal), how it is delivered (interpreted, compiled ahead of time, or either), and which features it may use (Language Reference §1-2.4):

This book covers the two middle rows. Scripts have their own book (The Loup Scripting Book), and so do browser code (The Loup Web Book) and firmware (The Loup Freestanding Book).

The directive must be the first token in the file; comments may precede it. A later directive is E_MODE_POSITION, a second one is E_MODE_DUPLICATE. If a file has no directive, the project's [build] mode applies, and failing that the file is a host.scripted script, so always write the line.

What the two native modes share

host.native and host.dual are both ahead-of-time modes. That gives them the same structure:

• main() is the entry point. The runtime calls it after the module is initialized. It takes no parameters and returns void or int (ruling MAIN-1).
• No top-level statements. Only declarations and constant initializers may appear at module scope. Anything else is E_TOPLEVEL_CONTROL_AOT.
• Static types are expected. Every parameter and return type is declared. Any still compiles, but it produces a warning, because the compiler has to fall back to dynamic dispatch:

@mode(host.native)

func show(x: Any): void {
    println(x);
}

func main(): void {
    show(3);
}

Listing 2-1: Any compiles in an AOT mode, with a warning

3
main.lphc:3:14: warning: W_ANY_IN_AOT_MODE: use of `Any` in host.native mode prevents AOT specialisation — consider a static type if performance is critical
main.lphc:3:14: warning: W_ANY_IN_AOT_MODE: use of `Any` in host.native mode prevents AOT specialisation — consider a static type if performance is critical

loup run prints warnings after the program's own output (Stage0 1.25.1 prints this one twice). The program still runs; a warning never stops a build.

• ARC memory semantics. Class instances are reference-counted; structs, enums, tuples and collections are values that are copied (Language Reference §1-8.1.1). Chapter 9 covers this in detail. This is not a difference from the other modes: every mode presents the same reference-counting semantics, and none of them uses a tracing garbage collector.
• The ownership system. Parameter verbs (reads, edits, takes, shares), modifier methods, safe { } blocks, borrow, and unique bindings are checked at compile time in every mode. Native programs lean on them most, because they decide when reference counts change and who may mutate what. Chapters 15 to 18 cover them.

Here is a small program that uses several of these pieces: a class with a modifier method, a safe block that permits calling it, a dictionary, and string methods.

@mode(host.native)

class WordCounter {
    var counts: dict[string, int] = {};

    pub modifier func add(word: string): void {
        let w = word.toLowerCase();
        let current = this.counts.get(w) ?? 0;
        this.counts[w] = current + 1;
    }

    pub func count(word: string): int {
        return this.counts.get(word) ?? 0;
    }

    pub func vocabularySize(): int {
        return this.counts.length();
    }
}

func main(): void {
    let text = "the cat and the hat and THE bat";
    let wc = WordCounter();
    safe {
        for (w in text.split(" ")) {
            wc.add(w);
        }
    }
    println(i"'the' appears {$ wc.count("the") $} times");
    println(i"{$ wc.vocabularySize() $} distinct words");
}

Listing 2-2: A word counter

'the' appears 3 times
5 distinct words

A few things to notice:

• The field counts is a var, and only a method declared modifier may write to it.
• wc is a reference-counted class instance, and calling a modifier method on one requires a safe { … } block (or a safe func). That is where the compiler checks that nothing else is mutating the same object at the same time. Chapter 15 explains the rule.
• counts.get(w) returns an Option[int]; ?? supplies the value to use when it is None.
• Fields without pub are private to the class.

Choosing between host.native and host.dual

The two modes accept almost the same language. The difference is how the code may be delivered, and that decides which features are allowed.

host.native is for programs whose deliverable is a native binary. It permits the features that only make sense when Loup compiles straight to machine code: unique class (single-owner class types, chapter 17), inline asm { } blocks (chapter 19), and volatile borrow parameters and Volatile[T] for memory-mapped device access.

host.dual is for code that must also run without the native toolchain: on the interpreter with loup run, as WebAssembly with loup-bootstrap build and loup-launcher, or as a packaged app with loup-bootstrap build --target desktop. Because a host.dual file must behave the same on every path, the features that need direct machine-code generation are refused there. Today a host.dual program is also the way to use the two features that native binaries cannot run yet, template fences and async, on the interpreter or in a WebAssembly build.

Choose host.native when you ship a binary and want the native-only features. Choose host.dual for libraries and tools that should work everywhere, including Windows and Linux arm64, where native builds are not available yet. Every host.dual file is also a valid host.native file, so moving from dual to native is a one-line change; the reverse may not be.

Mistake: a native-only feature in a dual file

A unique class lives in exactly one place at a time, and the compiler moves it rather than counting references. That cannot round-trip through the other delivery paths, so host.dual rejects it:

@mode(host.dual)

unique class FileLock {
    pub let path: string;
    new(path: string) { this.path = path; }
}

func main(): void {
    let lock = FileLock("/tmp/app.lock");
    println(lock.path);
}

main.loup:3:1: error[E_UNIQUE_CLASS_ARC_BINDING]: E_UNIQUE_CLASS_ARC_BINDING: `unique class 'FileLock'` is only valid in `@mode(native)` or `@mode(freestanding)`

The message still uses the retired name native for host.native. There are two fixes. If the program will only ever be a native binary, change the first line to @mode(host.native) and rename the file to .lphc:

@mode(host.native)

unique class FileLock {
    pub let path: string;
    new(path: string) { this.path = path; }
}

func main(): void {
    let lock = FileLock("/tmp/app.lock");
    println(lock.path);
}

Listing 2-3: unique class is a host.native feature

If the code must stay portable, keep host.dual, declare an ordinary class, and give the one binding that owns it single-owner semantics with unique let lock = FileLock(…). unique let works in every mode; chapter 17 shows how.

Inline assembly is the other common case:

@mode(host.dual)

func cpuPause(): void {
    asm { "pause" }
}

func main(): void {
    cpuPause();
}

main.loup:4:5: error[E_ASM_NOT_COMPILED]: E_ASM_NOT_COMPILED: `asm { }` is only valid in a compiled mode (`web.compiled`, `host.native`, `freestanding`); the module mode is `host.dual` (§3-3.7)

Here there is no portable alternative: assembly is machine code for one architecture, so the function belongs in a host.native file.

What native binaries cannot do yet

Loup 1.25.1 builds native binaries for a large part of the language: value types, strings, collections, classes with reference counting, interfaces, closures, enums and match, and exceptions. Some features that the specification lists for host.native are not implemented in the native code generator, or not shipped in the standard library, yet:

When a native build meets one of these, it stops with an E-BUILD-NATIVE error that names the construct rather than producing a binary that behaves differently. For example, building a program with an async func:

error[E-BUILD-NATIVE]: unsupported in managed native (libc foundation): async function `half` (native builds have no task scheduler: `async`/`await` run on the interpreters only); …

The chapters that cover these topics say exactly what works today and mark the rest ⚠ Planned.

Coming from another mode

From scripts (host.scripted). The language is the same; the structure changes. Code moves into main() and functions, every parameter gets a type, and Any becomes a warning. You will start writing ownership verbs, because a native program's correctness depends on who may mutate what. The __name__ == "__main__" guard has no purpose in an AOT mode, since main() is always the entry point.

From the browser (web.*). Host capabilities such as the file system (readText, writeText), processes (exec) and the environment (runtime.args(), env) are available. There is no DOM.

From freestanding. You gain the runtime: reference-counted classes, exceptions, growable collections and the standard library. You lose @entry, @interrupt, @naked and the manifest's panic policy, which exist only in freestanding.

Summary

• Loup has six modes. This book covers host.native (.lphc), compiled to a native binary, and host.dual (.loup), which can also run on the interpreter or as WebAssembly.
• Both start at main(), forbid top-level statements, expect static types (Any is W_ANY_IN_AOT_MODE), present ARC semantics, and check the ownership system at compile time.
• host.native adds unique class, asm { } and Volatile[T]; using them in host.dual is an error (E_UNIQUE_CLASS_ARC_BINDING, E_ASM_NOT_COMPILED).
• Choose host.native for binaries that need those features; choose host.dual for code that must run everywhere. Every host.dual file is a valid host.native file.
• Native builds in 1.25.1 refuse async, template fences and for concurrent, keep weak references strong, and let int arithmetic wrap. The relevant chapters mark these ⚠ Planned.
• Chapter 3 starts on the language itself: bindings, numeric types, and what happens on overflow.