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 needed to set up alternative linking final binary.

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:

cargo +nightly install cargo-playdate --git=https://github.com/boozook/playdate.git

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

• The cargo-playdate supports cargo's auto-targets such as bin and example, but only for binary executable targets ignoring #![crate_type = "lib"] attribute. So if you want to build example-target as lib, that needed for run in simulator, you could declare it in the package manifest like this:

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

  Otherwise example will be built as bin and runnable on device only. In future versions it may be fixed with adding support of rustc command like it does cargo rustc to set --crate-type.

• 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 and for dev-targets - there is dev-assets extra table inherited by package assets.

Troubleshooting

• On any OS in case of a restricted environment 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.