pico-sdk/bazel/README.md

Bazel build

The Bazel build for the Pico SDK is currently community-maintained, and should be considered an experimental work-in-progress. There are missing features, and you may encounter significant breakages with future versions.

You are welcome and encouraged to file issues for any problems you encounter along the way.

Using the Pico SDK in a Bazel project.

Add pico-sdk as a dependency

First, in your MODULE.bazel file, add a dependency on the Pico SDK:

bazel_dep(
  name = "pico-sdk",
  version = "1.6.0-rc1",
)

Second, in the same file you'll need to add an explicit dependency on rules_cc, as it's a special-cased Bazel module:

# Note: rules_cc is special-cased repository; a dependency on rules_cc in a
# module will not ensure that the root Bazel module has that same version of
# rules_cc. For that reason, this primarily acts as a FYI. You'll still need
# to explicitly list this dependency in your own project's MODULE.bazel file.
bazel_dep(name = "rules_cc", version = "0.0.10")

# rules_cc v0.0.10 is not yet cut, so manually pull in the desired version.
# This does not apply to dependent projects, so it needs to be copied to your
# project's MODULE.bazel too.
archive_override(
    module_name = "rules_cc",
    urls = "https://github.com/bazelbuild/rules_cc/archive/1acf5213b6170f1f0133e273cb85ede0e732048f.zip",
    strip_prefix = "rules_cc-1acf5213b6170f1f0133e273cb85ede0e732048f",
    integrity = "sha256-NddP6xi6LzsIHT8bMSVJ2NtoURbN+l3xpjvmIgB6aSg=",
)

Register toolchains

These toolchains tell Bazel how to compile for ARM cores. Add the following to the MODULE.bazel for your project:

register_toolchains(
    "@pico-sdk//bazel/toolchain:arm_gcc_linux-x86_64",
    "@pico-sdk//bazel/toolchain:arm_gcc_win-x86_64",
    "@pico-sdk//bazel/toolchain:arm_gcc_mac-x86_64",
    "@pico-sdk//bazel/toolchain:arm_gcc_mac-aarch64",
)

Enable required .bazelrc flags

To use the toolchains provided by the Pico SDK, you'll need to enable a few new features. In your project's .bazelrc, add the following

# Required for new toolchain resolution API.
build --incompatible_enable_cc_toolchain_resolution
build --@rules_cc//cc/toolchains:experimental_enable_rule_based_toolchains

Ready to build!

You're now ready to start building Pico Projects in Bazel! When building, don't forget to specify --platforms so Bazel knows you're targeting the Raspberry Pi Pico:

$ bazelisk build --platforms=@pico-sdk//bazel/platform:rp2040 //...

SDK configuration [experimental]

These configuration options are a work in progress and may see significant breaking changes in future versions.

Selecting a different board

Currently there are three configurable flags for targeting a different board:

1. pico_config_extra_headers: This should always point to a cc_library that provides a "pico_config_extra_headers.h" header. You can configure this by including a flag like the following in your build invocation:

   --@pico-sdk//bazel/config:pico_config_extra_headers=//path/to:custom_extra_headers
   

2. pico_config_platform_headers: This should always point to a cc_library that provides a "pico_config_platform_headers.h" header.

   --@pico-sdk//bazel/config:pico_config_platform_headers=//path/to:custom_platform_headers
   

3. pico_config_header: This should point to a cc_library that sets all necessary SDK defines. Most notably, PICO_BOARD, PICO_CONFIG_HEADER, PICO_ON_DEVICE, PICO_NO_HARDWARE, and PICO_BUILD. See //src/boards:BUILD.bazel for working examples. Any defines set on this library will propagate to the rest of the Pico SDK. To set this configuration option, pass a flag like the following in your Bazel build invocation:

   --@pico-sdk//bazel/config:pico_config_platform_headers=//path/to:pico_board_config
   

Selecting a stdio mode

To select a different stdio mode, add it to your platform definition. For example:

platform(
    name = "rp2040",
    constraint_values = [
        "@pico-sdk//bazel/constraint:rp2040",
        "@pico-sdk//bazel/constraint:stdio_usb", # Configures stdio_mode.
        "@platforms//cpu:armv6-m",
    ],
)

Building the Pico SDK itself

First time setup

You'll need Bazel (v7.0.0 or higher) or Bazelisk (a self-updating Bazel launcher) to build the Pico SDK.

We strongly recommend you set up Bazelisk.

Building

To build all of the Pico SDK, run the following command:

$ bazelisk build --platforms=//bazel/platform:rp2040 //...

Note: Since the Bazel build does not yet have any cc_binary rules with a main() function, there won't be any binaries to flash on your board. For now, this only builds the SDK as a collection of libraries.

Known issues and limitations

The Bazel build is currently experimental and incomplete. At this time, only the stock Pi Pico board is supported, and the only configuration options are changing the STDIO mode between UART and USB serial.

Keep in mind the following limitations:

• Pico-W is not yet supported.
• Selecting an alternative board is not yet supported.
• Nearly all preexisting CMake configuration options are not yet supported.
• Targeting the host build of the Pico SDK is not yet supported.