Merge pull request #25 from copper-project/gbin/doc-app-builder-docs

Refresh docs for generated app builder setup

Author: gbin

book/src/ch10-main-rs.md

@@ -10,8 +10,7 @@ are mostly boilerplate that you write once and rarely touch.
 pub mod tasks;
 
 use cu29::prelude::*;
-use cu29_helpers::basic_copper_setup;
-use std::path::{Path, PathBuf};
+use std::path::Path;
 use std::thread::sleep;
 use std::time::Duration;
 
@@ -27,24 +26,17 @@ fn main() {
             std::fs::create_dir_all(parent).expect("Failed to create logs directory");
         }
     }
-    let copper_ctx = basic_copper_setup(
-        &PathBuf::from(&logger_path),
-        PREALLOCATED_STORAGE_SIZE,
-        true,
-        None,
-    )
-    .expect("Failed to setup logger.");
     debug!("Logger created at {}.", logger_path);
     debug!("Creating application... ");
-    let mut application = MyProjectApplicationBuilder::new()
-        .with_context(&copper_ctx)
+    let mut application = MyProjectApplication::builder()
+        .with_log_path(logger_path, PREALLOCATED_STORAGE_SIZE)
+        .expect("Failed to setup logger.")
         .build()
         .expect("Failed to create application.");
-    let clock = copper_ctx.clock.clone();
-    debug!("Running... starting clock: {}.", clock.now());
+    debug!("Running... starting clock: {}.", application.clock().now());
 
     application.run().expect("Failed to run application.");
-    debug!("End of program: {}.", clock.now());
+    debug!("End of program: {}.", application.clock().now());
     sleep(Duration::from_secs(1));
 }
 ```
@@ -63,20 +55,21 @@ generated code is injected by the macro.
 **`PREALLOCATED_STORAGE_SIZE`** -- How much memory (in bytes) to pre-allocate for the
 structured log. 100 MB is a reasonable default.
 
-**`basic_copper_setup()`** -- Initializes the unified logger, the robot clock, and returns
-a `copper_ctx` that holds references to both. The parameters are: log file path,
-pre-allocated size, whether to also print to console, and an optional custom monitor.
+**`MyProjectApplication::builder()`** -- Creates the generated application builder.
+You provide the pieces you want to override, such as the clock, config override, or
+resource factory.
 
-**`MyProjectApplicationBuilder::new().with_context(&copper_ctx).build()`** -- Wires
+**`.with_log_path(...).build()`** -- Wires
 everything together: creates each task by calling their `new()` constructors,
 pre-allocates all message buffers, and sets up the scheduler.
 
 **`application.run()`** -- Starts the deterministic execution loop. Calls `start()` on
 all tasks, then enters the cycle loop (`preprocess` -> `process` -> `postprocess` for
 each task, in topological order), and continues until you stop the application (Ctrl+C).
 
-**`copper_ctx.clock.clone()`** -- Note that we clone the clock **after** passing
-`copper_ctx` to the builder, to avoid a partial-move error.
+**`application.clock()`** -- Returns the runtime clock handle. The builder creates a
+default clock unless you override it with `.with_clock(...)`, which is mainly useful in
+tests or simulation.
 
 ## build.rs -- log index setup
 

book/src/ch12-monitoring.md

@@ -14,7 +14,6 @@ Add `cu-consolemon` to your `Cargo.toml`:
 ```toml
 [dependencies]
 cu29 = { git = "https://github.com/copper-project/copper-rs" }
-cu29-helpers = { git = "https://github.com/copper-project/copper-rs" }
 cu-consolemon = { git = "https://github.com/copper-project/copper-rs" }
 bincode = { package = "cu-bincode", version = "2.0", default-features = false,
             features = ["derive", "alloc"] }
@@ -157,4 +156,3 @@ see without the monitor, but captured inside the TUI. You can scroll through the
 with `hjkl` or arrow keys. The bottom bar also shows keyboard shortcuts: `r` to reset
 latency statistics, `q` to quit.
 
-

book/src/ch13-logging-replay.md

@@ -1,7 +1,7 @@
 # Logging and Replaying Data
 
 Every time you've run our project so far, Copper has been quietly recording everything.
