From b0f2d51ba84720d1470a273afee9ecadca5612f8 Mon Sep 17 00:00:00 2001 From: Jika Date: Thu, 30 Oct 2025 19:10:17 +0100 Subject: [PATCH] Reworked a bit readme --- Cargo.toml | 2 +- README.md | 32 +++++++------------ crates/oc2r-core/Readme.md | 13 ++++++++ crates/oc2r-core/docs/index.md | 11 ++----- crates/oc2r-core/docs/wrappers.md | 4 +-- crates/oc2r-core/src/devices/mod.rs | 4 +-- .../{redstone.rs => redstone_interface.rs} | 4 +-- 7 files changed, 34 insertions(+), 36 deletions(-) create mode 100644 crates/oc2r-core/Readme.md rename crates/oc2r-core/src/devices/{redstone.rs => redstone_interface.rs} (98%) diff --git a/Cargo.toml b/Cargo.toml index a970105..0149ebc 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ resolver = "3" members = ["crates/*"] [workspace.package] -authors = ["Christopher Head "] +authors = ["Jika"] edition = "2024" repository = "https://git.jika.li/jika/oc2r-rust" license = "GPL-3.0-only" diff --git a/README.md b/README.md index e81ffa7..0a23587 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,29 @@ -# OC2R Rust Client +# OC2R Rust -Thin, synchronous access to the OC2R high-level API from Rust. The crate mirrors -the stock Lua helpers (`devices.lua`, `robot.lua`) so you can list devices, invoke methods, +Thin, synchronous access to the [OpenComputers II: Reimagined](https://github.com/North-Western-Development/oc2r) high-level API for Rust. + +This repository is a workspace is divided into multiple crates: + +- `crates/oc2r-core`: mirrors the stock Lua helpers (`devices.lua`, `robot.lua`) so you can list devices, invoke methods, subscribe to events, and work with typed wrappers for common peripherals. -## Documentation - -See [`docs/index.md`](docs/index.md) for the full guide and -[`docs/wrappers.md`](docs/wrappers.md) for device-by-device examples. - ## Development -The crate targets rust nightly for some size optimisations and relies on `miniserde` and `libc`. - To ease developpemnt we use [cross-rs](https://github.com/cross-rs/cross), but you can install all toolchain component or your local computer and replace cross with cargo. By default the option "-Zfmt-debug=none" is set meaning all debug print (:?) are off. If you can disable this option at any time. +There are more size optimisation done you can check the `.cargo/config.toml`, `Cargo.toml`, `Cross.toml` and [min-sized-rust](https://github.com/johnthagen/min-sized-rust) for more info. + # Compilation -Simply `cross clippy --all-targets` to compile all examples +Simply `cross clippy --all-targets` to compile everything ## Examples -Examples of how to use the crate are in the `examples` directory. +Each crates has some examples of how to use it crate are in the `examples` directory. -Build them with: - -```bash -cross build --release --example example-names -``` - -Copy the resulting binaries from -`target//release/examples/` into Minux (an Import/Export card works +Copy the resulting binaries from `target//release/examples/` into Minux (an Import/Export card works well), mark them as executable and then execute them inside the VM. - diff --git a/crates/oc2r-core/Readme.md b/crates/oc2r-core/Readme.md new file mode 100644 index 0000000..1e54015 --- /dev/null +++ b/crates/oc2r-core/Readme.md @@ -0,0 +1,13 @@ +# OC2R-Core + +This crate mirrors the stock Lua helpers (`devices.lua`, `robot.lua`) so you can list devices, invoke methods, +subscribe to events, and work with typed wrappers for common peripherals. + +## Documentation + +See [`docs/index.md`](docs/index.md) for the full guide and +[`docs/wrappers.md`](docs/wrappers.md) for device-by-device examples. + +## Development + +The crate targets rust nightly for some size optimisations and relies on `miniserde` and `libc`. diff --git a/crates/oc2r-core/docs/index.md b/crates/oc2r-core/docs/index.md index 4330bda..1944701 100644 --- a/crates/oc2r-core/docs/index.md +++ b/crates/oc2r-core/docs/index.md @@ -62,7 +62,7 @@ fn main() -> Result<()> { To avoid raw JSON, every base device has a wrapper with strongly typed methods: -- `Redstone` +- `RedstoneInterface` - `EnergyStorage` - `FluidHandler` - `ItemHandler` @@ -71,8 +71,9 @@ To avoid raw JSON, every base device has a wrapper with strongly typed methods: - `BlockOperations` - `InventoryOperations` - `FileImportExport` +- `Robot` -Each wrapper exposes Rust-style methods (e.g. `Redstone::input`, `SoundCard::find`) +Each wrapper exposes Rust-style methods (e.g. `RedstoneInterface::input`, `SoundCard::find`) built on top of the dynamic API. See [`wrappers.md`](wrappers.md) for detailed examples and method-by-method coverage. @@ -81,9 +82,3 @@ examples and method-by-method coverage. - [Device wrapper reference](wrappers.md) - [Redstone event example](../examples/redstone-events.rs) - [Lua-style event loop](../src/event.rs) -- [Performance comparison workflow](performance_testing.md) - -Contributions and further documentation improvements are welcome. Open an issue -with suggestions or gaps you’d like filled. - -- [Redstone wrapper safety](redstone_considerations.md) diff --git a/crates/oc2r-core/docs/wrappers.md b/crates/oc2r-core/docs/wrappers.md index 425b86b..fffff7f 100644 --- a/crates/oc2r-core/docs/wrappers.md +++ b/crates/oc2r-core/docs/wrappers.md @@ -11,7 +11,7 @@ Before using any wrapper, attach it: ```rust let mut bus = DeviceBus::connect(DEFAULT_DEVICE_PATH)?; -let mut redstone = oc2r_rust::Redstone::attach(&mut bus)? +let mut redstone = oc2r_rust::RedstoneInterface::attach(&mut bus)? .expect("no redstone interface attached"); // call unsubscribe() once you are done processing events redstone.subscribe()?; @@ -40,7 +40,7 @@ robot.turn(RobotDirection::Left)?; ## Redstone ```rust -use oc2r_rust::{Redstone, RedstoneSignal, Side}; +use oc2r_rust::{RedstoneInterface, RedstoneSignal, Side}; redstone.set_output_state(Side::East, true)?; let input = redstone.input(Side::East)?; diff --git a/crates/oc2r-core/src/devices/mod.rs b/crates/oc2r-core/src/devices/mod.rs index 6b09434..36dc546 100644 --- a/crates/oc2r-core/src/devices/mod.rs +++ b/crates/oc2r-core/src/devices/mod.rs @@ -51,7 +51,7 @@ pub mod file_import_export; pub mod fluid_handler; pub mod inventory_operations; pub mod item_handler; -pub mod redstone; +pub mod redstone_interface; pub mod robot; pub mod sound; @@ -62,6 +62,6 @@ pub use file_import_export::{FileImportExport, ImportedFileInfo}; pub use fluid_handler::FluidHandler; pub use inventory_operations::InventoryOperations; pub use item_handler::ItemHandler; -pub use redstone::{ParseSideError, Redstone, RedstoneSignal, Side}; +pub use redstone_interface::{ParseSideError, Redstone, RedstoneSignal, Side}; pub use robot::{Robot, RobotDirection}; pub use sound::SoundCard; diff --git a/crates/oc2r-core/src/devices/redstone.rs b/crates/oc2r-core/src/devices/redstone_interface.rs similarity index 98% rename from crates/oc2r-core/src/devices/redstone.rs rename to crates/oc2r-core/src/devices/redstone_interface.rs index 851fd11..864ec6f 100644 --- a/crates/oc2r-core/src/devices/redstone.rs +++ b/crates/oc2r-core/src/devices/redstone_interface.rs @@ -4,12 +4,12 @@ use std::fmt; use std::str::FromStr; crate::devices::define_wrapper!( - Redstone, + RedstoneInterface, "redstone", "Typed wrapper around the HLAPI redstone interface." ); -impl<'bus> Redstone<'bus> { +impl<'bus> RedstoneInterface<'bus> { /// Read the redstone input level for `side`. pub fn input(&mut self, side: Side) -> Result { self.device