README.md
1# Bazel build
2
3## Using the Pico SDK in a Bazel project.
4
5### Add pico-sdk as a dependency
6First, in your `MODULE.bazel` file, add a dependency on the Pico SDK and
7`rules_cc`:
8```python
9bazel_dep(name = "pico-sdk", version = "2.1.0")
10```
11
12### Register toolchains
13These toolchains tell Bazel how to compile for ARM cores. Add the following
14to the `MODULE.bazel` for your project:
15```python
16register_toolchains(
17 "@pico-sdk//bazel/toolchain:linux-x86_64-rp2040",
18 "@pico-sdk//bazel/toolchain:linux-x86_64-rp2350",
19 "@pico-sdk//bazel/toolchain:win-x86_64-rp2040",
20 "@pico-sdk//bazel/toolchain:win-x86_64-rp2350",
21 "@pico-sdk//bazel/toolchain:mac-x86_64-rp2040",
22 "@pico-sdk//bazel/toolchain:mac-x86_64-rp2350",
23 "@pico-sdk//bazel/toolchain:mac-aarch64-rp2040",
24 "@pico-sdk//bazel/toolchain:mac-aarch64-rp2350",
25)
26```
27
28### Ready to build!
29You're now ready to start building Pico Projects in Bazel! When building,
30don't forget to specify `--platforms` so Bazel knows you're targeting the
31Raspberry Pi Pico:
32```console
33$ bazelisk build --platforms=@pico-sdk//bazel/platform:rp2040 //...
34```
35
36## SDK configuration
37An exhaustive list of build system configuration options is available in
38`//bazel/config:BUILD.bazel`.
39
40### Selecting a different board
41A different board can be selected specifying `--@pico-sdk//bazel/config:PICO_BOARD`:
42```console
43$ bazelisk build --platforms=//bazel/platform:rp2040 --@pico-sdk//bazel/config:PICO_BOARD=pico_w //...
44```
45
46If you have a bespoke board definition, you can configure the Pico SDK to use it
47by pointing `--@pico-sdk//bazel/config:PICO_CONFIG_HEADER` to a `cc_library`
48that defines `PICO_BOARD` and either a `PICO_CONFIG_HEADER` define or a
49`pico/config_autogen.h` header. Make sure any required `includes`, `hdrs`, and
50`deps` are also provided.
51
52## Generating UF2 firmware images
53Creation of UF2 images can be done as explicit build steps on a per-binary
54rule basis, or through an aspect. Running a wildcard build with the
55`pico_uf2_aspect` enabled is the easiest way to create a UF2 for every ELF
56firmware image.
57
58```console
59$ bazelisk build --platforms=@pico-sdk//bazel/platform:rp2040 \
60 --aspects @pico-sdk//tools:uf2_aspect.bzl%pico_uf2_aspect \
61 --output_groups=+pico_uf2_files \
62 //...
63```
64
65## Building the Pico SDK itself
66
67### First time setup
68You'll need Bazel (v7.0.0 or higher) or Bazelisk (a self-updating Bazel
69launcher) to build the Pico SDK.
70
71We strongly recommend you set up
72[Bazelisk](https://bazel.build/install/bazelisk).
73
74You will also need a working compiler configured if you wish to build Picotool
75or pioasm.
76
77* Linux: `sudo apt-get install build-essential` or similar.
78* macOS: `xcode-select --install`
79* Windows: [Install MSVC](https://visualstudio.microsoft.com/vs/features/cplusplus/)
80
81### Building
82To build all of the Pico SDK, run the following command:
83```console
84$ bazelisk build --platforms=//bazel/platform:rp2040 //...
85```
86
87## Known issues and limitations
88The Bazel build for the Pico SDK is relatively new, but most features and
89configuration options available in the CMake build are also available in Bazel.
90You are welcome and encouraged to file issues for any problems and limitations
91you encounter along the way.
92
93Currently, the following features are not supported:
94
95* Pico W wireless libraries work, but may not have complete feature parity with
96 the CMake build.
97* Bazel does not yet provide RISC-V support for Pico 2/RP2350.
98* The pioasm parser cannot be built from source via Bazel.
99* Windows MSVC wildcard build (`bazel build //...`) does not work when targeting
100 host.
101
102## Contributing
103When making changes to the Bazel build, please run the Bazel validation script
104to ensure all supported configurations build properly:
105
106```console
107$ ./tools/run_all_bazel_checks.py
108```
109
110If you need to check against a local version of Picotool, you can run the script
111with `--picotool-dir`:
112
113```console
114$ ./tools/run_all_bazel_checks.py --picotool-dir=/path/to/picotool
115```
116