diff options
Diffstat (limited to 'docs/get_started/bazel.rst')
| -rw-r--r-- | docs/get_started/bazel.rst | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/docs/get_started/bazel.rst b/docs/get_started/bazel.rst new file mode 100644 index 000000000..68ba18821 --- /dev/null +++ b/docs/get_started/bazel.rst @@ -0,0 +1,217 @@ +.. _docs-get-started-bazel: + +================================== +Get Started With Pigweed And Bazel +================================== +This guide provides a starting point for using Pigweed in a Bazel-based project. +Bazel is :ref:`the recommended build system <seed-0111>` for new projects using +Pigweed. + +----------- +Limitations +----------- +.. TODO: b/306393519 - Update the MacOS description once that path is verified. + +* **Linux**. Your development host must be running Linux. Bazel-based Pigweed + projects are not yet supported on Windows. MacOS probably works but is + unverified. + +----- +Setup +----- +#. `Install Bazel <https://bazel.build/install>`_. + + .. tip:: + + If you want to minimize system-wide installations, first install + `Node Version Manager <https://github.com/nvm-sh/nvm>`_ and then + install Bazelisk through NPM using ``npm install -g @bazel/bazelisk``. + If you use this workflow, remember that Bazel will only be available + in the version of Node that's currently activated through NVM. + +#. Clone `the project <https://pigweed.googlesource.com/example/echo/+/refs/heads/main>`_: + + .. code-block:: console + + $ git clone --recursive https://pigweed.googlesource.com/example/echo + + .. tip:: + + If you forgot the ``--recursive`` flag when cloning the code, run + ``git submodule update --init``. + +All subsequent commands that you see in this guide should be run from the +root directory of your new ``echo`` repo. + +----------------- +Build the project +----------------- +#. Build the project for :ref:`target-host` and + :ref:`target-stm32f429i-disc1`: + + .. code-block:: console + + $ bazel build //... + + You should see output like this: + + .. code-block:: none + + Starting local Bazel server and connecting to it... + INFO: Analyzed 7 targets (101 packages loaded, 17371 targets configured). + INFO: Found 7 targets... + INFO: From Linking src/echo: + /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/gcc_arm_none_eabi_toolchain/bin/../lib/gcc/arm-none-eabi/12.2.1/../../../../arm-none-eabi/bin/ld: /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/gcc_arm_none_eabi_toolchain/bin/../lib/gcc/arm-none-eabi/12.2.1/../../../../arm-none-eabi/lib/thumb/v7e-m/nofp/libc_nano.a(libc_a-closer.o): in function `_close_r': + closer.c:(.text._close_r+0xc): warning: _close is not implemented and will always fail + /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/gcc_arm_none_eabi_toolchain/bin/../lib/gcc/arm-none-eabi/12.2.1/../../../../arm-none-eabi/bin/ld: /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/gcc_arm_none_eabi_toolchain/bin/../lib/gcc/arm-none-eabi/12.2.1/../../../../arm-none-eabi/lib/thumb/v7e-m/nofp/libc_nano.a(libc_a-signalr.o): in function `_getpid_r': + signalr.c:(.text._getpid_r+0x0): warning: _getpid is not implemented and will always fail + /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/gcc_arm_none_eabi_toolchain/bin/../lib/gcc/arm-none-eabi/12.2.1/../../../../arm-none-eabi/bin/ld: /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/gcc_arm_none_eabi_toolchain/bin/../lib/gcc/arm-none-eabi/12.2.1/../../../../arm-none-eabi/lib/thumb/v7e-m/nofp/libc_nano.a(libc_a-signalr.o): in function `_kill_r': + signalr.c:(.text._kill_r+0xe): warning: _kill is not implemented and will always fail + /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/gcc_arm_none_eabi_toolchain/bin/../lib/gcc/arm-none-eabi/12.2.1/../../../../arm-none-eabi/bin/ld: /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/gcc_arm_none_eabi_toolchain/bin/../lib/gcc/arm-none-eabi/12.2.1/../../../../arm-none-eabi/lib/thumb/v7e-m/nofp/libc_nano.a(libc_a-lseekr.o): in function `_lseek_r': + lseekr.c:(.text._lseek_r+0x10): warning: _lseek is not implemented and will always fail + /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/gcc_arm_none_eabi_toolchain/bin/../lib/gcc/arm-none-eabi/12.2.1/../../../../arm-none-eabi/bin/ld: /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/gcc_arm_none_eabi_toolchain/bin/../lib/gcc/arm-none-eabi/12.2.1/../../../../arm-none-eabi/lib/thumb/v7e-m/nofp/libc_nano.a(libc_a-readr.o): in function `_read_r': + readr.c:(.text._read_r+0x10): warning: _read is not implemented and will always fail + /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/gcc_arm_none_eabi_toolchain/bin/../lib/gcc/arm-none-eabi/12.2.1/../../../../arm-none-eabi/bin/ld: /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/gcc_arm_none_eabi_toolchain/bin/../lib/gcc/arm-none-eabi/12.2.1/../../../../arm-none-eabi/lib/thumb/v7e-m/nofp/libc_nano.a(libc_a-writer.o): in function `_write_r': + writer.c:(.text._write_r+0x10): warning: _write is not implemented and will always fail + INFO: Elapsed time: 6.716s, Critical Path: 1.98s + INFO: 40 processes: 3 internal, 37 linux-sandbox. + INFO: Build completed successfully, 40 total actions + +----------------------- +Run the project locally +----------------------- +#. Run the project locally on your Linux development host: + + .. code-block:: console + + bazel run //src:echo + + You should see output like this: + + .. code-block:: none + + INFO: Analyzed target //src:echo (36 packages loaded, 202 targets configured). + INFO: Found 1 target... + Target //src:echo up-to-date: + bazel-bin/src/echo + INFO: Elapsed time: 0.899s, Critical Path: 0.03s + INFO: 1 process: 1 internal. + INFO: Build completed successfully, 1 total action + INFO: Running command line: bazel-bin/src/echo + +#. Press ``Ctrl`` + ``C`` to stop running the project. + +---------------------------------------- +Flash the project onto a Discovery board +---------------------------------------- +If you have an `STM32F429 Discovery <https://www.st.com/stm32f4-discover>`_ +board, you can run the project on that hardware. + +.. note:: + + You don't need this hardware to run the project. Because this project + supports the :ref:`target-host` target, you can run everything + on your Linux development host. + +#. Ensure your udev rules are set up to allow the user running the commands + below to access the Discovery Board. For example, you may want to add the + following rule as ``/etc/udev/rules.d/99-stm32f329i-disc1.rules``: + + .. code-block:: console + + ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE="664", GROUP="plugdev" + + The user running the commands needs to be in the group ``plugdev``. + +#. Connect the Discovery board to your development host with a USB + cable. **Use the Mini-B USB port on the Discovery board, not the + Micro-B port**. + +#. Flash the project to the Discovery board: + + .. code-block:: console + + $ bazel run //tools:flash + + You should see output like this: + + .. code-block:: none + + INFO: Analyzed target //tools:flash (52 packages loaded, 2760 targets configured). + INFO: Found 1 target... + Target //tools:flash up-to-date: + bazel-bin/tools/flash + INFO: Elapsed time: 0.559s, Critical Path: 0.04s + INFO: 1 process: 1 internal. + INFO: Build completed successfully, 1 total action + INFO: Running command line: bazel-bin/tools/flash + binary Rlocation is: /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/execroot/__main__/bazel-out/k8-fastbuild/bin/src/echo.elf + openocd Rlocation is: /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/openocd/bin/openocd + openocd config Rlocation is: /home/xyz/.cache/bazel/_bazel_xyz/8c700b5cf88b83b789ceaf0e4e271fac/external/pigweed/targets/stm32f429i_disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg + xPack OpenOCD x86_64 Open On-Chip Debugger 0.11.0+dev (2021-12-07-17:30) + Licensed under GNU GPL v2 + For bug reports, read + http://openocd.org/doc/doxygen/bugs.html + DEPRECATED! use 'adapter driver' not 'interface' + DEPRECATED! use 'adapter serial' not 'hla_serial' + Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD + srst_only separate srst_nogate srst_open_drain connect_deassert_srst + + Info : clock speed 2000 kHz + Info : STLINK V2J25M14 (API v2) VID:PID 0483:374B + Info : Target voltage: 2.837377 + Info : stm32f4x.cpu: Cortex-M4 r0p1 processor detected + Info : stm32f4x.cpu: target has 6 breakpoints, 4 watchpoints + Info : gdb port disabled + Info : Unable to match requested speed 2000 kHz, using 1800 kHz + Info : Unable to match requested speed 2000 kHz, using 1800 kHz + target halted due to debug-request, current mode: Thread + xPSR: 0x01000000 pc: 0x08000708 msp: 0x20030000 + Info : Unable to match requested speed 8000 kHz, using 4000 kHz + Info : Unable to match requested speed 8000 kHz, using 4000 kHz + ** Programming Started ** + Info : device id = 0x20016419 + Info : flash size = 2048 kbytes + Info : Dual Bank 2048 kiB STM32F42x/43x/469/479 found + Info : Padding image section 0 at 0x08000010 with 496 bytes + ** Programming Finished ** + ** Resetting Target ** + Info : Unable to match requested speed 2000 kHz, using 1800 kHz + Info : Unable to match requested speed 2000 kHz, using 1800 kHz + shutdown command invoked + + +Communicate with the project over serial +======================================== +After you've flashed the project onto your Discovery board, your Linux development +host can communicate with the project over a serial terminal like ``miniterm``. + +#. Transmit and receive characters: + + .. code-block:: console + + $ bazel run //tools:miniterm -- /dev/ttyACM0 --filter=debug + + After typing ``hello`` and pressing ``Ctrl`` + ``]`` to exit you should see output + like this: + + .. code-block:: none + + INFO: Analyzed target //tools:miniterm (41 packages loaded, 2612 targets configured). + INFO: Found 1 target... + Target //tools:miniterm up-to-date: + bazel-bin/tools/miniterm + INFO: Elapsed time: 0.373s, Critical Path: 0.02s + INFO: 1 process: 1 internal. + INFO: Build completed successfully, 1 total action + INFO: Running command line: bazel-bin/tools/miniterm /dev/ttyACM0 '--filter=debug' + --- Miniterm on /dev/ttyACM0 115200,8,N,1 --- + --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- + [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 + --- exit --- + +------------------------------ +Questions? Comments? Feedback? +------------------------------ +Please join `our Discord <https://discord.com/invite/M9NSeTA>`_ and talk to us +in the ``#bazel-build`` channel or `file a bug <https://issues.pigweed.dev>`_. |