User App Development

User Application Development

Use this skill when the user asks about developing, building, or running user-space applications on Nanvix. User applications are programs that run inside the Nanvix guest environment.

Supported Languages and Examples

Running Applications

Interactive Mode (recommended for development)

# Run a native application with console output.
./bin/nanvixd.elf \
    -console-file /dev/stdout \
    -- ./bin/hello-rust-nostd.elf

# Pass arguments to the application.
./bin/nanvixd.elf \
    -console-file /dev/stdout \
    -- ./bin/echo-rust-nostd.elf arg1 arg2

# Pass arguments and environment variables.
./bin/nanvixd.elf \
    -console-file /dev/stdout \
    -- ./bin/echo-rust-nostd.elf \
    "arg1 arg2;VAR1=foo VAR2=bar"

# Pass arguments, environment variables, and kernel arguments.
# Format: "<app args>;<env vars>;<kernel args>"
./bin/nanvixd.elf \
    -console-file /dev/stdout \
    -- ./bin/echo-rust-nostd.elf \
    "arg1 arg2;VAR1=foo;feature1 feature2"

HTTP Mode (for multi-application scenarios)

# Start nanvixd in HTTP mode.
NANVIX_HTTP_ADDR=127.0.0.1:8080
./bin/nanvixd.elf -http-addr $NANVIX_HTTP_ADDR

# Spawn an application via HTTP (in another terminal).
curl --silent \
    --header "Content-Type: application/json" \
    --header "X-NVX-Message-Type: NEW" \
    --request POST \
    --data '{"tenant_id":"foo",
             "app_name":"bar",
             "program":"./bin/hello-rust-nostd.elf",
             "program_args":""}' \
    http://${NANVIX_HTTP_ADDR}

Standalone UserVM Mode (expert/debugging)

./bin/uservm.elf \
    -kernel ./bin/kernel.elf \
    -initrd ./bin/hello-rust-nostd.elf \
    -standalone

Running on Windows

On Windows, nanvixd supports standalone interactive mode (no HTTP mode). Both nanvixd and the UserVM are built natively with the WHP backend:

# Run via nanvixd (recommended).
.\bin\nanvixd.exe -- .\bin\hello-rust-nostd.elf

You can also launch a run via z.ps1:

# Run with default options.
.\z.ps1 run

# Run with a custom guest binary.
.\z.ps1 run -- -program bin\hello-rust-nostd.elf

For low-level debugging, the standalone UserVM is still available:

.\bin\uservm.exe -kernel .\bin\kernel.elf -initrd .\bin\hello-rust-nostd.elf -standalone

Note: HTTP mode is Linux-only. On Windows, only standalone interactive mode via nanvixd is supported.

Creating a New Rust Application (no_std)

1. Create directory at src/user/<name>/.

2. Add Cargo.toml:

   [package]
   name = "<name>"
   version.workspace = true
   license-file.workspace = true
   authors.workspace = true
   edition.workspace = true
   
   [[bin]]
   name = "<name>"
   path = "src/main.rs"
   
   [dependencies]
   nvx = { workspace = true }
   sys = { workspace = true }
   syslog = { workspace = true }
   

3. Create src/main.rs:

   // Copyright(c) The Maintainers of Nanvix.
   // Licensed under the MIT License.
   
   #![no_std]
   #![no_main]
   
   extern crate alloc;
   
   // Application entry point.
   

4. Add to workspace members in root Cargo.toml.

5. Add to ALL_GUEST_APPLICATIONS in the Makefile.

Creating a New C Application

1. Create directory at src/user/<name>/.
2. Create a Makefile following the pattern in existing C applications.
3. Write source files using the Nanvix POSIX layer (#include <nanvix/...>).
4. The application links against libposix.a, libc.a, and the custom linker script at build/user/linker/x86/user.ld.

Logging

• Use RUST_LOG environment variable for nanvixd daemon-level logging.
• Guest-side logging uses the syslog crate (error!, warn!, info!, debug!, trace!).
• Console output defaults to logs/ directory; use -console-file /dev/stdout to redirect to terminal.

Source: nanvix/nanvix — distributed by TomeVault.