Introduce initial Bazel build (#1705)

* Build boot_stage2 with Bazel

Introduces the initial foundations of a Bazel build, including a
toolchain, critical generated headers, platform patterns, and enough
BUILD files to build boot_stage2.

* Bazel libraries to support picotool

* Move SDK defines to toolchain

* Switch to `archive_override` in MODULE.bazel

Uses archive_override where applicable to allow transitive bzlmod deps
to propagate.

* Multiplatform objcopy selection in Bazel build

Makes an objcopy alias that redirects to the objcopy tool for the
current exec platform, which allows boot_stage2 to build on Linux,
macOS, and Windows.

* Generate Bazel build files

Adds initial set of generated Bazel build files. Note that these do not
yet build, as dependency cycles are present.

* Fix dependency cycles in Bazel build

Fixes many dependency cycles, some were unintentionally created by the
build file generator, others are true dependency cycles that require
manual workarounds.

* Silence warning in pico_stdio Bazel build

Silences a stray warning in the Bazel build.

* Fix wildcard Bazel build

This makes `bazel build //...` succeed, and also prevents the fetching
of toolchains that aren't compatible with the current execution
environment (i.e. Windows computers will no longer try to download macOS
toolchains).

* Get the SDK working

Finishes out the remainder of the work required to successfully compile
a working blinky example.

* Fix UART stdio dependencies in Bazel build

Fixes some dependencies around pico_stdlib so that pico_stdlib links
properly and UART stdio works.

* Add linux support to Bazel build

* Get Bazel deps from registry

Adds external an external registry for resolving Bazel module
dependencies.

* Fix host configuration for picotool

Provides the appropriate defines for host builds to support the picotool
build.

* Remove -ffreestanding from Bazel toolchain

The -ffreestanding toolchain flag is quite strict, so remove it from the
Bazel toolchain.

* Remove unused .bzl file

* Reduce Bazel compiler flags

Cuts out most of the Bazel toolchain flags and only specifies the
bare-minimum set of flags. Also, adds wrapper linker flags for functions
the SDK wraps.

* Get USB serial working

Adds initial TinyUSB support and enough integration to get USB serial
working.

* Remove "Generated build file"

Removes comments that indicates BUILD.bazel files are generated. This
was used during initial bringup to indicate hand-crafted vs
automatically generated BUILD.bazel files.

* Do not build USB libraries unless configured

Prevents USB libraries from being built unless the build is properly
configured to use them.

* Switch to rules_cc toolchains

Moves toolchain configuration to use the new rules in rules_cc.

* Minor cleanup in parse_version.py

Cleans up trailing whitespace and runs the black formatter on
parse_version.py.

* Simplify constraint dimensions in Bazel build

Consolidates the class/chip constraint settings to be a single
constraint_setting with a config_setting that represents the rp2 class.

* Update pin of rules_cc in Bazel build

Includes a necessary fix for the target_compatible_with expression in
the cc_toolchain to work as intended.

* Move toolchains from pico.bzl to BUILD.bazel

Moves toolchain definitions from pico.bzl to BUILD.bazel to make them
easier to find and read.

* Run buildifier on Bazel build files

Fix trivial formatting issues by running buildifier on all BUILD.bazel
files.

* Make objcopy rule

Makes a simple objcopy rule to remove direct references to the ARM
toolchains.

* Fix link flags in Bazel build

Critical flags were not being applied to link steps. This applies -mcpu
and -mthumb to the link steps to make the produced binaries work again.

* Mention missing host build support

* Fix various Bazel library rules

* pico_bit_ops was incomplete.
* pico_double and pico_float were trying to link in the "none"
  implementation.

* Extend Bazel build documentation

Improves documentation and comments across the Bazel build.

* Clean up auxilary tools in Bazel build

Switches genrules to use skylib rules to simplify things. Reworks
version header generation to use the Bazel module version rather than
parsing CMake.

* Update boot_stage2 Bazel build file

Moves `includes` to be enumerated on the correct library.

* Add WORKSPACE version fallback

WORKSPACE Bazel projects don't support querying module version, so add a
fallback of '0.0.1-WORKSPACE' so the build can succeed.

* Fix malloc handling in Bazel build

* Fix Bazel dependency cycle in pico_malloc

* Prevent malloc from being linked into boot_stage2

Prevents Bazel from ever trying to link malloc into the boot_stage2
binary.

* Remove custom bootloader platform

A dedicated boot_stage2 platform introduces a lot of complexity that
needs to be more thought-through.

.bazelrc

@@ -0,0 +1,6 @@
+# Required for new toolchain resolution API.
+build --incompatible_enable_cc_toolchain_resolution
+build --@rules_cc//cc/toolchains:experimental_enable_rule_based_toolchains
+
+# Produce useful output when the build fails.
+common --verbose_failures

.bazelversion

@@ -0,0 +1 @@
+7.0.2

.gitignore

@@ -3,3 +3,8 @@
 cmake-*
 .DS_Store
 build
+
+bazel-*
+
+# Ignore until https://github.com/bazelbuild/bazel/issues/20369 is fixed.
+MODULE.bazel.lock

MODULE.bazel

@@ -0,0 +1,71 @@
+module(name = "pico-sdk", version = "1.6.0-rc1")
+
+bazel_dep(name = "platforms", version = "0.0.8")
+
+bazel_dep(name = "bazel_skylib", version = "1.6.1")
+
+# 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=",
+)
+
+http_archive = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "arm_gcc_linux-x86_64",
+    url = "https://developer.arm.com/-/media/Files/downloads/gnu/13.2.rel1/binrel/arm-gnu-toolchain-13.2.rel1-x86_64-arm-none-eabi.tar.xz",
+    strip_prefix = "arm-gnu-toolchain-13.2.Rel1-x86_64-arm-none-eabi",
+    build_file = "//bazel/toolchain:gcc_arm_none_eabi.BUILD",
+    sha256 = "6cd1bbc1d9ae57312bcd169ae283153a9572bd6a8e4eeae2fedfbc33b115fdbb",
+)
+
+http_archive(
+    name = "arm_gcc_win-x86_64",
+    url = "https://developer.arm.com/-/media/Files/downloads/gnu/13.2.rel1/binrel/arm-gnu-toolchain-13.2.rel1-mingw-w64-i686-arm-none-eabi.zip",
+    strip_prefix = "arm-gnu-toolchain-13.2.Rel1-mingw-w64-i686-arm-none-eabi",
+    build_file = "//bazel/toolchain:gcc_arm_none_eabi.BUILD",
+    sha256 = "51d933f00578aa28016c5e3c84f94403274ea7915539f8e56c13e2196437d18f",
+)
+
+http_archive(
+    name = "arm_gcc_mac-x86_64",
+    url = "https://developer.arm.com/-/media/Files/downloads/gnu/13.2.rel1/binrel/arm-gnu-toolchain-13.2.rel1-darwin-x86_64-arm-none-eabi.tar.xz",
+    strip_prefix = "arm-gnu-toolchain-13.2.Rel1-darwin-x86_64-arm-none-eabi",
+    build_file = "//bazel/toolchain:gcc_arm_none_eabi.BUILD",
+    sha256 = "075faa4f3e8eb45e59144858202351a28706f54a6ec17eedd88c9fb9412372cc",
+)
+
+http_archive(
+    name = "arm_gcc_mac-aarch64",
+    url = "https://developer.arm.com/-/media/Files/downloads/gnu/13.2.rel1/binrel/arm-gnu-toolchain-13.2.rel1-darwin-arm64-arm-none-eabi.tar.xz",
+    strip_prefix = "arm-gnu-toolchain-13.2.Rel1-darwin-arm64-arm-none-eabi",
+    build_file = "//bazel/toolchain:gcc_arm_none_eabi.BUILD",
+    sha256 = "39c44f8af42695b7b871df42e346c09fee670ea8dfc11f17083e296ea2b0d279",
+)
+
+# TODO: Provide tinyusb as a proper Bazel module.
+http_archive(
+    name = "tinyusb",
+    url = "https://github.com/hathach/tinyusb/archive/86c416d4c0fb38432460b3e11b08b9de76941bf5.zip",
+    strip_prefix = "tinyusb-86c416d4c0fb38432460b3e11b08b9de76941bf5",
+    build_file = "//src/rp2_common/tinyusb:tinyusb.BUILD",
+    sha256 = "ac57109bba00d26ffa33312d5f334990ec9a9a4d82bf890ed8b825b4610d1da2",
+)
+
+register_toolchains(
+    "//bazel/toolchain:arm_gcc_linux-x86_64",
+    "//bazel/toolchain:arm_gcc_win-x86_64",
+    "//bazel/toolchain:arm_gcc_mac-x86_64",
+    "//bazel/toolchain:arm_gcc_mac-aarch64",
+)

