Skip to content

Commit 6039f63

Browse files
will-v-piwill-v-pi
authored
Move build & install instructions into separate file (#146)
* Move build & install instructions into separate file, linked from the main README.md * Add note about pico-sdk-tools * General fixup of BUILDING.md and README.md
1 parent e6376e1 commit 6039f63

File tree

2 files changed

+108
-101
lines changed

2 files changed

+108
-101
lines changed

‎BUILDING.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
## Building
2+
3+
You need to set PICO_SDK_PATH in the environment, or pass it to cmake with `-DPICO_SDK_PATH=/path/to/pico-sdk`. To use features such as signing or hashing, you will need to make sure the mbedtls submodule in the SDK is checked out - this can be done by running this from your SDK directory.
4+
5+
```console
6+
git submodule update --init lib/mbedtls
7+
```
8+
9+
You also need to install `libusb-1.0` if you want to use the USB functionality.
10+
11+
> If libusb-1.0 is not installed, picotool still builds, but it omits all options that deal with managing a pico via USB (load, save, erase, verify, reboot). Builds that do not include USB support can be recognized because these commands won't appear in the output of the help command. The build output message 'libUSB is not found - no USB support will be built' also appears in the build logs.
12+
13+
### Linux / macOS
14+
15+
Use your favorite package tool to install dependencies. For example, on Ubuntu:
16+
17+
```console
18+
sudo apt install build-essential pkg-config libusb-1.0-0-dev cmake
19+
```
20+
21+
Then simply build like a normal CMake project:
22+
23+
```console
24+
mkdir build
25+
cd build
26+
cmake ..
27+
make
28+
```
29+
30+
On Linux you can add udev rules in order to run picotool without sudo:
31+
32+
```console
33+
sudo cp udev/99-picotool.rules /etc/udev/rules.d/
34+
```
35+
36+
### Windows
37+
38+
##### For Windows without MinGW
39+
40+
Download libUSB from here https://libusb.info/
41+
42+
Set LIBUSB_ROOT environment variable to the install directory.
43+
```console
44+
mkdir build
45+
cd build
46+
cmake -G "NMake Makefiles" ..
47+
nmake
48+
```
49+
50+
##### For Windows with MinGW in WSL
51+
52+
Download libUSB from here https://libusb.info/
53+
54+
Set LIBUSB_ROOT environment variable to the install directory.
55+
56+
```console
57+
mkdir build
58+
cd build
59+
cmake ..
60+
make
61+
```
62+
63+
##### For Windows with MinGW in MSYS2:
64+
65+
No need to download libusb separately or set `LIBUSB_ROOT`.
66+
67+
```console
68+
pacman -S $MINGW_PACKAGE_PREFIX-{toolchain,cmake,libusb}
69+
mkdir build
70+
cd build
71+
cmake .. -DCMAKE_INSTALL_PREFIX=$MINGW_PREFIX
72+
cmake --build .
73+
```
74+
75+
## Installing (so the Pico SDK can find it)
76+
77+
The Raspberry Pi Pico SDK ([pico-sdk](https://github.com/raspberrypi/pico-sdk)) version 2.0.0 and above uses `picotool` to do the ELF-to-UF2 conversion previously handled by the `elf2uf2` tool in the SDK. The SDK also uses `picotool` to hash and sign binaries.
78+
79+
Whilst the SDK can download picotool on its own per project, if you have multiple projects or build configurations, it is preferable to install a single copy of `picotool` locally. This can be done most simply with `make install` or `cmake --install .`, using `sudo` if required; the SDK will use this installed version by default.
80+
81+
> On some Linux systems, the `~/.local` prefix may be used for an install without `sudo`; from your build directory simply run
82+
> ```console
83+
> cmake -DCMAKE_INSTALL_PREFIX=~/.local ..
84+
> make install
85+
> ```
86+
> This will only work if `~/.local/bin` is included in your `PATH`
87+
88+
### Custom Path Installation (eg if you can't use `sudo`)
89+
90+
Alternatively, you can install to a custom path via:
91+
92+
```console
93+
cmake -DCMAKE_INSTALL_PREFIX=$MY_INSTALL_DIR -DPICOTOOL_FLAT_INSTALL=1 ..
94+
make install
95+
```
96+
97+
In order for the SDK to find `picotool` in this custom folder, you will usually need to set the `picotool_DIR` variable in your project. This can be achieved either by setting the `picotool_DIR` environment variable to `$MY_INSTALL_DIR/picotool`, by passing `-Dpicotool_DIR=$MY_INSTALL_DIR/picotool` to your `cmake` command, or by adding `set(picotool_DIR $MY_INSTALL_DIR/picotool)` to your CMakeLists.txt file.
98+
99+
> See the [find_package documentation](https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure) for more details

‎README.md‎

Lines changed: 9 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,3 @@
1-
## Building
2-
3-
You need to set PICO_SDK_PATH in the environment, or pass it to cmake with `-DPICO_SDK_PATH=/path/to/pico-sdk`. To use features such as signing or hashing, you will need to make sure the mbedtls submodule in the SDK is checked out - this can be done by running this from your SDK directory.
4-
5-
```console
6-
git submodule update --init lib/mbedtls
7-
```
8-
9-
You also need to install `libusb-1.0`.
10-
11-
### Linux / macOS
12-
13-
Use your favorite package tool to install dependencies. For example, on Ubuntu:
14-
15-
```console
16-
sudo apt install build-essential pkg-config libusb-1.0-0-dev cmake
17-
```
18-
19-
> If libusb-1.0-0-dev is not installed, picotool still builds, but it omits all options that deal with managing a pico via USB (load, save, erase, verify, reboot). Builds that do not include USB support can be recognized because these commands also do not appear in the help command. The build output message 'libUSB is not found - no USB support will be built' also appears in the build logs.
20-
21-
Then simply build like a normal CMake project:
22-
23-
```console
24-
mkdir build
25-
cd build
26-
cmake ..
27-
make
28-
```
29-
30-
On Linux you can add udev rules in order to run picotool without sudo:
31-
32-
```console
33-
sudo cp udev/99-picotool.rules /etc/udev/rules.d/
34-
```
35-
36-
### Windows
37-
38-
##### For Windows without MinGW
39-
40-
Download libUSB from here https://libusb.info/
41-
42-
set LIBUSB_ROOT environment variable to the install directory.
43-
```console
44-
mkdir build
45-
cd build
46-
cmake -G "NMake Makefiles" ..
47-
nmake
48-
```
49-
50-
##### For Windows with MinGW in WSL
51-
52-
Download libUSB from here https://libusb.info/
53-
54-
set LIBUSB_ROOT environment variable to the install directory.
55-
56-
```console
57-
mkdir build
58-
cd build
59-
cmake ..
60-
make
61-
```
62-
63-
##### For Windows with MinGW in MSYS2:
64-
65-
No need to download libusb separately or set `LIBUSB_ROOT`.
66-
67-
```console
68-
pacman -S $MINGW_PACKAGE_PREFIX-{toolchain,cmake,libusb}
69-
mkdir build
70-
cd build
71-
cmake .. -DCMAKE_INSTALL_PREFIX=$MINGW_PREFIX
72-
cmake --build .
73-
```
74-
75-
## Usage by the Raspberry Pi Pico SDK
76-
77-
The Raspberry Pi Pico SDK ([pico-sdk](https://github.com/raspberrypi/pico-sdk)) version 2.0.0 and above uses `picotool` to do the ELF-to-UF2 conversion previously handled by the `elf2uf2` tool in the SDK. The SDK also uses `picotool` to hash and sign binaries.
78-
79-
Whilst the SDK can download picotool on its own per project, if you have multiple projects or build configurations, it is preferable to install a single copy of `picotool` locally. This can be done most simply with `make install` or `cmake --install .`, using `sudo` if required; the SDK will use this installed version by default.
80-
81-
> On some Linux systems, the `~/.local` prefix may be used for an install without `sudo`; from your build directory simply run
82-
> ```console
83-
> cmake -DCMAKE_INSTALL_PREFIX=~/.local ..
84-
> make install
85-
> ```
86-
> This will only work if `~/.local/bin` is included in your `PATH`
87-
88-
Alternatively, you can install to a custom path via:
89-
90-
```console
91-
cmake -DCMAKE_INSTALL_PREFIX=$MY_INSTALL_DIR -DPICOTOOL_FLAT_INSTALL=1 ..
92-
make install
93-
```
94-
95-
In order for the SDK to find `picotool` in this custom folder, you will usually need to set the `picotool_DIR` variable in your project. This can be achieved either by setting the `picotool_DIR` environment variable to `$MY_INSTALL_DIR/picotool`, by passing `-Dpicotool_DIR=$MY_INSTALL_DIR/picotool` to your `cmake` command, or by adding `set(picotool_DIR $MY_INSTALL_DIR/picotool)` to your CMakeLists.txt file.
96-
97-
> See the [find_package documentation](https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure) for more details
98-
991
## Overview
1002

1013
`picotool` is a tool for working with RP2040/RP2350 binaries, and interacting with RP2040/RP2350 devices when they are in BOOTSEL mode. (As of version 1.1 of `picotool` it is also possible to interact with devices that are not in BOOTSEL mode, but are using USB stdio support from the Raspberry Pi Pico SDK by using the `-f` argument of `picotool`).
@@ -155,6 +57,12 @@ Use "picotool help <cmd>" for more info
15557

15658
Note commands that aren't acting on files require a device in BOOTSEL mode to be connected.
15759

60+
## Building & Installing
61+
62+
If you don't want to build picotool yourself, you can find pre-built executables for Windows, macOS, and Linux in the [pico-sdk-tools](https://github.com/raspberrypi/pico-sdk-tools/releases) repository. Assuming you've extracted that archive to `<extract_location>` (with the actual picotool executable at `<extract_location>/picotool/picotool`), you can point the Pico SDK at this binary by setting the `picotool_DIR` environment variable to `<extract_location>/picotool`, or by passing `-Dpicotool_DIR=<extract_location>/picotool` to your `cmake` command or setting it in your `CMakeLists.txt` file.
63+
64+
If you do wish to build picotool yourself, then see [Building](BUILDING.md#building) for build instructions. For the Pico SDK to find your picotool you will need to install it, the simplest way being to run `cmake --install .` - see [Installing](BUILDING.md#installing-so-the-pico-sdk-can-find-it) for more details and alternatives. **You cannot just copy the binary into your `PATH`, else the Pico SDK will not be able to locate it.**
65+
15866
## info
15967

16068
There is _Binary Information_ support in the SDK which allows for easily storing compact information that `picotool`
@@ -668,7 +576,7 @@ OPTIONS:
668576

669577
## encrypt
670578

671-
`encrypt` allows you to encrypt and sign a binary for use on the RP2350. By default, it will sign the encrypted binary, but that can be configured similarly to `picotool sign`.
579+
`encrypt` allows you to encrypt and sign a binary for use on the RP2350. By default, it will sign the encrypted binary, but that can be configured similarly to `picotool seal`.
672580

673581
The encrypted binary will have the following structure:
674582

@@ -942,10 +850,10 @@ These commands will set/get specific rows of OTP. By default, they will write/re
942850

943851
### load
944852

945-
This command allows loading of a range of OTP rows onto the device. The source can be a binary file, or a JSON file such as the one output by `picotool sign`. The schema for this JSON file is [here](json/schemas/otp-schema.json)
853+
This command allows loading of a range of OTP rows onto the device. The source can be a binary file, or a JSON file such as the one output by `picotool seal`. The schema for this JSON file is [here](json/schemas/otp-schema.json)
946854
For example, if you wish to sign a binary and then test secure boot with it, you can run the following set of commands:
947855
```text
948-
$ picotool sign hello_world.elf hello_world.signed.elf private.pem otp.json
856+
$ picotool seal --sign hello_world.elf hello_world.signed.elf private.pem otp.json
949857
$ picotool load hello_world.signed.elf
950858
$ picotool otp load otp.json
951859
$ picotool reboot

0 commit comments

Comments
 (0)