Module init 

Phase 212.L.5 — top-level init API; phase-427 W9 — on every target.

Re-exported flat at the crate root: nros::Context (alloc), nros::ContextSource, nros::InitError, nros::InitOptions (every target); nros::init(), nros::init_with_args(args) (env). The env feature gates only the process-environment reader and the argv entry; freestanding, Context::default_from_env() is the bake (Context::baked()). Phase 212.L.5 — top-level init API; phase-427 W9 — on every target.

Context is WHERE this image is connected — locator, domain, RMW, session mode, and the source those came from (RFC-0089 “Context and init, settled”). One per process or image; a resolved value, not an entity on the graph. A Node is a named participant with its own entities, and one image holds several of those on one Context (RFC-0047).

Where the values come from

• Hosted (feature env): the process environment (ROS_DOMAIN_ID, NROS_LOCATOR, NROS_SESSION_MODE, NROS_RMW / RMW_IMPLEMENTATION) through the one hosted resolver, crate::env::try_resolve_hosted. A launcher projects per-node values into that environment before exec.
• Freestanding (no env): there is no process and no environment; the same values are BAKED at compile time — option_env!("NROS_LOCATOR") and option_env!("NROS_DOMAIN_ID"), exported into this crate’s build by nros_zephyr_build::bake_nros_config() from Kconfig (build.rs), or present in the process environment of the build for the other RTOS lanes (the board crates read the same two names the same way). The semantics survive with the source moved from run time to build time: “the environment this image was built for or launched in”.

The env feature gates ONLY the process-environment reader and the argv/launch entry points; Context, ContextSource, InitError, InitOptions and Context::config compile on every target. The floor for Context itself is alloc: locator and rmw are owned Strings so the value outlives whatever transient produced it (an env cache, a parsed launch file, a harness-supplied override).

The rclrs family

Context::default_from_env, Context::from_env and (hosted only) Context::new are the rclrs::Context constructors under the same names; InitOptions is rclrs’s, with the one option it has. init() is the C++-symmetric anchor (rclcpp::init) and equals default_from_env().

Two patterns are supported:

1. Node pkg — register via the nros::node! macro (Phase 172 W.3); the generated runtime owns the spin loop and builds its Context through Context::default_from_env.
2. Application pkg — call init() / Context::default_from_env (or init_with_args / Context::new for argv-style entry) and drive your own spin. The returned Context carries the domain id, locator and RMW choice from the environment — see “Where launch content comes from” below.

To actually open a session, call Context::create_executor (alloc) or Context::create_executor_in (caller-supplied backing, nothing leaked), then name each node with Executor::create_node. The older spelling — materialise an crate::ExecutorConfig via Context::config and pass it to Executor::open — still works and is what a single-node entry wants; phase-427 W10 added the pair because it cannot express the second node.

Where launch content comes from

Nothing here reads a launch file at run time. A launch tree reaches an image at BUILD time: nros sync resolves it into the image’s SystemModel, and the generated entry (nros::main!(launch = …), nano_ros_entry(… LAUNCH …)) installs its node identities, remaps and parameters. What is left for init to read is the environment (ROS_DOMAIN_ID, NROS_LOCATOR, NROS_SESSION_MODE, RMW_IMPLEMENTATION) and, through init_with_args / Context::new, per-process --ros-args. (Issue 1917 retired the runtime-overlay placeholder and, with issue 1931, the init_with_launch* entry points named after it.)

Structs

Context

Phase 212.L.5 — resolved init context.

InitOptions

phase-427 W9 — rclrs::InitOptions, with the one option it has.

Enums

ContextSource

Where the Context came from. Diagnostics only.

InitError

Errors returned by the init API.

Constants

REFUSE_INIT_ARGS

The refusal init_with_args and Context::new emit for a ROS argument nano-ros does not honour. Panics carry this text followed by the refused argument. NROS_RCLCPP_REFUSE_INIT_ARGV is the C++ twin (packages/api/nros-cpp/include/rclcpp/logging.hpp), and since phase-467 Row 11’s C++ half it states the same honoured and refused sets, from the same parser.

Functions

args_have_ros_args

Does args open a --ros-args scope at all?

init

Pattern 3 — raw init, launch file ignored. The C++-symmetric anchor: rclcpp::init() in the Rust spelling, and EQUAL to Context::default_from_env on a hosted build (RFC-0089 “Context and init, settled” — each language follows its own upstream; rclrs spells this one on the type, rclcpp as a free function, and both are here).

init_with_args

Pattern 3 — like init() but takes the process arguments, the way rclcpp::init(argc, argv) / rclrs’s Context::new(args, ..) do. The free-function twin of Context::new with default options.