[draft] add README.md, move .bazelrc to example.bazelrc to keep flags straight

.github/workflows/examples-bzlmod-build.yml

@@ -0,0 +1,28 @@
+name: Build bzlmod example
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+
+jobs:
+  build:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: linux-amd64
+            os: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Bazelisk
+        uses: bazelbuild/setup-bazelisk@v3
+
+      - name: Build example target
+        run: bazel build //:main
+        working-directory: examples/bzlmod
+        shell: bash

examples/bzlmod/MODULE.bazel

@@ -1,17 +1,20 @@
 module(name = "example")
 
-bazel_dep(name = "rules_cc", version = "0.0.9")
+bazel_dep(name = "rules_cc", version = "0.2.8")
 
-# "@toolchains_buildbuddy" is the module in the Bazel registry
 bazel_dep(name = "toolchains_buildbuddy")
 local_path_override(
     module_name = "toolchains_buildbuddy",
     path = "../../",
 )
 
 # The module provides an extension named "buildbuddy".
-# The extension creates a repository named "@buildbuddy_toolchain".
+# The extension creates a repository named "@toolchains_buildbuddy".
 buildbuddy = use_extension("@toolchains_buildbuddy//:extensions.bzl", "buildbuddy")
+register_toolchains(
+    "@toolchains_buildbuddy//toolchains/cc:ubuntu_gcc_x86_64",
+    "@toolchains_buildbuddy//toolchains/cc:ubuntu_gcc_arm64",
+)
 
 # Example customizations (all optional):
 #

examples/bzlmod/README.md

@@ -0,0 +1,41 @@
+# Building a C++ binary with the BuildBuddy Toolchain
+
+## Build locally, send build events to BuildBuddy UI
+
+```
+bazel build //:main \
+    --bes_results_url=https://app.buildbuddy.io/invocation/ \
+    --bes_backend=grpcs://remote.buildbuddy.io \
+    --experimental_platform_in_output_dir
+```
+
+## Create a BuildBuddy API key for Remote Build Execution (RBE)
+1. Login to or sign up for your [BuildBuddy account](https://app.buildbuddy.io/).
+2. Visit the [quickstart page](https://app.buildbuddy.io/docs/setup/), check "Enable remote execution", and copy your API key.
+3. Set a `BUILDBUDDY_API_KEY` environment variable.
+
+## Build remotely for Linux x86_64
+
+```
+bazel build //:main \
+    --bes_results_url=https://app.buildbuddy.io/invocation/ \
+    --bes_backend=grpcs://remote.buildbuddy.io \
+    --remote_executor=grpcs://remote.buildbuddy.io \
+    --platforms=@toolchains_buildbuddy//platforms:linux_x86_64 \
+    --extra_execution_platforms=@toolchains_buildbuddy//platforms:linux_x86_64 \
+    --experimental_platform_in_output_dir \
+    --remote_header="x-buildbuddy-api-key=${BUILDBUDDY_API_KEY}"
+```
+
+## Build remotely for Linux arm64
+
+```
+bazel build //:main \
+    --bes_results_url=https://app.buildbuddy.io/invocation/ \
+    --bes_backend=grpcs://remote.buildbuddy.io \
+    --remote_executor=grpcs://remote.buildbuddy.io \
+    --platforms=@toolchains_buildbuddy//platforms:linux_arm64 \
+    --extra_execution_platforms=@toolchains_buildbuddy//platforms:linux_arm64 \
+    --experimental_platform_in_output_dir \
+    --remote_header="x-buildbuddy-api-key=${BUILDBUDDY_API_KEY}"
+```