-Look at `main.rs` -- the call to `basic_copper_setup()` initializes a **unified logger**
+Look at `main.rs` -- the generated app builder's `.with_log_path(...)` call initializes a **unified logger**
 that writes to `logs/my-project.copper`. Every cycle, the runtime serializes every message
 exchanged between tasks (the **CopperList**) and writes it to that file.
 
@@ -259,7 +259,7 @@ hardware or a log file.
 
 Copper's logger is designed for **zero-impact logging** on the critical path. Here's how:
 
-1. **Pre-allocated memory slabs** -- At startup, `basic_copper_setup()` allocates a large
+1. **Pre-allocated memory slabs** -- At startup, `.with_log_path(...)` allocates a large
    contiguous block of memory (controlled by `PREALLOCATED_STORAGE_SIZE` -- 100 MB in our
    project). CopperLists are written into this pre-allocated buffer without any dynamic
    allocation.
@@ -350,4 +350,3 @@ to decide what to *exclude* (via `logging: (enabled: false)`) if storage is a co
 This "record everything by default" approach is what makes Copper's deterministic replay
 possible. Since every message and every timestamp is captured automatically, you can always
 go back and reproduce any moment of your robot's execution.
-

book/src/ch14-missions.md

@@ -145,8 +145,7 @@ Update `main.rs` to select a mission:
 pub mod tasks;
 
 use cu29::prelude::*;
-use cu29_helpers::basic_copper_setup;
-use std::path::{Path, PathBuf};
+use std::path::Path;
 use std::thread::sleep;
 use std::time::Duration;
 
@@ -155,9 +154,9 @@ const PREALLOCATED_STORAGE_SIZE: Option<usize> = Some(1024 * 1024 * 100);
 #[copper_runtime(config = "copperconfig.ron")]
 struct MyProjectApplication {}
 
-// Import the per-mission builders
-use normal::MyProjectApplicationBuilder as NormalBuilder;
-use direct::MyProjectApplicationBuilder as DirectBuilder;
+// Import the per-mission application types
+use normal::MyProjectApplication as NormalApp;
+use direct::MyProjectApplication as DirectApp;
 
 fn main() {
     // Pick the mission from the first command-line argument (default: "normal")
@@ -171,28 +170,26 @@ fn main() {
             std::fs::create_dir_all(parent).expect("Failed to create logs directory");
         }
     }
-    let copper_ctx = basic_copper_setup(
-        &PathBuf::from(&logger_path),
-        PREALLOCATED_STORAGE_SIZE,
-        true,
-        None,
-    )
-    .expect("Failed to setup logger.");
+    let clock = RobotClock::default();
     debug!("Logger created at {}.", logger_path);
 
     match mission.as_str() {
         "normal" => {
             debug!("Starting mission: normal");
-            let mut app = NormalBuilder::new()
-                .with_context(&copper_ctx)
+            let mut app = NormalApp::builder()
+                .with_clock(clock.clone())
+                .with_log_path(logger_path, PREALLOCATED_STORAGE_SIZE)
+                .expect("Failed to setup logger.")
                 .build()
                 .expect("Failed to create application.");
             app.run().expect("Failed to run application.");
         }
         "direct" => {
             debug!("Starting mission: direct");
-            let mut app = DirectBuilder::new()
-                .with_context(&copper_ctx)
+            let mut app = DirectApp::builder()
+                .with_clock(clock.clone())
+                .with_log_path(logger_path, PREALLOCATED_STORAGE_SIZE)
+                .expect("Failed to setup logger.")
                 .build()
                 .expect("Failed to create application.");
             app.run().expect("Failed to run application.");

book/src/ch15-workspace.md

@@ -70,7 +70,6 @@ resolver = "2"
 
 [workspace.dependencies]
 cu29 = { path = "../../core/cu29" }
-cu29-helpers = { path = "../../core/cu29_helpers" }
 cu29-export = { path = "../../core/cu29_export" }
 bincode = { package = "cu-bincode", version = "2.0", default-features = false, features = ["derive", "alloc"] }
 serde = { version = "*", features = ["derive"] }