32blit · Gadgetoid · May 17, 2023
diff --git a/README.md b/README.md
@@ -42,7 +42,7 @@ The `32blit-stm32` directory contains the STM32 HAL for 32blit, compatible with
 
 ## 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
@@ -34,14 +34,27 @@ You should also make sure you have a cross-compile environment set up on your co
 
 ### 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
@@ -6,9 +6,10 @@ These instructions cover building 32blit on macOS.
   - [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 @@ You'll need to install `SDL2`, `SDL2 Image` and `SDL2 Net`
 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
@@ -5,18 +5,22 @@ The Pico port brings the 32blit SDK to PicoSystem and other RP2040-based devices
 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 @@ export PATH=$PATH:~/.local/bin
 
 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 @@ This requires a working Pico SDK setup ([Getting started with Raspberry Pi Pico]
 
 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 @@ The RP2040/Pico port supports PicoSystem and VGA board. Below is a table showing
 * ‡ - 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`.