# Modular low-level Playdate API
Low-level bindings to Playdate API with optional adapted official documentation and optional lang-items.
## Main concepts in a thesis statement
1. We must panic when something wrong and we cannot recover from it. To give an example, when we hit null-ptr in api, thi is fatal.
2. We must return error when API returns error.
That looks pretty hardcore. That's why there is four+ possible ways to get access to API endpoints, among them returning `Option` or `Result`.
_I've experimented enough with wrapping the entire API with results at every step, then painstakingly optimized their unfolding. And in the end I came to the conclusion that in this exact project the number of errors/results should be minimized._
## What's inside
- cffi bindings
- pre-generated cffi bindings
- minimal required parts such as lang-items
- simple entry point
- additional utils like `println` macro
## Prerequisites
MNRV is [`1.81.0` from 2024-06-30][rust-toolchain.toml]
1. Rust __nightly__ toolchain (rustup is optional)
1. [Playdate SDK][sdk]
- Ensure that env var `PLAYDATE_SDK_PATH` points to the SDK root
1. Follow the [official documentation][doc-prerequisites]
- Ensure that `arm-none-eabi-gcc` or `gcc-arm-none-eabi` in your `PATH`
[sdk]: https://play.date/dev/#cardSDK
[doc-prerequisites]: https://sdk.play.date/Inside%20Playdate%20with%20C.html#_prerequisites
[rust-toolchain.toml]: https://github.com/boozook/playdate/blob/main/rust-toolchain.toml#L2
## Usage
Minimal example of the application
1. Setup library with crate-type
2. Add playdate-sys dependency
Cargo.toml:
```toml
[lib]
name = "example"
path = "src/lib.rs"
crate-type = [
"dylib", # for simulator
"staticlib", # for hardware
]
[dependencies.pd]
package = "playdate-sys"
git = "this/repo/path.git"
```
3. Next is just minimal required initialization code and additionally code that prints all received events
src/lib.rs:
```rust
#![no_std]
use core::ffi::*;
#[macro_use]
extern crate alloc;
#[macro_use]
extern crate pd;
use pd::ffi::*;
#[no_mangle]
// Note: `_arg` is a key-code in simulator, otherwise it's just zero.
pub extern "C" fn eventHandlerShim(api: *const PlaydateAPI, event: PDSystemEvent, _arg: u32) -> c_int {
match event {
PDSystemEvent::kEventInit => unsafe {
// register the API entry point
pd::API = api;
// get `setUpdateCallback` fn
let f = (*(*api).system).setUpdateCallback.unwrap();
// register update callback
f(Some(on_update), core::ptr::null_mut());
// `println` uses `API` internally, that set above
println!("Init, Hello world!");
},
PDSystemEvent::kEventLock => println!("Lock"),
PDSystemEvent::kEventUnlock => println!("Unlock"),
PDSystemEvent::kEventPause => println!("Pause"),
PDSystemEvent::kEventResume => println!("Resume"),
PDSystemEvent::kEventLowPower => println!("LowPower"),
PDSystemEvent::kEventTerminate => println!("Terminate"),
PDSystemEvent::kEventInitLua => println!("InitLua"),
// simulator only, keyboard events:
PDSystemEvent::kEventKeyPressed => println!("KeyPressed"),
PDSystemEvent::kEventKeyReleased => println!("KeyReleased"),
}
0 // zero means "OK, no error, continue please"
}
unsafe extern "C" fn on_update(_: *mut c_void) -> i32 { 1 /* `1` means "OK, continue updates" */ }
```
1. Also add the following config needed for proper build configuration
.cargo/config.toml:
```toml
[target.thumbv7em-none-eabihf]
rustflags = [
"-Ctarget-cpu=cortex-m7",
"-Ctarget-feature=-fp64",
"-Clink-args=--emit-relocs",
"-Crelocation-model=pic",
"-Csoft-float=no",
"-Clink-arg=--cref",
"-Clink-arg=--gc-sections",
"-Clink-arg=--entry=eventHandlerShim"
]
# Also I recommend to allow unstable options here:
[unstable]
unstable-options = true
```
5. Now build it
```shell
cargo build --lib --release --target=thumbv7em-none-eabihf -Zbuild-std=core,alloc -Zunstable-options
# Note: on windows use gcc-arm-none-eabi instead
arm-none-eabi-gcc ./target/thumbv7em-none-eabihf/release/libexample.a \
-nostartfiles -mthumb -mcpu=cortex-m7 -mfloat-abi=hard -mfpu=fpv5-sp-d16 -D__FPU_USED=1 \
-Wl,--cref,--gc-sections,--no-warn-mismatch,--emit-relocs -mword-relocations \
-fno-common -fno-exceptions \
-T$PLAYDATE_SDK_PATH/C_API/buildsupport/link_map.ld \
-o ./target/thumbv7em-none-eabihf/release/example.elf \
--entry eventHandlerShim
# Then prepare package with manifest and assets, place into it example.elf and call
# `$PLAYDATE_SDK_PATH/bin/pdc` with path of prepared package.
```
6. Then prepare package with manifest and assets, place into it example.elf and then
call `$PLAYDATE_SDK_PATH/bin/pdc` with path of prepared package.
7. Install and run on device.
⚠️ Note that [cargo-playdate][cargo-playdate-crates] can do it all for you easily. Also it can build executable binaries.
full list of derive- features
- bindings-derive-default
- bindings-derive-eq
- bindings-derive-copy
- bindings-derive-debug
- bindings-derive-hash
- bindings-derive-ord
- bindings-derive-partialeq
- bindings-derive-partialord