cu29/
lib.rs

1//! # Copper Runtime & SDK
2//!
3//! Think of Copper as a robotics game engine: define a task graph, compile once,
4//! and get deterministic execution, unified logging, and sub-microsecond
5//! latency from Linux workstations all the way down to bare-metal MPU builds.
6//!
7//! ## Quick start
8//!
9//! ```bash
10//! cargo install cargo-generate
11//! git clone https://github.com/copper-project/copper-rs
12//! cd copper-rs/templates
13//! cargo cunew /path/to/my_robot   # scaffolds a full Copper project
14//! ```
15//!
16//! It will generate a minimal Copper robot project at `/path/to/my_robot`. `cargo build` should
17//! compile it out of the box.
18//!
19//! ## Feature flags
20//!
21//! - `default` = `["std", "textlogs", "units"]`
22//! - `units`: exposes `cu29::units` (re-export of `cu29-units`)
23//! - `std`: host/runtime support
24//! - `reflect`: reflection support for runtime and units types
25//! - `textlogs`: text logging derive support
26//! - `remote-debug`: remote debug transport support
27//!
28//! ## Concepts behind Copper
29//!
30//! Check out the [Copper Wiki](https://github.com/copper-project/copper-rs/wiki) to understand the
31//! deployments concepts, task lifecycle, available components, etc ...
32//!
33//! ## More examples to get you started
34//!
35//! - `examples/cu_caterpillar`: a minimal running example passing around booleans.
36//! - `examples/cu_rp_balancebot`: a more complete example try Copper without hardware via
37//!   `cargo install cu-rp-balancebot` + `balancebot-sim` (Bevy + Avian3d).
38//!
39//! ## Key traits and structs to check out
40//!
41//! - `cu29_runtime::app::CuApp`: the main trait the copper runtime will expose to run your application. (when run() etc .. is coming from)
42//! - `cu29_runtime::config::CuConfig`: the configuration of your runtime
43//! - `cu29_runtime::cutask::CuTask`: the core trait and helpers to implement your own tasks.
44//! - `cu29_runtime::cubridge::CuBridge`: the trait to implement bridges to hardware or other software.
45//! - `cu29_runtime::curuntime::CuRuntime`: the runtime that manages task execution.
46//! - `cu29_runtime::simulation`: This will explain how to hook up your tasks to a simulation environment.
47//!
48//! Need help or want to show what you're building? Join
49//! [Discord](https://discord.gg/VkCG7Sb9Kw) and hop into the #general channel.
50//!
51
52#![cfg_attr(not(feature = "std"), no_std)]
53#[cfg(not(feature = "std"))]
54extern crate alloc;
55
56pub use cu29_derive::{bundle_resources, resources};
57pub use cu29_runtime::config;
58pub use cu29_runtime::copperlist;
59#[cfg(feature = "std")]
60pub use cu29_runtime::cuasynctask;
61pub use cu29_runtime::cubridge;
62pub use cu29_runtime::curuntime;
63pub use cu29_runtime::cutask;
64#[cfg(feature = "std")]
65pub use cu29_runtime::debug;
66pub use cu29_runtime::input_msg;
67pub use cu29_runtime::monitoring;
68pub use cu29_runtime::output_msg;
69pub use cu29_runtime::payload;
70pub use cu29_runtime::reflect;
71pub use cu29_runtime::reflect as bevy_reflect;
72#[cfg(feature = "remote-debug")]
73pub use cu29_runtime::remote_debug;
74pub use cu29_runtime::resource;
75pub use cu29_runtime::rx_channels;
76#[cfg(feature = "std")]
77pub use cu29_runtime::simulation;
78pub use cu29_runtime::tx_channels;
79
80#[cfg(feature = "rtsan")]
81pub mod rtsan {
82    pub use rtsan_standalone::*;
83}
84
85#[cfg(not(feature = "rtsan"))]
86pub mod rtsan {
87    use core::ffi::CStr;
88
89    #[derive(Default)]
90    pub struct ScopedSanitizeRealtime;
91
92    #[derive(Default)]
93    pub struct ScopedDisabler;
94
95    #[inline]
96    pub fn realtime_enter() {}
97
98    #[inline]
99    pub fn realtime_exit() {}
100
101    #[inline]
102    pub fn disable() {}
103
104    #[inline]
105    pub fn enable() {}
106
107    #[inline]
108    pub fn ensure_initialized() {}
109
110    #[allow(unused_variables)]
111    pub fn notify_blocking_call(_function_name: &'static CStr) {}
112}
113
114pub use bincode;
115pub use cu29_clock as clock;
116#[cfg(feature = "units")]
117pub use cu29_units as units;
118#[cfg(feature = "defmt")]
119pub mod defmt {
120    pub use defmt::{debug, error, info, warn};
121}
122#[cfg(feature = "std")]
123pub use cu29_runtime::config::read_configuration;
124pub use cu29_traits::*;
125
126#[cfg(feature = "std")]
127pub use rayon;
128
129// defmt shims re-exported for proc-macro call sites
130#[cfg(all(feature = "defmt", not(feature = "std")))]
131#[macro_export]
132macro_rules! defmt_debug {
133    ($fmt:literal $(, $arg:expr)* $(,)?) => {
134        $crate::defmt::debug!($fmt $(, $arg)*);
135    }
136}
137#[cfg(not(all(feature = "defmt", not(feature = "std"))))]
138#[macro_export]
139macro_rules! defmt_debug {
140    ($($tt:tt)*) => {{}};
141}
142
143#[cfg(all(feature = "defmt", not(feature = "std")))]
144#[macro_export]
145macro_rules! defmt_info {
146    ($fmt:literal $(, $arg:expr)* $(,)?) => {
147        $crate::defmt::info!($fmt $(, $arg)*);
148    }
149}
150#[cfg(not(all(feature = "defmt", not(feature = "std"))))]
151#[macro_export]
152macro_rules! defmt_info {
153    ($($tt:tt)*) => {{}};
154}
155
156#[cfg(all(feature = "defmt", not(feature = "std")))]
157#[macro_export]
158macro_rules! defmt_warn {
159    ($fmt:literal $(, $arg:expr)* $(,)?) => {
160        $crate::defmt::warn!($fmt $(, $arg)*);
161    }
162}
163#[cfg(not(all(feature = "defmt", not(feature = "std"))))]
164#[macro_export]
165macro_rules! defmt_warn {
166    ($($tt:tt)*) => {{}};
167}
168
169#[cfg(all(feature = "defmt", not(feature = "std")))]
170#[macro_export]
171macro_rules! defmt_error {
172    ($fmt:literal $(, $arg:expr)* $(,)?) => {
173        $crate::defmt::error!($fmt $(, $arg)*);
174    }
175}
176#[cfg(not(all(feature = "defmt", not(feature = "std"))))]
177#[macro_export]
178macro_rules! defmt_error {
179    ($($tt:tt)*) => {{}};
180}
181
182pub mod prelude {
183    pub use crate::bevy_reflect;
184    #[cfg(feature = "units")]
185    pub use crate::units;
186    pub use crate::{defmt_debug, defmt_error, defmt_info, defmt_warn};
187    #[cfg(feature = "std")]
188    pub use ctrlc;
189    pub use cu29_clock::*;
190    pub use cu29_derive::*; // includes resources! proc macro
191    pub use cu29_log::*;
192    pub use cu29_log::{
193        __cu29_defmt_debug, __cu29_defmt_error, __cu29_defmt_info, __cu29_defmt_warn,
194    };
195    pub use cu29_log_derive::*;
196    pub use cu29_log_runtime::*;
197    pub use cu29_runtime::app::*;
198    pub use cu29_runtime::config::*;
199    pub use cu29_runtime::copperlist::*;
200    pub use cu29_runtime::cubridge::*;
201    pub use cu29_runtime::curuntime::*;
202    pub use cu29_runtime::cutask::*;
203    #[cfg(feature = "std")]
204    pub use cu29_runtime::debug::*;
205    pub use cu29_runtime::input_msg;
206    pub use cu29_runtime::monitoring::*;
207    pub use cu29_runtime::output_msg;
208    pub use cu29_runtime::payload::*;
209    #[cfg(feature = "reflect")]
210    pub use cu29_runtime::reflect::serde as reflect_serde;
211    #[cfg(feature = "reflect")]
212    pub use cu29_runtime::reflect::serde::{
213        ReflectSerializer, SerializationData, TypedReflectSerializer,
214    };
215    pub use cu29_runtime::reflect::{
216        GetTypeRegistration, Reflect, ReflectTaskIntrospection, ReflectTypePath, TypeInfo,
217        TypePath, TypeRegistry, dump_type_registry_schema,
218    };
219    #[cfg(feature = "remote-debug")]
220    pub use cu29_runtime::remote_debug::*;
221    pub use cu29_runtime::resource::*;
222    pub use cu29_runtime::rx_channels;
223    #[cfg(feature = "std")]
224    pub use cu29_runtime::simulation::*;
225    pub use cu29_runtime::tx_channels;
226    pub use cu29_runtime::*;
227    pub use cu29_traits::*;
228    pub use cu29_unifiedlog::*;
229    pub use cu29_value::Value;
230    pub use cu29_value::to_value;
231    #[cfg(feature = "std")]
232    pub use pool::*;
233    pub use serde::Serialize;
234}
cu29/lib.rs

cu29/
lib.rs