bazel/BUILD.bazel

@@ -0,0 +1,34 @@
+package(default_visibility = ["//visibility:public"])
+
+py_binary(
+    name = "generate_version_header",
+    srcs = ["generate_version_header.py"],
+    visibility = ["//:__subpackages__"],
+)
+
+# This isn't actually generated, it just uses the same name
+# to make it show up easier in searches.
+#
+# Rather than generating lists of headers to match CMake, the Bazel build
+# opts to have a static header that transitively include two known headers.
+# By default, empty header files are included, and users/platforms are expected
+# to specify an appropriate `cc_library` to replace them.
+#
+# You tell bazel which `cc_library` provides the respective headers by
+# configuring these `label_flag`s:
+#
+#     # Specify the library that provides "pico_config_extra_headers.h"
+#     --@pico-sdk//bazel/config:pico_config_extra_headers=//my_proj:my_custom_headers
+#
+#     # Specify the library that provides "pico_config_platform_headers.h"
+#     --@pico-sdk//bazel/config:pico_config_platform_headers=//my_proj:my_custom_platform_headers
+cc_library(
+    name = "generate_config_header",
+    hdrs = ["include/pico/config_autogen.h"],
+    includes = ["include"],
+    visibility = ["//:__subpackages__"],
+    deps = [
+        "//bazel/config:pico_config_extra_headers",
+        "//bazel/config:pico_config_platform_headers",
+    ],
+)

