library-development

Library Development

Use this skill when the user asks about developing, modifying, or adding system libraries in Nanvix. All libraries live under src/libs/ and are part of the Cargo workspace.

Library Categories

Core Libraries (Guest — #![no_std])

These run inside the Nanvix guest (user-space) and are compiled with cargo:

Utility Libraries (Guest — #![no_std])

Host Libraries (Host — std available)

These run on the host system and are compiled with the host Rust build command (HOST_CARGO_BUILD_CMD, currently cargo):

Build Utilities

Creating a New Library

1. Create the directory under src/libs/<name>/.

2. Add a Cargo.toml with workspace package metadata:

   [package]
   name = "<name>"
   version.workspace = true
   license-file.workspace = true
   authors.workspace = true
   edition.workspace = true
   
   [dependencies]
   # Add dependencies here.
   
   [features]
   default = []
   std = []
   

3. Add the crate to the workspace members list in the root Cargo.toml.

4. Add the crate to the workspace [workspace.dependencies] section.

5. Add the library name to the appropriate list in the Makefile:

   • Guest: ALL_GUEST_RUST_LIBS (and optionally ALL_GUEST_RUST_LIBS_TEST_LIST).
   • Host: ALL_HOST_RUST_LIBS.

6. Add the copyright header to all source files.

7. Create src/lib.rs with proper module organization (see coding standards).

Building Libraries

# Build all guest libraries.
./z build -- all

# Run unit tests for host libraries.
./z build -- run-unit-tests

Guest libraries use GUEST_CARGO_BUILD_CMD (cross-compiled with cargo). Host libraries use HOST_CARGO_BUILD_CMD.

Windows Compilation

On a Windows development host, guest libraries are cross-compiled using a local toolchain, so they work identically to Linux. Host libraries that use std may need conditional compilation (#[cfg(target_os = "...")]) for platform-specific code paths (e.g., KVM, libc).

Note: Windows CI jobs run as part of the main CI pipeline. Platform-independent crates should still be manually verified on a Windows host when making changes that may affect cross-platform compatibility or Windows-specific behavior.

Coding Rules (Library-Specific)

• Guest libraries must support #![no_std] with optional std feature gate.
• Use default-features = false in workspace dependency declarations.
• Use c_size_t, c_ssize_t, c_int, etc. for C interoperability.
• Keep struct fields private; provide getter/setter methods.
• All public items must have doc comments with # Description, # Parameters, # Returns, and # Errors sections as applicable.
• Unit tests go in #[cfg(test)] modules; expect() is preferred over unwrap().