Lowered the Swift tools required to build this project to 6.3 and also, polished some documentation in the READMe file.
This commit is contained in:
@@ -0,0 +1,72 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- Generator: Adobe Illustrator 19.2.1, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
|
||||
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
|
||||
viewBox="0 0 1551 995" style="enable-background:new 0 0 1551 995;" xml:space="preserve">
|
||||
<style type="text/css">
|
||||
.st0{fill:#FAC133;}
|
||||
</style>
|
||||
<g>
|
||||
<path class="st0" d="M533.8,18.6c50.3-0.3,100.5,0,150.8-0.1c0,114,0,228,0,342c-0.1,36.9,0.2,73.8-0.1,110.8
|
||||
c-50.2-0.1-100.4,0-150.6-0.1C533.9,320.3,534,169.5,533.8,18.6z"/>
|
||||
<g>
|
||||
<path class="st0" d="M799.9,119.8c32.3-17.4,69.1-25.4,105.5-26.3c23.4-0.9,46.9,0.8,69.8,5.2c15.9,3.5,31.5,8.4,45.9,16.1
|
||||
c14,7.7,27.5,16.7,38.6,28.4c15.2,15.7,25.4,35.9,29.6,57.2c4.1,18.8,3.6,38.1,4.1,57.1c-0.1,71.2,0,142.5-0.1,213.7
|
||||
c-50.1,0-100.2-0.1-150.2,0.1c-0.3-16,0-32.1-0.1-48.1c-16.1,25-41,44.5-69.7,52.9c-10.3,3.3-21.1,4.8-32,5.4
|
||||
c-13.7,0.2-27.6,1-41-2.6c-34.7-7.8-64.8-33.3-78.2-66.3c-6.4-15.5-9.1-32.4-8.3-49.1c-0.8-32.4,12.3-65.4,36.6-87.1
|
||||
c11.8-11,26.1-19.1,40.9-25.2c23.5-9.1,49-12.3,74-11.3c17.4,1.1,34.9,3.4,51.8,7.9c8.8,2.1,17.3,5.2,25.9,7.8
|
||||
c2.2-19.6-2.4-40-13.3-56.4c-4.7-6.8-9.8-13.6-16.8-18.1c-11.6-8-25.4-12.8-39.5-13c-11.7,0.2-23.6,1-34.8,4.6
|
||||
c-17,5-32.4,14.7-45.5,26.5c-5.5,4.6-10.4,9.8-15.6,14.8c-15.1-12.3-30.2-24.7-45.4-36.9C751.3,154.4,773.8,134.1,799.9,119.8z
|
||||
M890.9,315.1c-9.4,3-18.5,8.3-24.2,16.6c-7.7,10.7-9.8,25.1-5.9,37.7c4.7,14.9,19.8,26.3,35.6,25.5c18.1-0.3,35.4-9.7,46.5-23.9
|
||||
c0-17.9-0.3-35.8-0.2-53.8c-8.2-2.5-16.7-4-25.2-4.4C908.7,312,899.6,312.8,890.9,315.1z"/>
|
||||
</g>
|
||||
<g>
|
||||
<path class="st0" d="M303.8,111.9c16.4-6.3,34.1-9.5,51.7-8.4c14.1,0.2,28.2,2.1,41.7,6.3c29.1,8.7,54.7,27.9,72.1,52.8
|
||||
c25.7,35.8,36.4,80.4,37.5,123.9c1,42.6-7.4,86.2-28.8,123.4c-15.9,27.9-40.2,51.2-69.6,64.5c-13.9,6.1-28.7,10-43.8,11.6
|
||||
c-14.7,1.1-29.8,1.8-44.3-1.7c-29.4-5.7-56-23.6-73.4-47.9c0,42.2-0.2,84.4,0.1,126.5c-15.8,0.5-31.7,0.1-47.6,0.2
|
||||
c-34.1,0-68.3-0.1-102.4,0c-0.2-150.4,0-300.8-0.1-451.3c50-0.1,99.9-0.1,149.9,0c0,15.9,0,31.7,0,47.6
|
||||
C260.2,138.2,280.5,121.4,303.8,111.9z M247.3,216.7c-0.2,52.4-0.1,104.7-0.4,157c11.6,10.3,27.1,15.6,42.6,15.4
|
||||
c7.9-0.5,15.5-2.8,22.6-6.2c14.1-7.6,24.4-21,30.1-35.7c9.5-24,9.9-50.4,7.1-75.7c-2.3-18.2-7.3-37.1-19.5-51.3
|
||||
c-9.4-11.2-23.8-17.5-38.3-17.8C275.7,202.2,259.9,207.2,247.3,216.7z"/>
|
||||
</g>
|
||||
<path class="st0" d="M1085.6,112c52.8,0,105.7,0,158.5,0c20.2,65.4,41.3,130.7,55.1,197.8c17.5-67.1,41.8-132.2,64.1-197.8
|
||||
c39.9-0.1,79.9-0.1,119.8,0c-43.1,100.9-86.1,201.9-129.2,302.9c-14.7,34.6-29.4,69.5-50.5,100.7c-11.7,16.8-25.2,32.7-41.5,45.3
|
||||
c-29,23.5-65.8,35.7-102.5,40.1c-24.6,2.9-49.4,3.3-74.1,2.6c0-18.8,0-37.5,0-56.3c22.9-1.6,46-7.1,65.6-19.4
|
||||
c13.6-8.2,25.1-19.6,35-31.9c13.7-17.4,24.6-36.9,35.4-56.2C1176,330.5,1130.8,221.2,1085.6,112z"/>
|
||||
<g>
|
||||
<path class="st0" d="M281.3,515.3c50.2,0,100.4,0,150.7,0c0,149.6,0,299.1,0,448.7c-41.1,0.1-82.3,0-123.5,0
|
||||
c-9.1-0.1-18.2,0.2-27.3-0.2c0.2-15.7,0-31.3,0.1-47c-15.7,25.3-40.7,45-69.5,52.9c-20.5,5.8-42.2,5.7-63.2,2.8
|
||||
C117.3,968,87.8,952,67.1,928c-25.3-28.9-38.8-66.3-44-103.9c-6-44.8-2.1-91.3,14.3-133.5c10.9-27.8,28-53.8,51.5-72.6
|
||||
c23.5-18.7,53.5-28.8,83.5-29.1c19.4-1.3,39.2,1.8,57.1,9.4c20.6,9.1,38.7,23.7,51.5,42.2C281.2,598.8,281.2,557,281.3,515.3z
|
||||
M209.8,695.8c-13.1,9.1-21.6,23.4-26.7,38.2c-7.1,21.4-8.3,44.3-6.3,66.6c1.9,18.9,7.2,38.3,19.5,53.2
|
||||
c10.7,13.3,28.2,20.4,45.2,19c14-1.2,28-5.8,39.4-14c-0.1-52.4,0.4-104.8,0.3-157.2c-7.8-6.8-17.8-11.5-28.1-13.6
|
||||
C238.5,684.2,222.1,686.9,209.8,695.8z"/>
|
||||
</g>
|
||||
<path class="st0" d="M905.8,548.5c50,0,99.9,0,149.9,0c0,29.3,0,58.6,0,88c20.8,0,41.5,0,62.3,0c0.1,28.5-0.1,57,0.1,85.6
|
||||
c-20.8,0.5-41.6-0.2-62.3,0.3c0.2,41.7,0,83.4,0.1,125c0,10.8,1.3,21.9,6.1,31.7c5.9,12.6,19.9,19.8,33.6,19.4
|
||||
c8.5,0,17-0.7,25.1-3.3c5.9,16,12,32,17.6,48.2c-14.8,10.2-30.7,19-47.8,24.6c-20.7,7.3-42.9,10.5-64.8,9.9
|
||||
c-24.1,0.5-48-6.6-68.8-18.7c-12.2-7.7-24.3-16.5-32.2-28.8c-13.3-19.2-17.9-43-18.5-66c-0.4-19.3-0.1-38.6-0.2-58
|
||||
c0-28.1-0.1-56.3,0-84.4c-13.3-0.3-26.6-0.1-39.9-0.1c-0.1-28.5,0-57-0.1-85.5c13.3-0.1,26.6,0,39.9,0
|
||||
C905.8,607.2,905.8,577.9,905.8,548.5z"/>
|
||||
<g>
|
||||
<path class="st0" d="M628.6,588.1c28.5-3,57.4-2.8,85.7,1.7c13.8,1.9,27.2,5.8,40.3,10.6c28,11.5,54.2,29.9,69.8,56.3
|
||||
c9.6,16,14.7,34.4,16.7,52.9c1.5,12.9,1.3,26,1.6,39c-0.2,71.8-0.3,143.6-0.5,215.5c-50.2,0-100.4,0-150.6,0
|
||||
c-0.2-16,0.1-32-0.1-48c-10.5,16-24.1,30.1-40.6,39.8c-11.7,7.4-24.8,12.6-38.3,15.7c-13.5,3.1-27.4,3.1-41.1,3.1
|
||||
c-26.5-0.7-52.6-11-72.1-29c-22.2-19.6-35.7-48.6-36.9-78.2c-0.3-13.7-0.2-27.6,3.2-41c4.9-20.7,15.5-40.1,30.9-54.8
|
||||
c26.2-25.3,62.9-37.2,98.8-38.6c17.8-1,35.5,1,53,3.9c14.7,2.6,29.1,7,43.3,11.8c2.9-26.1-6.7-53.5-26.2-71.3
|
||||
c-11.8-9.1-26.1-15.3-41.1-16c-18.3-1-37.1,2.2-53.6,10.5c-17.4,8.3-31.7,21.5-45.1,35.1c-14.8-12.5-29.8-24.8-44.5-37.3
|
||||
c23-26.9,50.6-50.9,83.5-64.7C585,596,606.8,591,628.6,588.1z M641.4,807.7c-10.8,2.9-21.2,9.1-27.1,18.9
|
||||
c-6.4,9.9-8.2,22.5-5.3,33.9c2.6,9.6,9.2,17.9,17.9,22.7c11,6.6,24.9,5.7,36.4,1.2c11.3-3.9,20.9-11.6,28.1-21
|
||||
c0-17.8,0.2-35.6-0.1-53.4C675.1,806.2,657.9,803.5,641.4,807.7z"/>
|
||||
</g>
|
||||
<g>
|
||||
<path class="st0" d="M1247.4,602.5c21-8.7,43.5-13.2,66-14.7c23.9-1.5,48.2-0.3,71.4,6.1c18.4,4.6,36.1,12.2,52.7,21.5
|
||||
c27.5,16,50.5,39.8,65,68.2c11.2,21.5,17.8,45.2,21.2,69.1c3,20.3,3.2,40.9,3.6,61.4c-81.4,0-162.9,0-244.3,0
|
||||
c1.2,20.3,10.1,40.1,24.8,54.2c13.2,12.4,29.9,21.1,47.8,24.5c18.2,4,37.2,1.7,55-3.2c24.9-7.2,47.3-22.2,64-42
|
||||
c12.9,11.3,25.9,22.6,38.8,34c-21.1,32.5-51.7,58.9-87.1,74.8c-19.5,8.9-40.5,14.6-61.8,17c-12.3,1.5-24.7,1.2-37.1,1
|
||||
c-25.2-0.9-50.5-4.9-74.3-13.6c-16.9-6.2-33.1-14.5-47.6-25.3c-28.4-20.5-49.4-50.3-60.7-83.3c-7.2-20.7-10.7-42.7-11.1-64.6
|
||||
c-1.6-43.9,10.2-88.8,36.2-124.6C1189.1,635.8,1216.8,615,1247.4,602.5z M1313.6,670.7c-9.3,3.5-16.7,10.8-21.8,19.1
|
||||
c-8.8,15-12.1,32.5-14,49.7c35.1,0,70.2,0,105.3,0c-1.2-17.6-2.7-36.1-12.2-51.4c-5.9-9.9-16-17.2-27.4-19.4
|
||||
C1333.7,666.8,1323.1,667,1313.6,670.7z"/>
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 5.9 KiB |
@@ -1,4 +1,4 @@
|
||||
// swift-tools-version: 6.4
|
||||
// swift-tools-version: 6.3
|
||||
|
||||
import PackageDescription
|
||||
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
// swift-tools-version: 6.4
|
||||
// swift-tools-version: 6.3
|
||||
|
||||
import PackageDescription
|
||||
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
# PlaydateKit
|
||||
|
||||
[](https://github.com/<you>/playdate-kit/actions/workflows/ci.yml)
|
||||
|
||||
|
||||
Swift bindings to the [Playdate](https://play.date) C API.
|
||||
|
||||
The Playdate C API is delivered as a `PlaydateAPI*` struct of function pointers that the firmware hands to your game at launch. This package wraps that surface in idiomatic Swift: namespaced APIs, wrapper types with ownership semantics, closures instead of function-pointer/userdata pairs, `OptionSet`s and `enum`s instead of raw constants, and typed `throws` for fallible calls.
|
||||
The Playdate C API is delivered as a `PlaydateAPI*` struct of function pointers that the firmware hands to your game at launch. This package wraps that surface in idiomatic Swift: namespaced APIs, wrapper types with ownership semantics, closures instead of function-pointer/userdata pairs, `OptionSet` and `enum` types instead of raw constants, and typed `throws` for fallible calls.
|
||||
|
||||
All ten C subsystems are covered:
|
||||
|
||||
@@ -24,11 +24,15 @@ All ten C subsystems are covered:
|
||||
## Requirements
|
||||
|
||||
- The [Playdate SDK](https://play.date/dev/) (3.1.1 or later). The SDK is not vendored into this repository.
|
||||
- Swift 6.4 tools or later.
|
||||
- Swift 6.3 tools or later.
|
||||
|
||||
Device builds additionally need:
|
||||
|
||||
- A [swift.org development snapshot toolchain](https://www.swift.org/install/macos/) — Xcode's toolchain does not ship the Embedded Swift stdlib for the device target (`armv7em-none-none-eabi`).
|
||||
- A [swift.org development snapshot toolchain](https://www.swift.org/install/macos/) — Xcode's toolchain does not ship the Embedded Swift stdlib for the device target (`armv7em-none-none-eabi`). The easiest way to get one is to install [Swiftly](https://www.swift.org/swiftly/), Swift's toolchain manager, and install the `main-snapshot` toolchain with it:
|
||||
|
||||
```sh
|
||||
swiftly install main-snapshot
|
||||
```
|
||||
- The [Arm GNU toolchain](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads) (`arm-none-eabi-gcc`) on your `PATH`, which the Playdate SDK's build support uses to compile and link the device binary.
|
||||
|
||||
### One-time SDK setup
|
||||
@@ -48,21 +52,27 @@ If Xcode had the package open before you ran the setup, make it re-read the mani
|
||||
```swift
|
||||
// Package.swift of your game
|
||||
dependencies: [
|
||||
.package(url: "https://github.com/<you>/playdate-kit.git", from: "0.1.0"),
|
||||
// …or, while developing locally:
|
||||
// .package(path: "../playdate-kit"),
|
||||
.package(
|
||||
url: "https://github.com/rock-n-code/playdate-kit.git",
|
||||
from: "0.1.0"
|
||||
),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "MyGame",
|
||||
dependencies: [.product(name: "PlaydateKit", package: "playdate-kit")]
|
||||
dependencies: [
|
||||
.product(
|
||||
name: "PlaydateKit",
|
||||
package: "playdate-kit"
|
||||
)
|
||||
]
|
||||
),
|
||||
]
|
||||
```
|
||||
|
||||
## Getting started
|
||||
|
||||
A Playdate game has a single C entry point, `eventHandler`. Export it with `@_cdecl`, initialize the binding on the first event, and install an update callback:
|
||||
A Playdate application or game has a single C entry point, `eventHandler`. Export it with `@_cdecl`, initialize the binding on the first event, and install an update callback:
|
||||
|
||||
```swift
|
||||
import CPlaydate
|
||||
@@ -307,7 +317,7 @@ Shipping a `.pdx` needs the Playdate toolchain on top:
|
||||
|
||||
[`Examples/swift.mk`](Examples/swift.mk) packages the device pipeline: it locates the SDK and a Swift snapshot toolchain, compiles the `PlaydateKit` wrapper as a module-aliased Embedded Swift module, and hooks the game objects into the SDK's `common.mk`. A game needs only a short Makefile on top — [`Examples/HelloPlaydate/Makefile`](Examples/HelloPlaydate/Makefile) is the template, and `make` in that directory produces a `.pdx` containing both the device binary and the simulator dylib. Swift code is compiled `-Osize` by default (measured ~15% smaller than `-O` on the example); override with `make SWIFT_OPT=-O`. The setup follows Apple's [swift-playdate-examples](https://github.com/apple/swift-playdate-examples), adapted to this package.
|
||||
|
||||
The wrappers are written within the Embedded Swift subset for exactly this reason: no Foundation, no reflection, no untyped throws. That claim is enforced, not aspirational: the check cross-compiles the whole module for `armv7em-none-none-eabi` with Embedded Swift enabled and the device's `-fshort-enums` ABI, and CI runs it on every push. Running it locally needs the same snapshot toolchain and Arm GNU toolchain headers:
|
||||
The wrappers are written within the Embedded Swift subset for exactly this reason: no Foundation, no reflection, no untyped throws. That claim is enforced, not aspirational: the check cross-compiles the whole module for `armv7em-none-none-eabi` with Embedded Swift enabled and the device's `-fshort-enums` ABI. Running it needs the same snapshot toolchain and Arm GNU toolchain headers:
|
||||
|
||||
```sh
|
||||
make embedded
|
||||
@@ -326,7 +336,7 @@ A root Makefile fronts the development lifecycle; a bare `make` (or `make help`)
|
||||
| `make outdated` / `make upgrade` | Show / apply updates to the SwiftPM dependencies |
|
||||
| `make embedded` | Compile-only device check (Embedded Swift, `armv7em-none-none-eabi`) |
|
||||
| `make consumer-test` | Build and run a scratch package depending on playdate-kit |
|
||||
| `make check` | Everything CI runs: build, test, embedded, consumer-test |
|
||||
| `make check` | The full verification suite: build, test, embedded, consumer-test |
|
||||
| `make docs` / `make docs-preview` | Generate / preview the DocC documentation |
|
||||
| `make example` / `make example-run` | Build the HelloPlaydate example / open it in the Playdate Simulator |
|
||||
| `make clean` | Remove build products of the package and the example |
|
||||
@@ -356,34 +366,22 @@ The API reference is a DocC catalog. Generate it locally with:
|
||||
make docs
|
||||
```
|
||||
|
||||
serve it in a local web server with `make docs-preview`, or browse it with Xcode's documentation viewer (Product ▸ Build Documentation). Pushes to `main` publish the rendered docs to GitHub Pages via `.github/workflows/docs.yml` (enable Pages ▸ Source: GitHub Actions in the repository settings once).
|
||||
serve it in a local web server with `make docs-preview`, or browse it with Xcode's documentation viewer (Product ▸ Build Documentation).
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
Examples/
|
||||
swift.mk Shared make rules for device builds: toolchain/SDK
|
||||
discovery and Embedded Swift compile flags
|
||||
HelloPlaydate/ Minimal game buildable into a .pdx for the simulator
|
||||
(build.sh) or simulator + device (make)
|
||||
swift.mk Shared make rules for device builds: toolchain/SDK discovery and Embedded Swift compile flags
|
||||
HelloPlaydate/ Minimal game buildable into a .pdx for the simulator (build.sh) or simulator + device (make)
|
||||
Scripts/
|
||||
install-pkgconfig.sh One-time setup: points the "playdate" pkg-config
|
||||
module at your SDK installation
|
||||
build-embedded.sh Compile-only device check: Embedded Swift for
|
||||
armv7em-none-none-eabi with the device ABI (CI)
|
||||
consumer-test.sh Builds a scratch package depending on playdate-kit
|
||||
to prove settings propagate to consumers (CI)
|
||||
install-pkgconfig.sh One-time setup: points the "playdate" pkg-config module at your SDK installation
|
||||
build-embedded.sh Compile-only device check: Embedded Swift for armv7em-none-none-eabi with the device ABI
|
||||
consumer-test.sh Builds a scratch package depending on playdate-kit to prove settings propagate to consumers
|
||||
Sources/
|
||||
CPlaydate/ System library target: module map + umbrella header
|
||||
importing pd_api.h from the SDK, plus inline shims for
|
||||
the variadic log/error functions
|
||||
PlaydateKit/ The Swift bindings, one folder per subsystem (System,
|
||||
Graphics, Sound, ...) holding one type per file, grouped
|
||||
by kind (Classes, Structures, Enumerations, Aliases);
|
||||
Sound is further split into the Source, Signal, Effect,
|
||||
and Synth subdomains. Also holds the shared Support.swift
|
||||
helpers and the PlaydateKit.docc documentation catalog
|
||||
|
||||
CPlaydate/ System library target: module map + umbrella header importing pd_api.h from the SDK, plus inline shims for the variadic log/error functions
|
||||
PlaydateKit/ The Swift bindings, one folder per subsystem (System, Graphics, Sound, ...) holding one type per file, grouped by kind (Classes, Structures, Enumerations, Aliases);
|
||||
Sound is further split into the Source, Signal, Effect, and Synth subdomains. Also holds the shared Support.swift helpers and the PlaydateKit.docc documentation catalog
|
||||
Tests/
|
||||
PlaydateKit/ Host-runnable tests for the pure value types
|
||||
```
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
internal import CPlaydate
|
||||
// A public import: `addFunction(_:name:)` and `pushFunction(_:)` expose the
|
||||
// `CFunction` alias of `lua_CFunction` in their public signatures.
|
||||
public import CPlaydate
|
||||
|
||||
/// The cached `playdate->lua` C API table.
|
||||
var luaAPI: UnsafePointer<playdate_lua> { Playdate.luaAPI.unsafelyUnwrapped }
|
||||
|
||||
Reference in New Issue
Block a user