library-development

name: library-development description: Guide for creating and modifying Nanvix libraries under src/libs, including guest no_std and host std crates. Use this when asked about library architecture or crate changes.

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().