bazel/README.md

@@ -0,0 +1,137 @@
+# 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:
+```python
+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:
+```python
+# 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:
+```python
+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:
+```console
+$ 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:
+```python
+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](https://bazel.build/install/bazelisk).
+
+### Building
+To build all of the Pico SDK, run the following command:
+```console
+$ 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.

bazel/config/BUILD.bazel

@@ -0,0 +1,52 @@
+package(default_visibility = ["//visibility:public"])
+
+# This should always point to a cc_library that provides
+# a "pico_config_extra_headers.h".
+label_flag(
+    name = "pico_config_extra_headers",
+    build_setting_default = ":no_extra_headers",
+)
+
+# This should always point to a cc_library that provides
+# a "pico_config_platform_headers.h".
+label_flag(
+    name = "pico_config_platform_headers",
+    build_setting_default = ":no_platform_headers",
+)
+
+# This should always point to a cc_library that defines PICO_CONFIG_HEADER and
+# any other defines that should be applied when building the SDK.
+label_flag(
+    name = "pico_config_header",
+    build_setting_default = "//src/boards:default",
+)
+
+genrule(
+    name = "empty_extra_headers_file",
+    outs = ["generated_include/pico_config_extra_headers.h"],
+    cmd = "echo > $@",
+    cmd_bat = "copy NUL $@",
+    visibility = ["//visibility:private"],
+)
+
+genrule(
+    name = "empty_platform_headers_file",
+    outs = ["generated_include/pico_config_platform_headers.h"],
+    cmd = "echo > $@",
+    cmd_bat = "copy NUL $@",
+    visibility = ["//visibility:private"],
+)
+
+cc_library(
+    name = "no_extra_headers",
+    hdrs = ["generated_include/pico_config_extra_headers.h"],
+    includes = ["generated_include"],
+    visibility = ["//visibility:private"],
+)
+
+cc_library(
+    name = "no_platform_headers",
+    hdrs = ["generated_include/pico_config_platform_headers.h"],
+    includes = ["generated_include"],
+    visibility = ["//visibility:private"],
+)

bazel/constraint/BUILD.bazel

@@ -0,0 +1,58 @@
+package(default_visibility = ["//visibility:public"])
+
+# This constraint represents the dimension that guides the Pico SDK build. This
+# constraint will only ever enumerate specific MCUs (and the host), and does NOT
+# cover the differences from board-to-board.
+constraint_setting(
+    name = "sdk_target",
+    default_constraint_value = "host",
+)
+
+# This constraint value is used to guide the host build.
+constraint_value(
+    name = "host",
+    constraint_setting = ":sdk_target",
+)
+
+# This constraint value is used to guide parts of the build that are specific
+# to the rp2040.
+constraint_value(
+    name = "rp2040",
+    constraint_setting = ":sdk_target",
+)
+
+# This constraint value is used to guide parts of the build that apply to all
+# rp2-class chips.
+config_setting(
+    name = "rp2",
+    constraint_values = [
+        ":rp2040",
+    ],
+)
+
+# This constraint setting guides Bazel's build file evaluation differences
+# across different stdio configurations (e.g. stdio_usb needs TinyUSB).
+constraint_setting(
+    name = "stdio_mode",
+    default_constraint_value = "stdio_uart",
+)
+
+# When this constraint value is active, stdio is built against a hardware UART.
+constraint_value(
+    name = "stdio_uart",
+    constraint_setting = ":stdio_mode",
+)
+
+# When this constraint value is active, stdio is built against TinyUSB-based
+# USB serial.
+constraint_value(
+    name = "stdio_usb",
+    constraint_setting = ":stdio_mode",
+)
+
+# When this constraint value is active, stdio is built against an ARM
+# semihosting library.
+constraint_value(
+    name = "stdio_semihosting",
+    constraint_setting = ":stdio_mode",
+)