wheelos_core
wheelos_core is the WheelOS runtime foundation for message passing and middleware coordination. The repository implements the Cyber RT stack used for publish/subscribe channels, service/client RPC, component lifecycle management, coroutine-style scheduling, topology discovery, shared-memory and RTPS transport, record/playback, native tools, and Python bindings.
The code is organized under cyber/, with the public C++ entry point exposed through cyber/cyber.h. The project is built with Bazel and ships native runtime tools such as cyber_launch, cyber_monitor, and cyber_recorder.
The reusable unified runtime rules assemble source-built modules into one relocatable development, installed, or archived product.
wheelos_core sits in the WheelOS Runtime layer and provides the message-oriented middleware runtime used by higher-level components and applications.
WheelOS
|
+--- Runtime
|
+--- wheelos_core
|
+--- cyber runtime
| +--- Node / Channel / Service APIs
| +--- Scheduler and task execution
| +--- Transport: INTRA / SHM / RTPS
| +--- Topology and service discovery
| +--- Record, tools, and Python integration
|
+--- examples
+--- docs and release tooling
Application / Component
|
v
+-----------------------------------------------+
| Node API (CreateNode / Channel / Service) |
+-----------------------------------------------+
|
+----------------------+------------------+
| |
v v
+-------------------+ +----------------------------+
| Scheduler / Task | | Component loader / lifecycle |
+-------------------+ +----------------------------+
|
v
+-----------------------------------------------+
| Topology manager / service discovery |
+-----------------------------------------------+
|
v
+-----------------------------------------------+
| Transport layer |
| INTRA / SHM / RTPS / QoS / message routing |
+-----------------------------------------------+
|
v
Subscriber / Receiver / Proc() execution
Applications depend on //cyber or the explicit targets in the
public API contract.
//cyber:cyber_core, discovery managers, scheduler policies, and transport
backends are internal implementation targets, not external APIs.
The main ownership boundaries are:
| Directories | Responsibility |
|---|---|
node/, service/, parameter/, gpu/ |
Application APIs and their adapters; RPC uses transport directly rather than Node internals |
component/, mainboard/, class_loader/ |
Component contracts, process assembly, and dynamic loading |
scheduler/, croutine/, task/, timer/ |
Dispatch policies, execution contexts, task submission, and timers |
data/, blocker/ |
Scheduling data buffers/fusion and publish/observe caches; simulation Node adapters live in node/internal/ |
transport/, service_discovery/ |
Data backends and topology control; GPU Node control-plane adapters live in gpu/, not the backend |
record/, tools/, python/ |
Record-file library, runtime commands, and language bindings |
Paths in this table are relative to cyber/. The public SDK distinguishes
supported header roots from the internal support headers needed to compile
C++ templates; it does not export the entire runtime dependency graph.
sudo bash scripts/deploy/build.shThis installs the Bazel build dependencies used by the repository.
Use Bazel 8.8.1, matching Apollo-Lite. Bazelisk reads the version from
.bazelversion; a separately installed bazel binary must match it.
Protobuf 36.2 generates Python code requiring protobuf>=7.36.2,<8.
Abseil and GoogleTest remain at the latest versions compatible with
Protobuf's Abseil compatibility level 1.
bash scripts/build.shThe repository default build entry point is scripts/build.sh, which runs Bazel with the CI configuration and //cyber/... by default. For narrower checks, the repository also documents:
bazel build //cyber
bazel test //cyber/message/...For containerized unit, integration, installed-package E2E and release gates, see the test ownership and release workflow.
Vendor mode is an opt-in Bazel workflow for offline or air-gapped builds. Generate the lockfile and vendor tree while online, then publish a self-contained archive:
bazel mod deps --config=ci --lockfile_mode=update
bash scripts/release/build_vendor_bundle.sh --outdir artifacts/vendorThe script refreshes the Bazel 8.8.1-compatible MODULE.bazel.lock, runs
bazel vendor --lockfile_mode=update, validates //:wheelos_core, and writes
an archive such as
artifacts/vendor/wheelos_core_vendor_<timestamp>.tar.gz. The archive
contains the source snapshot, vendor/bazel repositories and registry files,
and the lockfile. It does not contain bazel-external, which Bazel recreates
at runtime.
To compile from the archive, extract it into a writable directory. Keep the lockfile and vendor tree together, use a fresh output root and empty repository cache, and disable downloads:
mkdir -p /work/wheelos-vendor
tar -xzf artifacts/vendor/wheelos_core_vendor_<timestamp>.tar.gz \
-C /work/wheelos-vendor
cd /work/wheelos-vendor/repo
mkdir -p /tmp/empty-repository-cache
bazel \
--output_user_root=/tmp/wheelos-vendor-output \
build \
--config=ci \
--lockfile_mode=error \
--vendor_dir=vendor/bazel \
--repository_cache=/tmp/empty-repository-cache \
--repository_disable_download \
//:wheelos_coreFor strict validation, run the extracted tree in an Ubuntu 22.04 container
with Docker --network none. Do not mount vendor/bazel read-only: Bazel
must create the runtime bazel-external symlink. Do not delete the lockfile
or use --lockfile_mode=off, because Bazel then falls back to remote
registries.
bazel build //:wheelos_core
sudo apt install ./bazel-bin/wheelos_core_1.0.0_all.deb
source /opt/wheelos_core/setup.bash
cyber_launch --helpThe Debian package is the supported native runtime bundle. It installs commands such as mainboard, cyber_launch, cyber_monitor, and cyber_recorder under /opt/wheelos_core.
The repository contains minimal example components under examples/. The clearest end-to-end example is examples/common_component_example.
cd /path/to/core
bazel build //examples/common_component_example/...Start the component in one terminal:
cyber_launch start examples/common_component_example/common.launchOr start it directly from the DAG file:
mainboard -d examples/common_component_example/common.dagThen start the two writer nodes in separate terminals:
bazel run //examples/common_component_example:channel_test_writer
bazel run //examples/common_component_example:channel_prediction_writerThis example demonstrates loading a component from a shared library and feeding it messages from multiple writer processes.
There are additional related examples under examples/timer_component_example, but the common component example is the smallest repository-provided example with explicit build and run commands.
Start with the documentation index for the complete, categorized guide list.
- Getting started: Installation · Quick start · Deployment options
- Runtime and applications: Pub/Sub · Service and Client · GPU zero-copy · Record and Replay · Scheduler optimization
- Development and operations: Component development · Secondary development and integration · Performance testing · Release validation · Common issues
- Reference: Generated API · Doxygen/Sphinx index · C++ API · Python API · Terms
- Examples: Common component · Timer component
The guides are the recommended entry point for installation and runtime usage; generated API documentation remains the code-level reference.