pre-release

.github/workflows/tests.yml

@@ -53,29 +53,28 @@ jobs:
       - name: Test Crates
         run: |
           FEATURES_1=bindgen-runtime
-          FEATURES_2=bindgen-runtime,bindings-derive-debug,error-ctx
-          FEATURES_3=bindgen-runtime,bindings-derive-debug,bindings-documentation
+          FEATURES_2=bindgen-runtime,bindings-derive-debug,bindings-documentation,error-ctx
 
-          cargo test -p=playdate-sys -- --nocapture
           cargo test -p=playdate-sys --features=$FEATURES_1 -- --nocapture
           cargo test -p=playdate-sys --features=$FEATURES_2 -- --nocapture
-          cargo test -p=playdate-sys --features=$FEATURES_3 -- --nocapture
 
           cargo test -p=playdate-fs --lib --no-default-features --features=$FEATURES_1 -- --nocapture
           cargo test -p=playdate-fs --lib --no-default-features --features=$FEATURES_2 -- --nocapture
-          cargo test -p=playdate-fs --lib --no-default-features --features=$FEATURES_3 -- --nocapture
 
           cargo test -p=playdate-sound --lib --no-default-features --features=$FEATURES_1 -- --nocapture
           cargo test -p=playdate-sound --lib --no-default-features --features=$FEATURES_2 -- --nocapture
-          cargo test -p=playdate-sound --lib --no-default-features --features=$FEATURES_3 -- --nocapture
 
           cargo test -p=playdate-color --lib --no-default-features --features=$FEATURES_1 -- --nocapture
           cargo test -p=playdate-color --lib --no-default-features --features=$FEATURES_2 -- --nocapture
-          cargo test -p=playdate-color --lib --no-default-features --features=$FEATURES_3 -- --nocapture
 
           cargo test -p=playdate-controls --lib --no-default-features --features=$FEATURES_1 -- --nocapture
           cargo test -p=playdate-controls --lib --no-default-features --features=$FEATURES_2 -- --nocapture
-          cargo test -p=playdate-controls --lib --no-default-features --features=$FEATURES_3 -- --nocapture
+
+          cargo test -p=playdate-menu --lib --no-default-features --features=$FEATURES_1 -- --nocapture
+          cargo test -p=playdate-menu --lib --no-default-features --features=$FEATURES_2 -- --nocapture
+
+          cargo test -p=playdate-graphics --lib --no-default-features --features=$FEATURES_1 -- --nocapture
+          cargo test -p=playdate-graphics --lib --no-default-features --features=$FEATURES_2 -- --nocapture
 
       - name: Examples
         run: |
@@ -85,6 +84,8 @@ jobs:
           cargo build --target=thumbv7em-none-eabihf -p=playdate-controls --examples --features=$FEATURES -Zbuild-std
           cargo build --target=thumbv7em-none-eabihf -p=playdate-color --examples --features=$FEATURES -Zbuild-std
           cargo build --target=thumbv7em-none-eabihf -p=playdate-sound --examples --features=$FEATURES -Zbuild-std
+          cargo build --target=thumbv7em-none-eabihf -p=playdate-menu --examples --features=$FEATURES -Zbuild-std
+          cargo build --target=thumbv7em-none-eabihf -p=playdate-graphics --examples --features=$FEATURES -Zbuild-std
 
       # Imitate docs.rs environment
       - name: Test in no-sdk environment
@@ -158,6 +159,8 @@ jobs:
           cargo playdate package --simulator --device -p=playdate-controls --examples
           cargo playdate package --simulator --device -p=playdate-color --examples
           cargo playdate package --simulator --device -p=playdate-sound --examples
+          cargo playdate package --simulator --device -p=playdate-menu --examples
+          cargo playdate package --simulator --device -p=playdate-graphics --examples
 
       # TODO: build crankstart with examples for compatibility test
 

README.md

@@ -1,7 +1,22 @@
 # 🦀 Playdate API and build tools in Rust
 
