docs: add README documentation

.cargo/config.toml

@@ -1,8 +1,12 @@
-[alias]
-xtask = "run --package xtask --"
+[build]
+# TODO: could we build to x86-64 too via sim?
+target = ["arm-unknown-linux-gnueabi"]
 
 [target.arm-unknown-linux-gnueabi]
 linker = "arm-frc2023-linux-gnueabi-gcc"
 rustflags = [
   "-C", "target-cpu=cortex-a9",
 ]
+
+[alias]
+xtask = "run --package xtask --"

README.md

@@ -29,20 +29,61 @@ fn main() -> Result<()> {
 
 ## Features
 
- * Rust bindings to WPILib: use WPILib's official C++ implementation
- * Type safety at its finest: strong typing ensures that undefined behaviour *cannot* happen
- * An efficient robot: Stay at C++'s speed, but implicitly use memory-safe concepts as much as possible
- * A powerful ecosystem: hook into Rust's ecosystem for logging, mathematical computations, and more
+ * Rust bindings to WPILib: Arfur is a set of bindings, not a reimplementation,
+   meaning you can expect the reliability of the official WPILib C++
+   implementation.
+
+ * Type safety at its finest: The public API is idiomatically Rust, meaning you
+   have type-level gaurantees that undefined behaviour will not and *cannot*
+   occur.
+
+ * An efficient robot: Keep the runtime speed provided by C++. Arfur is low- to
+   zero- overhead.
+
+ * A powerful ecosystem: Hook into Rust's ecosystem for logging, mathematical
+   computations, and more!
+
+## Requirements
+
+What do you need to get started?
+
+<!-- TODO: getting started guide that outlines toolchain installation -->
+
+ * **Rust**
+   * MSRV: `1.72.0`
+   * Toolchain: `stable`
+ * **ARM Compiler Toolchain**: Since you're building to the RoboRIO, which uses
+   a different architecture than most personal computers, you'll need a
+   toolchain that can build to ARM.
+   * Option 1: install a generic ARM toolchain.
+   * Option 2: install the
+     [FRC ARM toolchain](https://github.com/wpilibsuite/opensdk/).
+     * MSRV: `2023-9`
+   * Don't forget to point Arfur to your toolchain executable.
+ * (optional) **Nix**: Use [Nix](https://nixos.org/) to ditch both requirements
+   mentioned above.
+   * Your choice of Rust installation method.
+   * Use the Nix derivation in `./nix` to grab the FRC ARM toolchain.
+
+<!-- TODO: Make Nix drv public -->
 
 ## Getting started
 
-For now, sift through the crate's [examples](https://github.com/arfur-rs/arfur/tree/main/examples) and [documentation](https://docs.rs/arfur). There's much more to come!
+Arfur is still highly in development. Do not consider this project stable by
+any means.
+
+A complete guide is, unfortunately, still in the works. For now, sift through
+the crate's [examples](https://github.com/arfur-rs/arfur/tree/main/examples)
+and [documentation](https://docs.rs/arfur). There's more to come!
 
 ## Development
 
-So, you want to help out with this project? We'd love to chat about the project, just open an issue or make a PR.
+So, you want to help out with this project? We'd love to chat about the
+project, just open an issue or make a PR.
 
-Due to the inherently complex nature of generate bindings for large projects, Arfur uses `xtask` to manage the project. After getting access to the source code (presumably via cloning the git repository), run:
+Due to the inherently complex nature of generate bindings for large projects,
+Arfur uses `xtask` to manage the project. After getting access to the source
+code (presumably via cloning the git repository), run:
 
 ```
 cargo xtask bindgen

arfur-wpilib/src/lib.rs

@@ -45,6 +45,6 @@ mod manualffi {
         type SPI;
 
         type ADXRS450_Gyro;
-        fn new_ADXRS450_Gyro() -> UniquePtr<ADXRS450_Gyro>;
+        pub fn new_ADXRS450_Gyro() -> UniquePtr<ADXRS450_Gyro>;
     }
 }

src/lib.rs

@@ -1,33 +1,4 @@
-//! **Arfur** is a set of bindings and a framework that builds on top of the
-//! [WPILib](https://wpilib.org/) suite, enabling Rust-based robot programs in
-//! [FRC](https://www.firstinspires.org/robotics/frc).
-//!
-//! ```rust
-//! use arfur::prelude::*;
-//!
-//! fn main() -> Result<()> {
-//!     let robot: Robot = RobotBuilder::default().initialize()?;
-//!
-//!     // Having a `Robot` type is proof that the HAL has been initialized. We
-//!     // can use to construct all kinds of handles!
-//!
-//!     Ok(())
-//! }
-//! ```
-//!
-//! ## Features
-//!  * Rust bindings to WPILib: use WPILib's official C++ implementation.
-//!  * Type safety at its finest: strong typing ensures that undefined behaviour
-//!  *cannot* happen.
-//!  * An efficient robot: Stay at C++'s speed, but implicitly use memory-safe
-//!  concepts as much as possible.
-//!  * A powerful ecosystem: hook into Rust's ecosystem for logging,
-//!  mathematical computations, and more.
-//!
-//! ## Getting started
-//! For now, sift through the crate's
-//! [examples](https://github.com/arfur-rs/arfur/tree/main/examples) and
-//! [documentation](https://docs.rs/arfur). There's much more to come!
+#![doc = include_str!("../README.md")]
 
 #[cfg(feature = "arfur-rev")]
 #[doc(inline)]