diff options
Diffstat (limited to 'docs/get_started')
| -rw-r--r-- | docs/get_started/bazel.rst | 217 | ||||
| -rw-r--r-- | docs/get_started/index.rst | 27 | ||||
| -rw-r--r-- | docs/get_started/upstream.rst | 10 |
3 files changed, 244 insertions, 10 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>`_. diff --git a/docs/get_started/index.rst b/docs/get_started/index.rst index 3048b47a6..5dc484aef 100644 --- a/docs/get_started/index.rst +++ b/docs/get_started/index.rst @@ -3,18 +3,27 @@ =========== Get Started =========== -Stay tuned for a tutorial on getting started with Pigweed in a Bazel-based project, -:ref:`Pigweed's primary build system <seed-0111>` going forward. +.. grid:: 1 + + .. grid-item-card:: :octicon:`rocket` Bazel + :link: docs-get-started-bazel + :link-type: ref + :class-item: sales-pitch-cta-primary + + Fork our minimal, Bazel-based starter code. Bazel is the recommended + build system for new projects using Pigweed. .. grid:: 2 .. grid-item-card:: :octicon:`code` Sample Project :link: https://pigweed.googlesource.com/pigweed/sample_project/+/main/README.md :link-type: url - :class-item: sales-pitch-cta-primary + :class-item: sales-pitch-cta-secondary Fork the Sample Project, a repository that outlines the recommended way to use - Pigweed in a broader GN-based project. + Pigweed in a broader GN-based project. Note that Bazel is the recommended + build system for new projects using Pigweed, whereas this sample project uses + GN. .. grid-item-card:: :octicon:`code` Kudzu :link: docs-kudzu @@ -22,10 +31,17 @@ Stay tuned for a tutorial on getting started with Pigweed in a Bazel-based proje :class-item: sales-pitch-cta-secondary Study the code of Kudzu, a just-for-fun Maker Faire 2023 project that - demonstrates complex Pigweed usage. + demonstrates complex Pigweed usage. This project also uses GN. .. grid:: 2 + .. grid-item-card:: :octicon:`list-ordered` Zephyr + :link: docs-os-zephyr-get-started + :link-type: ref + :class-item: sales-pitch-cta-secondary + + Instructions on how to use Pigweed in a Zephyr-based project. + .. grid-item-card:: :octicon:`list-ordered` Upstream Pigweed :link: docs-get-started-upstream :link-type: ref @@ -37,4 +53,5 @@ Stay tuned for a tutorial on getting started with Pigweed in a Bazel-based proje :maxdepth: 1 :hidden: + Bazel <bazel> Upstream Pigweed <upstream> diff --git a/docs/get_started/upstream.rst b/docs/get_started/upstream.rst index 9cf2d74f5..136443048 100644 --- a/docs/get_started/upstream.rst +++ b/docs/get_started/upstream.rst @@ -174,7 +174,7 @@ bootstrap may take several minutes to complete, so please be patient. Below is a real-time demo with roughly what you should expect to see as output: -.. image:: ../images/pw_env_setup_demo.gif +.. image:: https://storage.googleapis.com/pigweed-media/pw_env_setup_demo.gif :width: 800 :alt: build example using pw watch @@ -260,7 +260,7 @@ save the file. See below for a demo of this in action: -.. image:: ../images/pw_watch_build_demo.gif +.. image:: https://storage.googleapis.com/pigweed-media/pw_watch_build_demo.gif :width: 800 :alt: build example using pw watch @@ -274,7 +274,7 @@ failure. To see a test failure, modify ``pw_status/status_test.cc`` to fail by changing one of the strings in the "KnownString" test. -.. image:: ../images/pw_watch_test_demo.gif +.. image:: https://storage.googleapis.com/pigweed-media/pw_watch_test_demo.gif :width: 800 :alt: example test failure using pw watch @@ -330,7 +330,7 @@ updates to ensure you have permissions to use the USB device. For example, on Linux you may need to update your udev rules and ensure you're in the plugdev and dialout groups. -.. image:: ../images/stm32f429i-disc1_connected.jpg +.. image:: https://storage.googleapis.com/pigweed-media/stm32f429i-disc1_connected.jpg :width: 800 :alt: development boards connected via USB @@ -367,7 +367,7 @@ will be run across the attached boards! See the demo below for an example of what this all looks like put together: -.. image:: ../images/pw_watch_on_device_demo.gif +.. image:: https://storage.googleapis.com/pigweed-media/pw_watch_on_device_demo.gif :width: 800 :alt: pw watch running on-device tests |