Switch to Ninja and add README #53

will-v-pi · 2025-06-06T14:12:48Z

Install Ninja and switch the pico-examples build over to that, so you get automatic multithreading without -j giving simpler command line instructions, and a shorter build output.

Add a README which:

Explains the purpose of the script & how to run it
Mentions VS Code extension as the way to go if you want a GUI
Includes some quick Getting Started bits for command line compilation
Adds basic command line setup instructions for other OSes that can't use the script (including mentioning that Linux with apt should work with the script)

Also build for W picos as well

Adds some simple command line instructions, along with basic setup instructions for other OSes that can't use this script

README.md

kilograham · 2025-06-06T16:33:39Z

README.md

+
+For more details on debugging with GDB, see the [GDB docs](https://sourceware.org/gdb/current/onlinedocs/gdb.html/)
+
+## Multiple Terminals


is this really something we should include? won't most people just open multiple terminal instances?

Given this script is to support Raspberry Pi OS Lite (as VS Code can be used everywhere else), I wanted to include how to have multiple terminals on that

README.md

lurch · 2025-06-07T08:09:47Z

README.md

+cd pico/pico-examples
+```
+
+Depending on the board you're using (eg pico2), replace `build_pico` with the relevant build directory (eg `build_pico2`) in the following commands.


I'm not sure about this advice to create a board-specific build directory - IIRC we've never done that elsewhere in any of our other documentation?
(also, I suspect the vast majority of people will only have a single board and/or single type of board?)

This recommendation was to follow how the script works (which uses board specific build directories), as then you can follow the instructions above exactly. Also, it avoids the need to say that you need to delete build directories when switching between Pico and Pico 2, but not Pico and Pico W

README.md

lurch · 2025-06-07T08:17:56Z

This expanded documentation is great; but in order to avoid duplication of effort, I wonder if it might be better to add it to https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf instead and then have this README.md point people to that? 🤔

will-v-pi · 2025-06-09T11:55:19Z

This expanded documentation is great; but in order to avoid duplication of effort, I wonder if it might be better to add it to https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf instead and then have this README.md point people to that? 🤔

I think I want to put the command line Getting Started here instead - that document should really focus on VS Code for getting started, as that's the easiest way to get set up (if you have a GUI). It also means the script and the documentation are in the same place, so they're easier to keep in sync.

lurch · 2025-06-09T13:46:22Z

I think I want to put the command line Getting Started here instead - that document should really focus on VS Code for getting started

Fair enough; as long as there's no duplication of documentation, and each place points to where "the other thing" is documented, I think I'm happy 🙂

lurch · 2025-06-19T14:58:09Z

README.md

+
+To debug programs on the Pico-series microcontroller, you first need to attach a debugger such as the [Debug Probe](https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html#getting-started). Once that's done, you can attach OpenOCD to your Pico-series microcontroller with:
+```bash
+openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000"


I guess this ought to mention using rp2350.cfg for Pico 2?

lurch · 2025-06-19T15:01:00Z

README.md

+gdb -ex "target extended-remote localhost:3333"
+```
+
+Then in GDB, run the following (replacing blink.elf with the path to blink.elf if it's not in the current directory)


The earlier example of using picotool used the explicit path build_pico/blink/blink.uf2, so perhaps this example ought to be using the explicit path build_pico/blink/blink.elf ?

lurch · 2025-06-19T15:02:50Z

README.md

+
+Depending on the board you're using (eg pico2), replace `build_pico` with the relevant build directory (eg `build_pico2`) in the following commands.
+
+> If you're not using one of the default boards (pico, pico_w, pico2, or pico2_w), you'll need to create a new build directory for your board - you can do this with this command (replace `$board` with the board you are using):


People might not realise that $board actually appears twice, so perhaps "replace $board with..." should be replaced with "replace both instances of $board with..." ?

lurch · 2025-06-19T15:06:33Z

README.md

+### Prerequisites
+#### Windows
+
+If you're on Windows, it is **strongly recommended** to use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and then follow the [Linux instructions](#linux) inside that. You should also install [usbipd](https://github.com/dorssel/usbipd-win) to access USB devices inside WSL2 (see the docs there for instructions).


Interesting - in the past we explicitly told people that WSL wasn't supported 😂

lurch · 2025-06-19T15:11:24Z

README.md

+* `screen -S minicom` - open a new terminal called `minicom`
+* Ctrl+A then D - detach from the current terminal
+* `screen -r minicom` - re-attach to an existing terminal called `minicom`
+* `screen -ls` - list existing terminals


Like you've done for gdb above, it might be nice to link to additional screen documentation here.

will-v-pi added 2 commits June 4, 2025 17:58

Switch to using Ninja for pico-examples build

b08472b

Also build for W picos as well

Add readme

b1ac75d

Adds some simple command line instructions, along with basic setup instructions for other OSes that can't use this script

will-v-pi requested a review from lurch June 6, 2025 14:13

peterharperuk approved these changes Jun 6, 2025

View reviewed changes

kilograham reviewed Jun 6, 2025

View reviewed changes

README.md Show resolved Hide resolved

kilograham requested changes Jun 6, 2025

View reviewed changes

kilograham reviewed Jun 6, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

lurch reviewed Jun 7, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

will-v-pi added 2 commits June 10, 2025 10:23

Review fixups

a31831e

Add useful GDB commands

781cbec

will-v-pi requested a review from kilograham June 11, 2025 08:42

kilograham approved these changes Jun 18, 2025

View reviewed changes

will-v-pi merged commit 7e995b4 into master Jun 18, 2025

will-v-pi deleted the add-readme branch June 18, 2025 14:26

lurch reviewed Jun 19, 2025

View reviewed changes


		For more details on debugging with GDB, see the [GDB docs](https://sourceware.org/gdb/current/onlinedocs/gdb.html/)

		## Multiple Terminals


		Depending on the board you're using (eg pico2), replace `build_pico` with the relevant build directory (eg `build_pico2`) in the following commands.

		> If you're not using one of the default boards (pico, pico_w, pico2, or pico2_w), you'll need to create a new build directory for your board - you can do this with this command (replace `$board` with the board you are using):

Switch to Ninja and add README #53

Switch to Ninja and add README #53

Uh oh!

Conversation

will-v-pi commented Jun 6, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lurch commented Jun 7, 2025

Uh oh!

will-v-pi commented Jun 9, 2025

Uh oh!

lurch commented Jun 9, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!