1.. _docs-get-started-bazel: 2 3================================== 4Get Started With Pigweed And Bazel 5================================== 6This guide provides a starting point for using Pigweed in a Bazel-based project. 7Bazel is :ref:`the recommended build system <seed-0111>` for new projects using 8Pigweed. 9 10----------- 11Limitations 12----------- 13.. TODO: b/306393519 - Update the MacOS description once that path is verified. 14 15* **Linux**. Your development host must be running Linux. Bazel-based Pigweed 16 projects are not yet supported on Windows. MacOS probably works but is 17 unverified. 18 19----- 20Setup 21----- 22#. `Install Bazel <https://bazel.build/install>`_. 23 24 .. tip:: 25 26 If you want to minimize system-wide installations, first install 27 `Node Version Manager <https://github.com/nvm-sh/nvm>`_ and then 28 install Bazelisk through NPM using ``npm install -g @bazel/bazelisk``. 29 If you use this workflow, remember that Bazel will only be available 30 in the version of Node that's currently activated through NVM. 31 32#. Clone `the project <https://pigweed.googlesource.com/pigweed/quickstart/bazel/+/refs/heads/main>`_: 33 34 .. code-block:: console 35 36 $ git clone --recursive https://pigweed.googlesource.com/pigweed/quickstart/bazel 37 38 .. tip:: 39 40 If you forgot the ``--recursive`` flag when cloning the code, run 41 ``git submodule update --init``. 42 43All subsequent commands that you see in this guide should be run from the 44root directory of your new ``quickstart`` repo. 45 46----------------- 47Build the project 48----------------- 49#. Build the project for :ref:`target-host` and 50 :ref:`target-stm32f429i-disc1`: 51 52 .. code-block:: console 53 54 $ bazel build //... 55 56 You should see output like this: 57 58 .. code-block:: none 59 60 Starting local Bazel server and connecting to it... 61 INFO: Analyzed 7 targets (105 packages loaded, 14022 targets configured). 62 INFO: Found 7 targets... 63 INFO: Elapsed time: 30.705s, Critical Path: 5.55s 64 INFO: 86 processes: 24 internal, 62 linux-sandbox. 65 INFO: Build completed successfully, 86 total actions 66 67Troubleshooting: ``Network is unreachable (connect failed)`` 68============================================================ 69.. _bazelbuild/bazel#2486: https://github.com/bazelbuild/bazel/issues/2486#issuecomment-1870698756 70 71If your build fails and you see a ``Network is unreachable (connect failed)`` 72error, check if you're on an IPv6 network. If you are, try switching to an IPv4 73network. See `bazelbuild/bazel#2486`_. 74 75.. code-block:: console 76 77 bazel build //... 78 Starting local Bazel server and connecting to it... 79 INFO: Repository platforms instantiated at: 80 /home/kayce/sandbox/echo/WORKSPACE:21:13: in <toplevel> 81 Repository rule http_archive defined at: 82 /home/kayce/.cache/bazel/_bazel_kayce/5b77aa1b33d7b7c439479c603973101b/external/bazel_tools/tools/build_defs/repo/http.bzl:372:31: in <toplevel> 83 WARNING: Download from https://mirror.bazel.build/github.com/bazelbuild/platforms/releases/download/0.0.8/platforms-0.0.8.tar.gz failed: class java.net.ConnectException Network is unreachable (connect failed) 84 WARNING: Download from https://github.com/bazelbuild/platforms/releases/download/0.0.8/platforms-0.0.8.tar.gz failed: class java.net.ConnectException Network is unreachable (connect failed) 85 ... 86 87----------------------- 88Run the project locally 89----------------------- 90#. Run the project locally on your Linux development host: 91 92 .. code-block:: console 93 94 bazel run //src:echo 95 96 You should see output like this: 97 98 .. code-block:: none 99 100 INFO: Analyzed target //src:echo (36 packages loaded, 202 targets configured). 101 INFO: Found 1 target... 102 Target //src:echo up-to-date: 103 bazel-bin/src/echo 104 INFO: Elapsed time: 0.899s, Critical Path: 0.03s 105 INFO: 1 process: 1 internal. 106 INFO: Build completed successfully, 1 total action 107 INFO: Running command line: bazel-bin/src/echo 108 109#. Press ``Ctrl`` + ``C`` to stop running the project. 110 111---------------------------------------- 112Flash the project onto a Discovery board 113---------------------------------------- 114If you have an `STM32F429 Discovery <https://www.st.com/stm32f4-discover>`_ 115board, you can run the project on that hardware. 116 117.. note:: 118 119 You don't need this hardware to run the project. Because this project 120 supports the :ref:`target-host` target, you can run everything 121 on your Linux development host. 122 123#. Ensure your udev rules are set up to allow the user running the commands 124 below to access the Discovery Board. For example, you may want to add the 125 following rule as ``/etc/udev/rules.d/99-stm32f329i-disc1.rules``: 126 127 .. code-block:: console 128 129 ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE="664", GROUP="plugdev" 130 131 The user running the commands needs to be in the group ``plugdev``. 132 133#. Connect the Discovery board to your development host with a USB 134 cable. **Use the Mini-B USB port on the Discovery board, not the 135 Micro-B port**. 136 137#. Flash the project to the Discovery board: 138 139 .. code-block:: console 140 141 $ bazel run //tools:flash 142 143 You should see output like this: 144 145 .. code-block:: none 146 147 INFO: Analyzed target //tools:flash (52 packages loaded, 2760 targets configured). 148 INFO: Found 1 target... 149 Target //tools:flash up-to-date: 150 bazel-bin/tools/flash 151 INFO: Elapsed time: 0.559s, Critical Path: 0.04s 152 INFO: 1 process: 1 internal. 153 INFO: Build completed successfully, 1 total action 154 INFO: Running command line: bazel-bin/tools/flash 155 binary Rlocation is: /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/execroot/__main__/bazel-out/k8-fastbuild/bin/src/echo.elf 156 openocd Rlocation is: /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/openocd/bin/openocd 157 openocd config Rlocation is: /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/pigweed/targets/stm32f429i_disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg 158 xPack OpenOCD x86_64 Open On-Chip Debugger 0.11.0+dev (2021-12-07-17:30) 159 Licensed under GNU GPL v2 160 For bug reports, read 161 http://openocd.org/doc/doxygen/bugs.html 162 DEPRECATED! use 'adapter driver' not 'interface' 163 DEPRECATED! use 'adapter serial' not 'hla_serial' 164 Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD 165 srst_only separate srst_nogate srst_open_drain connect_deassert_srst 166 167 Info : clock speed 2000 kHz 168 Info : STLINK V2J25M14 (API v2) VID:PID 0483:374B 169 Info : Target voltage: 2.837377 170 Info : stm32f4x.cpu: Cortex-M4 r0p1 processor detected 171 Info : stm32f4x.cpu: target has 6 breakpoints, 4 watchpoints 172 Info : gdb port disabled 173 Info : Unable to match requested speed 2000 kHz, using 1800 kHz 174 Info : Unable to match requested speed 2000 kHz, using 1800 kHz 175 target halted due to debug-request, current mode: Thread 176 xPSR: 0x01000000 pc: 0x08000708 msp: 0x20030000 177 Info : Unable to match requested speed 8000 kHz, using 4000 kHz 178 Info : Unable to match requested speed 8000 kHz, using 4000 kHz 179 ** Programming Started ** 180 Info : device id = 0x20016419 181 Info : flash size = 2048 kbytes 182 Info : Dual Bank 2048 kiB STM32F42x/43x/469/479 found 183 Info : Padding image section 0 at 0x08000010 with 496 bytes 184 ** Programming Finished ** 185 ** Resetting Target ** 186 Info : Unable to match requested speed 2000 kHz, using 1800 kHz 187 Info : Unable to match requested speed 2000 kHz, using 1800 kHz 188 shutdown command invoked 189 190 191Communicate with the project over serial 192======================================== 193After you've flashed the project onto your Discovery board, your Linux development 194host can communicate with the project over a serial terminal like ``miniterm``. 195 196#. Transmit and receive characters: 197 198 .. code-block:: console 199 200 $ bazel run //tools:miniterm -- /dev/ttyACM0 --filter=debug 201 202 After typing ``hello`` and pressing ``Ctrl`` + ``]`` to exit you should see output 203 like this: 204 205 .. code-block:: none 206 207 INFO: Analyzed target //tools:miniterm (41 packages loaded, 2612 targets configured). 208 INFO: Found 1 target... 209 Target //tools:miniterm up-to-date: 210 bazel-bin/tools/miniterm 211 INFO: Elapsed time: 0.373s, Critical Path: 0.02s 212 INFO: 1 process: 1 internal. 213 INFO: Build completed successfully, 1 total action 214 INFO: Running command line: bazel-bin/tools/miniterm /dev/ttyACM0 '--filter=debug' 215 --- Miniterm on /dev/ttyACM0 115200,8,N,1 --- 216 --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- 217 [TX:'h'] [RX:'h'] h [TX:'e'] [RX:'e'] e [TX:'l'] [RX:'l'] l [TX:'l'] [RX:'l'] l [TX:'o'] [RX:'o'] o 218 --- exit --- 219 220------------------------------ 221Questions? Comments? Feedback? 222------------------------------ 223Please join `our Discord <https://discord.com/invite/M9NSeTA>`_ and talk to us 224in the ``#bazel-build`` channel or `file a bug <https://issues.pigweed.dev>`_. 225