Build System for Playdate applications

Cargo-playdate is a cross-platform plugin for cargo that can build programs for Playdate handheld gaming system written in Rust. It also works as standalone tool.

It can build programs written in Rust, manage assets, build package for Playdate and run on sim or device. Usually it builds static or dynamic libraries for sim and hardware, but also it can build executable binaries for hardware and this method produces highly optimized output with dramatically minimized size (thanks to DCE & LTO)*.

* For executable binaries use --no-gcc argument.

Platform specific pre-req install instructions

MacOS:

1. Install the PlaydateSDK (by default installs into ~/Developer/PlaydateSDK)
2. Set PLAYDATE_SDK_PATH env var: export PLAYDATE_SDK_PATH="$HOME/Developer/PlaydateSDK"
3. Install cmake: brew install cmake
4. Install rust nightly: rustup toolchain install nightly
5. Arm toolchain is included with PlaydateSDK.

Ubuntu Linux:

1. Install the PlaydateSDK - remember where you extracted it.
2. Set PLAYDATE_SDK_PATH env var: export PLAYDATE_SDK_PATH="/path/to/PlaydateSDK-2.x.x/"
3. Install cmake: sudo apt-get install cmake
4. Install rust nightly: rustup toolchain install nightly
5. Install arm toolchain: sudo apt-get install gcc-arm-none-eabi
6. Install libudev: sudo apt-get install libudev-dev

Windows:

1. Install the PlaydateSDK (by default installs into ~/Documents/PlaydateSDK)
2. Set PLAYDATE_SDK_PATH
   1. windows+r, run: sysdm.cpl
   2. Advanced Tab -> Environment Variables -> New
   3. Variable name: PLAYDATE_SDK_PATH
   4. Variable value: C:\Users\username\Documents\PlaydateSDK
3. Install CMake: cmake downloads
4. Install rust nightly: rustup toolchain install nightly
5. Install arm toolchain: arm gnu toolchain downloads. Filename will be like 'arm-gnu-toolchain-13.2.rel1-mingw-w64-i686-arm-none-eabi.exe'.
6. Add arm toolchain and cmake to PATH environment:
   1. windows+r, run: sysdm.cpl
   2. Advanced Tab -> Environment Variables.
   3. Find Path and click Edit
   4. Click New and add C:\Program Files\CMake\bin
   5. Click New and add C:\Program Files (x86)\Arm GNU Toolchain arm-none-eabi\13.2 Rel1\bin

See also: Inside Playdate with C: Prerequisites

Cargo-Playdate Installation

cargo +nightly install cargo-playdate
cargo +nightly playdate --version

Or install to use bleeding edge bits from a local git clone:

mkdir ~/code
cd ~/code
git clone https://github.com/boozook/playdate.git
cargo +nightly install --path="$HOME/code/playdate/cargo" cargo-playdate

Hello World

Generate new project using new or init command.

mkdir -p ~/code/pd-hello/
cd ~/code/pd-hello/
cargo +nightly playdate init --lib --full-metadata --deps="playdate"
cargo +nightly playdate run

Note, there are more options for this command, e.g. --deps="sys:git, controls:git". Run cargo playdate new --help for more about it.

New package will be created.

Take a look at the package manifest file (Cargo.toml).

There is extra metadata for your playdate package.

For more information about metadata read documentation.

Configuration

There is no configuration other then inherited by cargo and some special environment variables.

• CARGO_PLAYDATE_LOG working same way as CARGO_LOG or default RUST_LOG. Also CARGO_PLAYDATE_LOG_STYLE
• PLAYDATE_SDK_PATH path to the SDK root
• ARM_GCC_PATH path to the arm-none-eabi-gcc executable.

Execute cargo playdate -h for more details, or with --help for further more.

Limitations

1. Global crate-level attributes like crate_type and crate_name doesn't supported, e.g:

#![crate_name = "Game"]
#![crate_type = "lib"]

2. Cargo-targets such as bin and example should be in the cargo manifest. Autodetect isn't yet tested and may not work. Example:

[[example]]
name = "demo"
crate-type = ["dylib", "staticlib"]
path = "examples/demo.rs"

3. Assets especially for example cargo-targets inherits from package assets. Currently there's no way to set assets for single cargo-target, but only for entire package or for dev-targets - there is dev-assets extra table inherited by main.

Troubleshooting

• On windows in some cases hardware cannot be ejected because of no permissions. Try to give rights and/or build cargo-playdate with feature eject.

• Welcome to discussions and issues.

This software is not sponsored or supported by Panic.