+* [Modular build system][support-dir]
+  - build-support libraries
+  - pre-configured bindgen with extra codegen
+  - [cargo-playdate][cargo-dir] - one-button solution to build, package and run programs
+* [Modular low- & high- level API][api-dir]
+  - with [examples][ctrl-examples-dir]
+
+Welcome to [discussions][] and [issues][] for any questions and suggestions.
+
+
+## Prerequisites
+
+Follow the instructions for:
+1. [SDK](https://sdk.play.date/Inside%20Playdate%20with%20C.html#_prerequisites)
+1. [cargo-playdate](https://github.com/boozook/playdate/blob/main/cargo/README.md#prerequisites)
+1. [playdate-sys](https://github.com/boozook/playdate/tree/main/api/sys#prerequisites)
 
-TODO: 🚨 proper documentation - short description for all crates with links.
 
 
 ## Usage
@@ -19,6 +34,52 @@ cargo playdate run -p=playdate-sound --example=sp-simple --device
 ```
 
 
+## Modularity
+
+Thanks to the modular structure of the system, you can use all or only the parts of the system you need.
+
+### Create a Game
+
+1. Add [API-components][api-dir] as dependencies to your project
+1. Install [cargo-playdate][] to build your project
+
+### Create an API-extension
+
+1. Add [playdate-sys][] to dependencies
+1. Write neat code
+1. Build & test using cargo, [cargo-playdate][] or anything else.
+
+Here is [example][color-dir] of simple API-extension.
+
+Please follow [the instructions of playdate-sys](https://github.com/boozook/playdate/tree/main/api/sys#extension-development).
+
+### Create your bindings
+
+1. Use [playdate-bindgen][] in your build-script
+
+### Create your build-system
+
+1. Use [build-support crates][support-dir]
+
+There is all needed to find SDK and arm-gnu toolchain on user's system, build flags, configurations, formats including pdxinfo, etc.
+
+
+
+[playdate-sys]: https://crates.io/crates/playdate-sys
+[cargo-playdate]: https://crates.io/crates/cargo-playdate
+[playdate-bindgen]: https://crates.io/crates/playdate-bindgen
+
+[support-dir]: https://github.com/boozook/playdate/tree/main/support
+[cargo-dir]: https://github.com/boozook/playdate/tree/main/cargo
+[api-dir]: https://github.com/boozook/playdate/tree/main/api
+[ctrl-examples-dir]: https://github.com/boozook/playdate/tree/main/api/ctrl/examples
+[color-dir]: https://github.com/boozook/playdate/tree/main/api/color
+
+[issues]: https://github.com/boozook/playdate/issues
+[discussions]: https://github.com/boozook/playdate/discussions
+
+
+
 
 - - -
 

api/color/Cargo.toml

@@ -11,27 +11,28 @@ repository = "https://github.com/boozook/playdate.git"
 
 
 [features]
-default = ["pd/default"]
-lang-items = ["pd/lang-items"]
-allocator = ["pd/allocator"]
-panic-handler = ["pd/panic-handler"]
-eh-personality = ["pd/eh-personality"]
-error-ctx = ["pd/error-ctx"]
-bindgen-runtime = ["pd/bindgen-runtime"]
-bindgen-static = ["pd/bindgen-static"]
-bindings-derive-default = ["pd/bindings-derive-default"]
-bindings-derive-eq = ["pd/bindings-derive-eq"]
-bindings-derive-copy = ["pd/bindings-derive-copy"]
-bindings-derive-debug = ["pd/bindings-derive-debug"]
-bindings-derive-hash = ["pd/bindings-derive-hash"]
-bindings-derive-ord = ["pd/bindings-derive-ord"]
-bindings-derive-partialeq = ["pd/bindings-derive-partialeq"]
-bindings-derive-partialord = ["pd/bindings-derive-partialord"]
-bindings-derive-constparamty = ["pd/bindings-derive-constparamty"]
-bindings-documentation = ["pd/bindings-documentation"]
+default = ["sys/default"]
+lang-items = ["sys/lang-items"]
+allocator = ["sys/allocator"]
+panic-handler = ["sys/panic-handler"]
+eh-personality = ["sys/eh-personality"]
+error-ctx = ["sys/error-ctx"]
+bindgen-runtime = ["sys/bindgen-runtime"]
+bindgen-static = ["sys/bindgen-static"]
+bindings-derive-default = ["sys/bindings-derive-default"]
+bindings-derive-eq = ["sys/bindings-derive-eq"]
+bindings-derive-copy = ["sys/bindings-derive-copy"]
+bindings-derive-debug = ["sys/bindings-derive-debug"]
+bindings-derive-hash = ["sys/bindings-derive-hash"]
+bindings-derive-ord = ["sys/bindings-derive-ord"]
+bindings-derive-partialeq = ["sys/bindings-derive-partialeq"]
+bindings-derive-partialord = ["sys/bindings-derive-partialord"]
+bindings-derive-constparamty = ["sys/bindings-derive-constparamty"]
+bindings-documentation = ["sys/bindings-documentation"]
 
 
-[dependencies.pd]
+[dependencies.sys]
 path = "../sys"
+version = "0.1"
 package = "playdate-sys"
 default-features = false

api/color/src/lib.rs

@@ -2,17 +2,18 @@
 #![feature(const_trait_impl)]
 #![feature(impl_trait_in_assoc_type)]
 
-pub extern crate pd as sys;
-use pd::ffi::LCDColor;
-use pd::ffi::LCDPattern;
-use pd::ffi::LCDSolidColor;
+pub extern crate sys;
+use sys::ffi::LCDColor;
+use sys::ffi::LCDPattern;
+use sys::ffi::LCDSolidColor;
 
 
 #[derive(PartialEq, Clone)]
 #[cfg_attr(feature = "bindings-derive-debug", derive(Debug))]
 pub enum Color<'t> {
 	Solid(LCDSolidColor),
-	Pattern(&'t LCDPattern),
+	PatternRef(&'t LCDPattern),
+	Pattern(LCDPattern),
 }
 
 impl Color<'static> {
@@ -26,7 +27,8 @@ impl From<Color<'_>> for LCDColor {
 	fn from(color: Color) -> Self {
 		match color {
 			Color::Solid(color) => color as LCDColor,
-			Color::Pattern(pattern) => (pattern as *const u8) as LCDColor,
+			Color::Pattern(ref pattern) => (pattern as *const u8) as LCDColor,
+			Color::PatternRef(pattern) => (pattern as *const u8) as LCDColor,
 		}
 	}
 }

api/ctrl/Cargo.toml

@@ -13,29 +13,30 @@ repository = "https://github.com/boozook/playdate.git"
 
 
 [features]
-default = ["pd/default"]
-lang-items = ["pd/lang-items"]
-allocator = ["pd/allocator"]
-panic-handler = ["pd/panic-handler"]
-eh-personality = ["pd/eh-personality"]
-entry-point = ["pd/entry-point"]
-error-ctx = ["pd/error-ctx"]
-bindgen-runtime = ["pd/bindgen-runtime"]
-bindgen-static = ["pd/bindgen-static"]
-bindings-derive-default = ["pd/bindings-derive-default"]
-bindings-derive-eq = ["pd/bindings-derive-eq"]
-bindings-derive-copy = ["pd/bindings-derive-copy"]
-bindings-derive-debug = ["pd/bindings-derive-debug"]
-bindings-derive-hash = ["pd/bindings-derive-hash"]
-bindings-derive-ord = ["pd/bindings-derive-ord"]
-bindings-derive-partialeq = ["pd/bindings-derive-partialeq"]
-bindings-derive-partialord = ["pd/bindings-derive-partialord"]
-bindings-derive-constparamty = ["pd/bindings-derive-constparamty"]
-bindings-documentation = ["pd/bindings-documentation"]
-
-
-[dependencies.pd]
+default = ["sys/default"]
+lang-items = ["sys/lang-items"]
+allocator = ["sys/allocator"]
+panic-handler = ["sys/panic-handler"]
+eh-personality = ["sys/eh-personality"]
+entry-point = ["sys/entry-point"]
+error-ctx = ["sys/error-ctx"]
+bindgen-runtime = ["sys/bindgen-runtime"]
+bindgen-static = ["sys/bindgen-static"]
+bindings-derive-default = ["sys/bindings-derive-default"]
+bindings-derive-eq = ["sys/bindings-derive-eq"]
+bindings-derive-copy = ["sys/bindings-derive-copy"]
+bindings-derive-debug = ["sys/bindings-derive-debug"]
+bindings-derive-hash = ["sys/bindings-derive-hash"]
+bindings-derive-ord = ["sys/bindings-derive-ord"]
+bindings-derive-partialeq = ["sys/bindings-derive-partialeq"]
+bindings-derive-partialord = ["sys/bindings-derive-partialord"]
+bindings-derive-constparamty = ["sys/bindings-derive-constparamty"]
+bindings-documentation = ["sys/bindings-documentation"]
+
+
+[dependencies.sys]
 path = "../sys"
+version = "0.1"
 package = "playdate-sys"
 default-features = false
 

api/ctrl/examples/README.md

@@ -0,0 +1,19 @@
+# Examples
+
+⚠️ All of the examples here are very low-level, except for the parts that directly demonstrate the functionality of this package.
+
+
+# How to run
+
+```bash
+# Simulator:
+cargo playdate run -p=playdate-controls --example=buttons --features=bindgen-runtime,bindings-derive-debug
+# Device:
+cargo playdate run -p=playdate-controls --example=accelerometer --features=bindgen-runtime,bindings-derive-debug --device
+```
+
+More information how to use [cargo-playdate][] in help: `cargo playdate --help`.
+
+
+
+[cargo-playdate]: https://crates.io/crates/cargo-playdate

api/ctrl/examples/accelerometer.rs

@@ -5,13 +5,13 @@ use alloc::boxed::Box;
 use core::ffi::*;
 
 #[macro_use]
-extern crate pd;
+extern crate sys;
 extern crate playdate_controls as controls;
-use pd::ffi::*;
+use sys::ffi::*;
 
 
 const INITIAL_X: u32 = LCD_COLUMNS / 2;
-const INITIAL_Y: u32 = (pd::ffi::LCD_ROWS - TEXT_HEIGHT) / 2;
+const INITIAL_Y: u32 = (sys::ffi::LCD_ROWS - TEXT_HEIGHT) / 2;
 const TEXT_HEIGHT: u32 = 16;
 
 
@@ -41,7 +41,7 @@ impl State {
 		let (x, y, z) = controls::peripherals::Accelerometer::get()?;
 
 		unsafe {
-			let graphics = (*pd::API).graphics;
+			let graphics = (*sys::API).graphics;
 			(*graphics).clear?(LCDSolidColor::kColorWhite as LCDColor);
 
 			// render state to string
@@ -80,7 +80,7 @@ impl State {
 				self.pos.y = LCD_ROWS as i32 - TEXT_HEIGHT as i32
 			}
 
-			(*(*pd::API).system).drawFPS?(0, 0);
+			(*(*sys::API).system).drawFPS?(0, 0);
 			Some(())
 		}
 	}
@@ -91,7 +91,7 @@ impl State {
 		match event {
 			// initial setup
 			PDSystemEvent::kEventInit => {
-				unsafe { (*(*pd::API).display).setRefreshRate?(20.0) }
+				unsafe { (*(*sys::API).display).setRefreshRate?(20.0) }
 				// turn on the accelerometer
 				controls::peripherals::Accelerometer::enable()?;
 			},
@@ -114,7 +114,7 @@ pub extern "C" fn eventHandlerShim(api: *const PlaydateAPI, event: PDSystemEvent
 	match event {
 		PDSystemEvent::kEventInit => unsafe {
 			// register the API entry point
-			pd::API = api;
+			sys::API = api;
 
 			// create game state
 			if STATE.is_none() {

api/ctrl/examples/buttons.rs

@@ -6,18 +6,18 @@ use alloc::borrow::Cow;
 use alloc::boxed::Box;
 
 #[macro_use]
-extern crate pd;
+extern crate sys;
 extern crate playdate_controls as controls;
 use alloc::format;
 use alloc::vec::Vec;
 use controls::buttons::PDButtonsExt;
 use controls::buttons::PDButtonsIter;
 use crate::controls::buttons::IterSingleButtons;
-use pd::ffi::*;
+use sys::ffi::*;
 
 
 const INITIAL_X: u32 = LCD_COLUMNS / 2;
-const INITIAL_Y: u32 = (pd::ffi::LCD_ROWS - TEXT_HEIGHT) / 2;
+const INITIAL_Y: u32 = (sys::ffi::LCD_ROWS - TEXT_HEIGHT) / 2;
 const TEXT_HEIGHT: u32 = 16;
 
 
@@ -47,7 +47,7 @@ impl State {
 		let buttons = controls::peripherals::Buttons::get()?;
 
 		unsafe {
-			let graphics = (*pd::API).graphics;
+			let graphics = (*sys::API).graphics;
 			(*graphics).clear?(LCDSolidColor::kColorWhite as LCDColor);
 
 			// render buttons state to string
@@ -102,7 +102,7 @@ impl State {
 				self.pos.y = LCD_ROWS as i32 - TEXT_HEIGHT as i32
 			}
 
-			(*(*pd::API).system).drawFPS?(0, 0);
+			(*(*sys::API).system).drawFPS?(0, 0);
 			Some(())
 		}
 	}
@@ -113,7 +113,7 @@ impl State {
 		match event {
 			// initial setup
 			PDSystemEvent::kEventInit => unsafe {
-				(*(*pd::API).display).setRefreshRate?(20.0);
+				(*(*sys::API).display).setRefreshRate?(20.0);
 			},
 			_ => {},
 		}
@@ -130,7 +130,7 @@ pub extern "C" fn eventHandlerShim(api: *const PlaydateAPI, event: PDSystemEvent
 	match event {
 		PDSystemEvent::kEventInit => unsafe {
 			// register the API entry point
-			pd::API = api;
+			sys::API = api;
 
 			// create game state
 			if STATE.is_none() {