docs: Add Zephyr quickstart
Change-Id: I2d826170182d18205d2ab5fc37f7b95aea1435f7
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/196671
Reviewed-by: Yuval Peress <peress@google.com>
Presubmit-Verified: CQ Bot Account <pigweed-scoped@luci-project-accounts.iam.gserviceaccount.com>
Commit-Queue: Kayce Basques <kayce@google.com>
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index b7892f0..1f85321 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -59,6 +59,7 @@
"get_started/first_time_setup.rst",
"get_started/index.rst",
"get_started/upstream.rst",
+ "get_started/zephyr.rst",
"glossary.rst",
"infra/ci_cq_intro.rst",
"infra/index.rst",
diff --git a/docs/get_started/index.rst b/docs/get_started/index.rst
index be32f0e..a29e318 100644
--- a/docs/get_started/index.rst
+++ b/docs/get_started/index.rst
@@ -38,7 +38,17 @@
Fork our minimal, Bazel-based starter code. Bazel is the recommended
build system for new projects using Pigweed.
-.. grid:: 2
+.. grid:: 1
+
+ .. grid-item-card:: :octicon:`rocket` Zephyr
+ :link: docs-quickstart-zephyr
+ :link-type: ref
+ :class-item: sales-pitch-cta-secondary
+
+ Learn how to set up a C++-based Zephyr project that is ready to use
+ Pigweed and then build the app with Zephyr's ``native_sim`` board.
+
+.. grid:: 1
.. grid-item-card:: :octicon:`code` Examples
:link: https://pigweed.dev/examples/index.html
@@ -50,6 +60,9 @@
recommended build system for new projects using Pigweed, whereas the
examples repo uses GN.
+
+.. grid:: 2
+
.. grid-item-card:: :octicon:`code` Kudzu
:link: docs-kudzu
:link-type: ref
@@ -58,15 +71,6 @@
Study the code of Kudzu, a just-for-fun Maker Faire 2023 project that
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
@@ -81,6 +85,7 @@
First-time setup <first_time_setup>
Bazel quickstart <bazel>
Bazel integration <bazel_integration>
+ Zephyr quickstart <zephyr>
Upstream Pigweed <upstream>
------------------------------------------
diff --git a/docs/get_started/zephyr.rst b/docs/get_started/zephyr.rst
new file mode 100644
index 0000000..d220a7b
--- /dev/null
+++ b/docs/get_started/zephyr.rst
@@ -0,0 +1,307 @@
+.. _docs-quickstart-zephyr:
+
+=================
+Zephyr quickstart
+=================
+.. _Zephyr: https://zephyrproject.org/
+.. _native_sim: https://docs.zephyrproject.org/latest/boards/native/native_sim/doc/index.html
+.. _GPIO Driver API: https://docs.zephyrproject.org/latest/doxygen/html/group__devicetree-gpio.html
+
+This tutorial shows you how to set up a new C++-based `Zephyr`_ project that's
+ready to use Pigweed. You'll learn how to build and run the project's app on
+`native_sim`_ as well as a physical Raspberry Pi Pico. The app uses
+:ref:`module-pw_log` and :ref:`module-pw_string` to log messages and
+Zephyr's `GPIO Driver API`_ to blink an LED.
+
+.. figure:: https://storage.googleapis.com/pigweed-media/zephyr-quickstart-pw_ide.png
+ :alt: Editing the Zephyr quickstart project in VS Code
+
+ The project's :ref:`module-pw_ide` integration provides code intelligence
+ and easy target swapping in VS Code
+
+.. _docs-quickstart-zephyr-prereqs:
+
+-------------
+Prerequisites
+-------------
+* **Disk space**: After setting everything up, the project takes ~19GB of space.
+ The project clones the Zephyr and Pigweed repos as well as their dependencies.
+ It also downloads toolchains and sets up a hermetic development environment.
+* **Operating systems**: This tutorial has only been validated on Debian-based
+ Linux and macOS. Windows support is a work in progress.
+
+.. _docs-quickstart-zephyr-setup:
+
+-----
+Setup
+-----
+#. Complete Pigweed's :ref:`First-time setup <docs-first-time-setup-guide>`
+ process.
+
+#. Clone the starter repo.
+
+ .. tab-set::
+
+ .. tab-item:: Linux
+ :sync: lin
+
+ .. code-block:: console
+
+ git clone --recursive \
+ https://pigweed.googlesource.com/pigweed/quickstart/zephyr \
+ ~/zephyr-quickstart
+
+ .. tab-item:: macOS
+ :sync: mac
+
+ .. code-block:: console
+
+ git clone --recursive \
+ https://pigweed.googlesource.com/pigweed/quickstart/zephyr \
+ ~/zephyr-quickstart
+
+ .. _main Pigweed: https://pigweed.googlesource.com/pigweed/pigweed/
+ .. _main Zephyr: https://github.com/zephyrproject-rtos/zephyr
+
+ This command downloads the `main Pigweed`_ and `main Zephyr`_ repos
+ as Git submodules.
+
+#. Change your working directory to the quickstart repo.
+
+ .. tab-set::
+
+ .. tab-item:: Linux
+ :sync: lin
+
+ .. code-block:: console
+
+ cd ~/quickstart-zephyr
+
+ .. tab-item:: macOS
+ :sync: mac
+
+ .. code-block:: console
+
+ cd ~/quickstart-zephyr
+
+#. Bootstrap the repo.
+
+ .. tab-set::
+
+ .. tab-item:: Linux
+ :sync: lin
+
+ .. code-block:: console
+
+ source bootstrap.sh
+
+ .. tab-item:: macOS
+ :sync: mac
+
+ .. code-block:: console
+
+ source bootstrap.sh
+
+ Pigweed's bootstrap workflow creates a hermetic development environment
+ for you, including toolchain setup!
+
+ .. tip::
+
+ For subsequent development sessions, activate your development environment
+ with the following command:
+
+ .. tab-set::
+
+ .. tab-item:: Linux
+ :sync: lin
+
+ .. code-block:: console
+
+ source activate.sh
+
+ .. tab-item:: macOS
+ :sync: mac
+
+ .. code-block:: console
+
+ source activate.sh
+
+ The activate script is faster than the bootstrap script. You only need to
+ run the bootstrap script after updating your Zephyr or Pigweed submodules.
+
+ .. _West: https://docs.zephyrproject.org/latest/develop/west/index.html
+
+#. Initialize your `West`_ workspace using the manifest that came with the
+ starter repo.
+
+ .. code-block:: console
+
+ west init -l manifest
+
+#. Update your West workspace.
+
+ .. code-block:: console
+
+ west update
+
+#. (Optional) Initialize :ref:`module-pw_ide` if you plan on working in
+ VS Code. ``pw_ide`` provides code intelligence features and makes it
+ easy to swap targets.
+
+ .. code-block:: console
+
+ pw ide sync
+
+.. _docs-quickstart-zephyr-build:
+
+---------------------
+Build and run the app
+---------------------
+
+.. _docs-quickstart-zephyr-build-native_sim:
+
+Native simulator
+================
+#. Build the quickstart app for `native_sim`_ and run it:
+
+ .. code-block:: console
+
+ export ZEPHYR_TOOLCHAIN_VARIANT=llvm &&
+ west build -p -b native_sim app -t run
+
+ You should see the app successfully build and then log messages to
+ ``stdout``:
+
+ .. code-block:: none
+
+ [00:00:00.000,000] <inf> pigweed: Hello, world!
+ [00:00:00.000,000] <inf> pigweed: LED state: OFF
+ [00:00:01.010,000] <inf> pigweed: LED state: ON
+ [00:00:02.020,000] <inf> pigweed: LED state: OFF
+ [00:00:03.030,000] <inf> pigweed: LED state: ON
+ [00:00:04.040,000] <inf> pigweed: LED state: OFF
+
+ .. important::
+
+ When building for ``native_sim`` make sure that
+ ``ZEPHYR_TOOLCHAIN_VARIANT`` is set to ``llvm``.
+ See :ref:`docs-quickstart-zephyr-troubleshooting-envvar`.
+
+#. (Optional) Build and run an upstream Zephyr sample app:
+
+ .. code-block:: console
+
+ west build -p -b native_sim third_party/zephyr/samples/basic/blinky -t run
+
+.. _docs-quickstart-zephyr-build-pico:
+
+Raspberry Pi Pico
+=================
+.. _Raspberry Pi Pico: https://docs.zephyrproject.org/latest/boards/raspberrypi/rpi_pico/doc/index.html
+.. _Pico SDK: https://github.com/raspberrypi/pico-sdk
+.. _picotool: https://github.com/raspberrypi/picotool
+
+#. Build the quickstart app for `Raspberry Pi Pico`_:
+
+ .. code-block:: console
+
+ export ZEPHYR_TOOLCHAIN_VARIANT=zephyr &&
+ west build -p -b rpi_pico app
+
+ .. important::
+
+ When building for physical boards make sure that
+ ``ZEPHYR_TOOLCHAIN_VARIANT`` is set to ``zephyr``.
+ See :ref:`docs-quickstart-zephyr-troubleshooting-envvar`.
+
+#. Install the `Pico SDK`_ and `picotool`_ so that you can easily
+ flash the quickstart app onto your Pico over USB without needing to
+ manually put your Pico board into ``BOOTSEL`` mode:
+
+ .. code-block:: console
+
+ pw package install pico_sdk
+ pw package install picotool
+
+#. Put the following rules into ``/usr/lib/udev/rules.d/49-picoprobe.rules``:
+
+ .. code-block:: none
+
+ # Pico app mode
+ SUBSYSTEMS=="usb", ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="000a", MODE:="0666"
+ KERNEL=="ttyACM*", ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="000a", MODE:="0666", SYMLINK+="rp2040"
+ # RP2 Boot
+ SUBSYSTEMS=="usb", ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="0003", MODE:="0666"
+ KERNEL=="ttyACM*", ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="0003", MODE:="0666", SYMLINK+="rp2040"
+ # Picoprobe
+ SUBSYSTEMS=="usb", ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="0004", MODE:="0666"
+ KERNEL=="ttyACM*", ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="0004", MODE:="0666", SYMLINK+="picoprobe"
+
+#. Apply the rules:
+
+ .. code-block:: console
+
+ sudo udevadm control --reload-rules
+ sudo udevadm trigger
+
+#. Flash the app onto your board:
+
+ .. code-block:: console
+
+ picotool reboot -f -u &&
+ sleep 3 &&
+ picotool load -x ./build/zephyr/zephyr.elf
+
+.. _docs-quickstart-zephyr-troubleshooting:
+
+---------------
+Troubleshooting
+---------------
+
+.. _docs-quickstart-zephyr-troubleshooting-envvar:
+
+``fatal error: bits/c++config.h: No such file or directory``
+============================================================
+If you see a compilation error about not being able to find
+``<bits/c++config.h>``, make sure that your ``ZEPHYR_TOOLCHAIN_VARIANT``
+environment variable is correctly set:
+
+* Set it to ``llvm`` when building for ``native_sim``.
+* Set it to ``zephyr`` when building for physical boards.
+
+Here's an example of the error:
+
+.. code-block:: console
+
+ ...
+ [2/109] Generating include/generated/version.h
+ -- Zephyr version: 3.6.99 (~/zephyr-quickstart/third_party/zephyr), build: v3.6.0-1976-g8a88cd4805b0
+ [10/109] Building CXX object modules/pigweed/pw_string/CMakeFiles/pw_string.to_string.dir/type_to_string.cc.obj
+ FAILED: modules/pigweed/pw_string/CMakeFiles/pw_string.to_string.dir/type_to_string.cc.obj
+ ccache /usr/bin/g++
+ ...
+ -c ~/zephyr-quickstart/third_party/pigweed/pw_string/type_to_string.cc
+ In file included from ~/zephyr-quickstart/third_party/pigweed/pw_string/public/pw_string/type_to_string.h:20,
+ from ~/zephyr-quickstart/third_party/pigweed/pw_string/type_to_string.cc:15:
+ /usr/include/c++/13/cstdint:38:10: fatal error: bits/c++config.h: No such file or directory
+ 38 | #include <bits/c++config.h>
+ | ^~~~~~~~~~~~~~~~~~
+ compilation terminated.
+ ...
+ [12/109] Building CXX object modules/pigweed/pw_string/CMakeFiles/pw_string.builder.dir/string_builder.cc.obj
+ FAILED: modules/pigweed/pw_string/CMakeFiles/pw_string.builder.dir/string_builder.cc.obj
+ ccache /usr/bin/g++
+ ...
+ -c ~/zephyr-quickstart/third_party/pigweed/pw_string/string_builder.cc
+ In file included from /usr/include/c++/13/algorithm:60,
+ from ~/zephyr-quickstart/third_party/pigweed/pw_string/public/pw_string/string_builder.h:21,
+ from ~/zephyr-quickstart/third_party/pigweed/pw_string/string_builder.cc:15:
+ /usr/include/c++/13/bits/stl_algobase.h:59:10: fatal error: bits/c++config.h: No such file or directory
+ 59 | #include <bits/c++config.h>
+ | ^~~~~~~~~~~~~~~~~~
+ compilation terminated.
+ [15/109] Building C object zephyr/CMakeFiles/offsets.dir/arch/posix/core/offsets/offsets.c.obj
+ ninja: build stopped: subcommand failed.
+ FATAL ERROR: command exited with status 1: ~/zephyr-quickstart/environment/cipd/packages/cmake/bin/cmake
+ --build ~/zephyr-quickstart/build --target run
+
