Skip to content

Commit a852c4f

Browse files
will-v-piwill-v-pi
committed
Separate out BUILDING.md
Move build & install instructions into separate file, liked from the main readme
1 parent 2b555ad commit a852c4f

File tree

2 files changed

+105
-102
lines changed

2 files changed

+105
-102
lines changed

‎BUILDING.md

+99
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+
### 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+
## 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

+6-102
Original file line numberDiff line numberDiff line change
@@ -1,109 +1,7 @@
1-
## Building
2-
3-
> If you don't need to build picotool yourself, you can find pre-built binaries for Windows, macOS, and Linux in the [pico-sdk-tools](https://github.com/raspberrypi/pico-sdk-tools/releases) repository
4-
5-
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.
6-
7-
```console
8-
git submodule update --init lib/mbedtls
9-
```
10-
11-
You also need to install `libusb-1.0`.
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-
> 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.
22-
23-
Then simply build like a normal CMake project:
24-
25-
```console
26-
mkdir build
27-
cd build
28-
cmake ..
29-
make
30-
```
31-
32-
On Linux you can add udev rules in order to run picotool without sudo:
33-
34-
```console
35-
sudo cp udev/99-picotool.rules /etc/udev/rules.d/
36-
```
37-
38-
### Windows
39-
40-
##### For Windows without MinGW
41-
42-
Download libUSB from here https://libusb.info/
43-
44-
set LIBUSB_ROOT environment variable to the install directory.
45-
```console
46-
mkdir build
47-
cd build
48-
cmake -G "NMake Makefiles" ..
49-
nmake
50-
```
51-
52-
##### For Windows with MinGW in WSL
53-
54-
Download libUSB from here https://libusb.info/
55-
56-
set LIBUSB_ROOT environment variable to the install directory.
57-
58-
```console
59-
mkdir build
60-
cd build
61-
cmake ..
62-
make
63-
```
64-
65-
##### For Windows with MinGW in MSYS2:
66-
67-
No need to download libusb separately or set `LIBUSB_ROOT`.
68-
69-
```console
70-
pacman -S $MINGW_PACKAGE_PREFIX-{toolchain,cmake,libusb}
71-
mkdir build
72-
cd build
73-
cmake .. -DCMAKE_INSTALL_PREFIX=$MINGW_PREFIX
74-
cmake --build .
75-
```
76-
77-
## Usage by the Raspberry Pi Pico SDK
78-
79-
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.
80-
81-
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.
82-
83-
> On some Linux systems, the `~/.local` prefix may be used for an install without `sudo`; from your build directory simply run
84-
> ```console
85-
> cmake -DCMAKE_INSTALL_PREFIX=~/.local ..
86-
> make install
87-
> ```
88-
> This will only work if `~/.local` is included in your `PATH`
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
100-
1011
## Overview
1022

1033
`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`).
1044

105-
Note for additional documentation see https://rptl.io/pico-get-started
106-
1075
```
1086
$ picotool help
1097
PICOTOOL:
@@ -157,6 +55,12 @@ Use "picotool help <cmd>" for more info
15755

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

58+
## Building & Installing
59+
60+
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 unzipped that directory to `$PICOTOOL_LOC` (with the actual picotool executable at `$PICOTOOL_LOC/picotool/picotool`), you can point the Pico SDK at this binary by setting the `picotool_DIR` environment variable to `$PICOTOOL_LOC/picotool`, or by passing `-Dpicotool_DIR=$PICOTOOL_LOC/picotool` to your `cmake` command or setting it in your `CMakeLists.txt` file.
61+
62+
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.**
63+
16064
## info
16165

16266
The is _Binary Information_ support in the SDK which allows for easily storing compact information that `picotool`

0 commit comments

Comments
 (0)