Building

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.

git submodule update --init lib/mbedtls

You also need to install libusb-1.0 if you want to use the USB functionality.

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 identified by running picotool version, which will state This version of picotool was compiled without USB support. Some commands are not available.. Additionally, the unsupported commands won't appear in the output of the help command, and if you attempt to execute an invalid command you will get an error message. The build output message libUSB is not found - no USB support will be built also appears in the build logs.

Linux / macOS

Use your favorite package tool to install dependencies. For example, on Ubuntu:

sudo apt install build-essential pkg-config libusb-1.0-0-dev cmake

Then simply build like a normal CMake project:

mkdir build
cd build
cmake ..
make

On Linux you can add udev rules in order to run picotool without sudo:

sudo cp udev/60-picotool.rules /etc/udev/rules.d/

Windows

For Windows without MinGW

Download libUSB from here https://libusb.info/

Set LIBUSB_ROOT environment variable to the install directory.

mkdir build
cd build
cmake -G "NMake Makefiles" ..
nmake

For Windows with MinGW in WSL

Download libUSB from here https://libusb.info/

Set LIBUSB_ROOT environment variable to the install directory.

mkdir build
cd build
cmake ..
make

For Windows with MinGW in MSYS2:

No need to download libusb separately or set LIBUSB_ROOT.

pacman -S $MINGW_PACKAGE_PREFIX-{toolchain,cmake,libusb}
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$MINGW_PREFIX
cmake --build .

Installing (so the Pico SDK can find it)

The Raspberry Pi Pico SDK (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.

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.

On some Linux systems, the ~/.local prefix may be used for an install without sudo; from your build directory simply run

cmake -DCMAKE_INSTALL_PREFIX=~/.local ..
make install

This will only work if ~/.local/bin is included in your PATH

Custom Path Installation (eg if you can't use sudo)

Alternatively, you can install to a custom path via:

cmake -DCMAKE_INSTALL_PREFIX=$MY_INSTALL_DIR -DPICOTOOL_FLAT_INSTALL=1 ..
make install

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.

See the find_package documentation for more details

Customising the build

The picotool build has some CMake variables you can use to customise how the build works, and how picotool functions:

• GENERATE_FIXED_DOCS_WIDTH: By default the width of the output from picotool adjusts to the width of the terminal. Setting this to true fixes the width to 140, which is used when generating the README.
• DEFAULT_BOOTSEL_LED: This can be used to set the default value for the --bootsel-led argument, so picotool always reboots devices to BOOTSEL with that LED used as the activity indicator.
• PICOTOOL_NO_LIBUSB: By default picotool is compiled with USB support if libusb is found. Setting this to true explicitly compiles without USB support, which is used when the Pico SDK builds picotool.
• USE_PRECOMPILED: By default the build uses pre-compiled ELF/BIN files for code that is run on the device (enc_bootloader, xip_ram_perms, and picoboot_flash_id). Setting this to false re-compiles these files instead.

These can all be set by passing -DNAME=VALUE to your cmake command (e.g. -DGENERATE_FIXED_DOCS_WIDTH=true).

Note: when setting PICOTOOL_NO_LIBUSB or USE_PRECOMPILED you should create a new build directory (rather than using an existing build directory), due to the way picotool uses external CMake projects.