Docs: Update references to examples.
diff --git a/README.md b/README.md
index 0626365..d6a4492 100644
--- a/README.md
+++ b/README.md
@@ -42,7 +42,7 @@
## Examples / Projects
-The `examples` directory contains example projects, these can be built into both SDL or STM32 binaries and cover a range of techniques from simple concepts to complete games.
+The [32blit-examples](https://github.com/32blit/32blit-examples) repository contains example projects, these can be built into both SDL or STM32 binaries and cover a range of techniques from simple concepts to complete games.
Refer to the OS/platform specific documentation files in the `docs/` folder for instructions on how to compile and run these examples.
diff --git a/docs/32blit.md b/docs/32blit.md
index 1771caa..2fd171b 100644
--- a/docs/32blit.md
+++ b/docs/32blit.md
@@ -34,14 +34,27 @@
### Building An Example
+First you need something to build. The [32blit-examples](https://github.com/32blit/32blit-examples) repository includes a series of demos showcasing various 32blit SDK features. These instructions will assume you're building those and have cloned or extracted that repository alongside 32blit-sdk:
+
+```shell
+git clone https://github.com/32blit/32blit-examples
+```
+
+Your directory tree should look something like:
+
+- root_dir
+ - 32blit-sdk
+ - 32blit-examples
+
To build an example for 32blit using `arm-none-eabi-gcc` you must prepare the Makefile with CMake using the provided toolchain file.
From the root of the repository:
```
+cd 32blit-examples
mkdir build.stm32
cd build.stm32
-cmake .. -DCMAKE_TOOLCHAIN_FILE=../32blit.toolchain
+cmake .. -DCMAKE_TOOLCHAIN_FILE=../../32blit-sdk/32blit.toolchain
```
And then run `make examplename` to build an example.
diff --git a/docs/macOS.md b/docs/macOS.md
index 59c92e5..c4f79fa 100644
--- a/docs/macOS.md
+++ b/docs/macOS.md
@@ -6,9 +6,10 @@
- [Python3](#python3)
- [Installing python3](#installing-python3)
- [Installing pip3 dependecies](#installing-pip3-dependecies)
+ - [Verifying install](#verifying-install)
- [Installing `gcc-arm-none-eabi`](#installing-gcc-arm-none-eabi)
-- [Building & Running on 32Blit](#building--running-on-32blit)
-- [Building & Running Locally](#building--running-locally)
+- [Building \& Running on 32Blit](#building--running-on-32blit)
+- [Building \& Running Locally](#building--running-locally)
- [Build Everything](#build-everything)
- [Troubleshooting](#troubleshooting)
@@ -87,7 +88,19 @@
brew install sdl2 sdl2_image sdl2_net
```
-Then, set up the 32Blit Makefile from the root of the repository with the following commands:
+You also need something to build. The [32blit-examples](https://github.com/32blit/32blit-examples) repository includes a series of demos showcasing various 32blit SDK features. These instructions will assume you're building those and have cloned or extracted that repository alongside 32blit-sdk:
+
+```shell
+git clone https://github.com/32blit/32blit-examples
+```
+
+Your directory tree should look something like:
+
+- root_dir
+ - 32blit-sdk
+ - 32blit-examples
+
+Create a build directory and configure the examples. The 32blit-sdk should be automatically detected:
```shell
mkdir build
diff --git a/docs/pico.md b/docs/pico.md
index bb8baba..a8f3ce2 100644
--- a/docs/pico.md
+++ b/docs/pico.md
@@ -5,18 +5,22 @@
Since RP2040 is slower and less capable than 32blit's STM32H750 there are some limitations, but most of the 32blit SDK conceniences work well.
- [Why use 32blit SDK on PicoSystem?](#why-use-32blit-sdk-on-picosystem)
-- [Building The SDK & Examples](#building-the-sdk--examples)
+- [Building The SDK \& Examples](#building-the-sdk--examples)
- [Fetch Pico SDK Automatically (Quick-Start)](#fetch-pico-sdk-automatically-quick-start)
+ - [Building Examples](#building-examples)
- [Existing Pico SDK (Advanced)](#existing-pico-sdk-advanced)
- [Starting Your Own 32blit SDK Project](#starting-your-own-32blit-sdk-project)
- [Coniguring PicoSystem builds](#coniguring-picosystem-builds)
- [Building](#building)
- [Copying to your PicoSystem](#copying-to-your-picosystem)
- [Extra configuration](#extra-configuration)
-- [API Limitations & Board Details](#api-limitations--board-details)
+- [API Limitations \& Board Details](#api-limitations--board-details)
- [Unsupported Features](#unsupported-features)
- [Limitations](#limitations)
- [Board-specific details](#board-specific-details)
+- [Troubleshooting](#troubleshooting)
+ - [fatal error: tusb.h: No such file or directory](#fatal-error-tusbh-no-such-file-or-directory)
+
## Why use 32blit SDK on PicoSystem?
@@ -67,19 +71,49 @@
You might also want to add this to the bottom of your `~/.bashrc`.
+And finally you should fetch the 32blit SDK and examples:
+
+```
+git clone https://github.com/32blit/32blit-sdk
+git clone https://github.com/32blit/32blit-examples
+```
+
### Fetch Pico SDK Automatically (Quick-Start)
You can use Pico SDK's fetch-from-git feature and build like so:
```
-git clone https://github.com/32blit/32blit-sdk
cd 32blit-sdk
mkdir build.pico
cd build.pico
cmake .. -D32BLIT_DIR=`pwd`/.. -DPICO_SDK_FETCH_FROM_GIT=true -DPICO_EXTRAS_FETCH_FROM_GIT=true -DPICO_BOARD=pimoroni_picosystem
```
-And then run `make` as usual.
+The 32blit SDK includes only `picosystem-hardware-test` which you can make with:
+
+```
+make picosystem-hardware-test
+```
+
+
+#### Building Examples
+
+The [32blit-examples](https://github.com/32blit/32blit-examples) repository includes a series of demos showcasing various 32blit SDK features.
+
+In order to compile examples against pico-sdk, your directory tree should look something like:
+
+- root_dir
+ - 32blit-sdk
+ - 32blit-examples
+
+For example:
+
+```
+cd 32blit-examples
+mkdir build.pico
+cd build.pico
+cmake .. -D32BLIT_DIR=`pwd`/.. -DPICO_SDK_FETCH_FROM_GIT=true -DPICO_EXTRAS_FETCH_FROM_GIT=true -DPICO_BOARD=pimoroni_picosystem
+```
Now you can start hacking on an existing example, or skip to [Starting Your Own 32blit SDK Project](#starting-your-own-32blit-sdk-project).
@@ -89,11 +123,18 @@
To build for a pico-based device you need to specify both the 32blit and Pico SDK paths, and the device/board you are building for.
+Your directory tree should look something like:
+
+- root_dir
+ - 32blit-sdk
+ - 32blit-examples
+ - pico-sdk
+ - pico-extras
+
To build the examples for a PicoSystem:
```
-git clone https://github.com/32blit/32blit-sdk
-cd 32blit-sdk
+cd 32blit-examples
mkdir build.pico
cd build.pico
cmake .. -D32BLIT_DIR=`pwd`/.. -DPICO_SDK_PATH=/path/to/pico-sdk -DPICO_BOARD=pimoroni_picosystem
@@ -217,3 +258,9 @@
* ‡ - makes a best-effort attempt to play any `SQUARE` waveforms (single-channel)
* § - 362K main RAM, 64K D3 RAM, 127K DTCMRAM, 30K ITCMRAM
* ¶ - setting `ALLOW_HIRES=0` allocates a doubled buffered 120x120 16bit framebuffer (56.25k) and disables the hires screen mode.
+
+# Troubleshooting
+
+## fatal error: tusb.h: No such file or directory
+
+You forgot to `git submodule update --init` in your local copy of `pico-sdk`.
\ No newline at end of file
