Chad Norvell | ee40edd | 2022-02-25 13:29:53 -0800 | [diff] [blame] | 1 | .. _docs-root: |
Armando Montanez | 4222532 | 2020-01-02 13:11:41 -0800 | [diff] [blame] | 2 | .. highlight:: sh |
| 3 | |
Alexei Frolov | 0efdb11 | 2019-11-14 17:22:08 -0800 | [diff] [blame] | 4 | .. toctree:: |
Wyatt Hepler | b82f995 | 2019-11-25 13:56:31 -0800 | [diff] [blame] | 5 | :maxdepth: 1 |
| 6 | :hidden: |
Alexei Frolov | 0efdb11 | 2019-11-14 17:22:08 -0800 | [diff] [blame] | 7 | |
Wyatt Hepler | ab4eb7a | 2020-01-08 18:04:31 -0800 | [diff] [blame] | 8 | Home <self> |
Keir Mierle | 72cae43 | 2021-04-10 02:03:40 -0700 | [diff] [blame] | 9 | docs/getting_started |
Chad Norvell | 5e779b8 | 2022-02-24 18:58:09 -0800 | [diff] [blame] | 10 | docs/concepts/index |
Chad Norvell | ee40edd | 2022-02-25 13:29:53 -0800 | [diff] [blame] | 11 | docs/release_notes/index |
Wyatt Hepler | b847615 | 2021-04-06 15:28:32 -0700 | [diff] [blame] | 12 | Source Code <https://cs.opensource.google/pigweed/pigweed> |
Keir Mierle | bc6d475 | 2020-07-23 14:00:28 -0700 | [diff] [blame] | 13 | Code Reviews <https://pigweed-review.googlesource.com> |
| 14 | Mailing List <https://groups.google.com/forum/#!forum/pigweed> |
| 15 | Chat Room <https://discord.gg/M9NSeTA> |
Rob Mohr | a10ebdb | 2021-03-10 19:50:13 -0800 | [diff] [blame] | 16 | Issue Tracker <https://bugs.pigweed.dev/> |
Keir Mierle | 72cae43 | 2021-04-10 02:03:40 -0700 | [diff] [blame] | 17 | docs/contributing |
| 18 | docs/code_of_conduct |
Wyatt Hepler | b82f995 | 2019-11-25 13:56:31 -0800 | [diff] [blame] | 19 | docs/embedded_cpp_guide |
Keir Mierle | 78db8c6 | 2021-11-10 19:28:21 -0800 | [diff] [blame] | 20 | Style Guide <docs/style_guide> |
Ted Pudlik | eb05b18 | 2021-11-05 00:30:56 +0000 | [diff] [blame] | 21 | Automated Analysis <automated_analysis> |
Ewout van Bekkum | cc756c8 | 2021-05-12 07:57:43 -0700 | [diff] [blame] | 22 | docs/os_abstraction_layers |
Armando Montanez | 0874558 | 2019-12-12 10:51:50 -0800 | [diff] [blame] | 23 | targets |
Keir Mierle | bc6d475 | 2020-07-23 14:00:28 -0700 | [diff] [blame] | 24 | Build System <build_system> |
Ewout van Bekkum | e7caae4 | 2021-11-29 11:52:18 -0800 | [diff] [blame] | 25 | docs/size_optimizations |
Keir Mierle | eaa7e92 | 2020-07-24 14:30:47 -0700 | [diff] [blame] | 26 | FAQ <docs/faq> |
Keir Mierle | 086ef1c | 2020-03-19 02:03:51 -0700 | [diff] [blame] | 27 | docs/module_structure |
| 28 | module_guides |
Ewout van Bekkum | ab1f8f7 | 2021-07-19 17:31:24 -0700 | [diff] [blame] | 29 | third_party_support |
Keir Mierle | 72cae43 | 2021-04-10 02:03:40 -0700 | [diff] [blame] | 30 | |
| 31 | ======= |
| 32 | Pigweed |
| 33 | ======= |
| 34 | Pigweed is an open source collection of embedded-targeted libraries--or as we |
| 35 | like to call them, modules. These modules are building blocks and |
| 36 | infrastructure that enable faster and more reliable development on |
| 37 | small-footprint MMU-less 32-bit microcontrollers like the STMicroelectronics |
| 38 | STM32L452 or the Nordic nRF52832. |
| 39 | |
| 40 | .. attention:: |
| 41 | |
| 42 | Pigweed is in **early access**; though many modules are shipping in |
| 43 | production already. If you're interested in using Pigweed, please reach out |
| 44 | in our `chat room <https://discord.gg/M9NSeTA>`_ or on the `mailing list |
| 45 | <https://groups.google.com/forum/#!forum/pigweed>`_. |
| 46 | |
| 47 | Getting Started |
| 48 | --------------- |
| 49 | If you'd like to get set up with Pigweed, please visit the |
| 50 | :ref:`docs-getting-started` guide. |
| 51 | |
| 52 | What does Pigweed offer? |
| 53 | ------------------------ |
| 54 | There are many modules in Pigweed; this section showcases a selection that |
| 55 | produce visual output. For more information about the different Pigweed module |
| 56 | offerings, refer to :ref:`docs-module-guides` section. |
| 57 | |
| 58 | ``pw_watch`` - Build, flash, run, & test on save |
| 59 | ------------------------------------------------ |
| 60 | In the web development space, file system watchers are prevalent. These |
| 61 | watchers trigger a web server reload on source change, making development much |
| 62 | faster. In the embedded space, file system watchers are less prevalent; |
| 63 | however, they are no less useful! The Pigweed watcher module makes it easy to |
| 64 | instantly compile, flash, and run tests upon save. Combined with the GN-based |
| 65 | build which expresses the full dependency tree, only the exact tests affected |
| 66 | by a file change are run on saves. |
| 67 | |
Ted Pudlik | 89147b3 | 2021-12-06 22:46:54 +0000 | [diff] [blame] | 68 | The demo below shows :ref:`module-pw_watch` building for a STMicroelectronics |
| 69 | STM32F429I-DISC1 development board, flashing the board with the affected test, |
| 70 | and verifying the test runs as expected. Once this is set up, you can attach |
| 71 | multiple devices to run tests in a distributed manner to reduce the time it |
| 72 | takes to run tests. |
Keir Mierle | 72cae43 | 2021-04-10 02:03:40 -0700 | [diff] [blame] | 73 | |
| 74 | .. image:: docs/images/pw_watch_on_device_demo.gif |
| 75 | :width: 800 |
| 76 | :alt: pw watch running on-device tests |
| 77 | |
| 78 | ``pw_presubmit`` - Vacuum lint on every commit |
| 79 | ---------------------------------------------- |
| 80 | Presubmit checks are essential tools, but they take work to set up, and |
Ted Pudlik | 89147b3 | 2021-12-06 22:46:54 +0000 | [diff] [blame] | 81 | projects don’t always get around to it. The :ref:`module-pw_presubmit` module |
| 82 | provides tools for setting up high quality presubmit checks for any project. We |
| 83 | use this framework to run Pigweed’s presubmit on our workstations and in our |
| 84 | automated building tools. |
Keir Mierle | 72cae43 | 2021-04-10 02:03:40 -0700 | [diff] [blame] | 85 | |
| 86 | The ``pw_presubmit`` module includes ``pw format``, a tool that provides a |
| 87 | unified interface for automatically formatting code in a variety of languages. |
| 88 | With ``pw format``, you can format C, C++, Python, GN, and Go code according to |
| 89 | configurations defined by your project. ``pw format`` leverages existing tools |
| 90 | like ``clang-format``, and it’s simple to add support for new languages. |
| 91 | |
| 92 | .. image:: pw_presubmit/docs/pw_presubmit_demo.gif |
| 93 | :width: 800 |
| 94 | :alt: pw presubmit demo |
| 95 | |
| 96 | ``pw_env_setup`` - Cross platform embedded compiler setup |
| 97 | --------------------------------------------------------- |
| 98 | A classic problem in the embedded space is reducing the **time from git clone |
| 99 | to having a binary executing on a device**. An entire suite of tools is needed |
| 100 | for building non-trivial production embedded projects, and need to be |
| 101 | installed. For example: |
| 102 | |
| 103 | - A C++ compiler for your target device, and also for your host |
| 104 | - A build system or three; for example, GN, Ninja, CMake, Bazel |
| 105 | - A code formatting program like clang-format |
| 106 | - A debugger like OpenOCD to flash and debug your embedded device |
| 107 | - A known Python version with known modules installed for scripting |
| 108 | - A Go compiler for the Go-based command line tools |
| 109 | - ... and so on |
| 110 | |
| 111 | In the server space, container solutions like Docker or Podman solve this; |
| 112 | however, container solutions are a mixed bag for embedded systems development |
| 113 | where one frequently needs access to native system resources like USB devices, |
| 114 | or must operate on Windows. |
| 115 | |
Ted Pudlik | 89147b3 | 2021-12-06 22:46:54 +0000 | [diff] [blame] | 116 | :ref:`module-pw_env_setup` is our compromise solution for this problem that |
| 117 | works on Mac, Windows, and Linux. It leverages the Chrome Infrastructure |
| 118 | Packaging Deployment system (CIPD) to bootstrap a Python installation, which in |
| 119 | turn inflates a virtual environment. The tooling is installed into your |
| 120 | workspace, and makes no changes to your system. This tooling is designed to be |
| 121 | reused by any project. |
Keir Mierle | 72cae43 | 2021-04-10 02:03:40 -0700 | [diff] [blame] | 122 | |
| 123 | .. image:: docs/images/pw_env_setup_demo.gif |
| 124 | :width: 800 |
| 125 | :alt: pw environment setup demo |
| 126 | |
| 127 | ``pw_unit_test`` - Embedded testing for MCUs |
| 128 | -------------------------------------------- |
| 129 | Unit testing is important, and Pigweed offers a portable library that’s broadly |
| 130 | compatible with `Google Test <https://github.com/google/googletest>`_. Unlike |
Ted Pudlik | 89147b3 | 2021-12-06 22:46:54 +0000 | [diff] [blame] | 131 | Google Test, :ref:`module-pw_unit_test` is built on top of embedded friendly |
| 132 | primitives; for example, it does not use dynamic memory allocation. |
Keir Mierle | 72cae43 | 2021-04-10 02:03:40 -0700 | [diff] [blame] | 133 | Additionally, it is easy to port to new target platforms by implementing the |
Rob Mohr | 640c75c | 2021-05-26 07:22:54 -0700 | [diff] [blame] | 134 | `test event handler interface <https://cs.opensource.google/pigweed/pigweed/+/main:pw_unit_test/public/pw_unit_test/event_handler.h>`_. |
Keir Mierle | 72cae43 | 2021-04-10 02:03:40 -0700 | [diff] [blame] | 135 | |
| 136 | Like other modules in Pigweed, ``pw_unit_test`` is designed for use in |
| 137 | established codebases with their own build system, without the rest of Pigweed |
| 138 | or the Pigweed integrated GN build. However, when combined with Pigweed's |
| 139 | build, the result is a flexible and powerful setup that enables easily |
| 140 | developing code on your desktop (with tests), then running the same tests |
| 141 | on-device. |
| 142 | |
| 143 | .. image:: docs/images/pw_status_test.png |
| 144 | :width: 800 |
| 145 | :alt: pw_status test run natively on host |
| 146 | |
| 147 | And more! |
| 148 | --------- |
| 149 | Here is a selection of interesting modules: |
| 150 | |
| 151 | - :ref:`module-pw_cpu_exception_cortex_m` - Robust low level hardware fault |
| 152 | handler for ARM Cortex-M; the handler even has unit tests written in |
| 153 | assembly to verify nested-hardware-fault handling! |
| 154 | |
| 155 | - :ref:`module-pw_polyfill` - Similar to JavaScript “polyfill” libraries, this |
| 156 | module provides selected C++17 standard library components that are |
Wyatt Hepler | 0132da5 | 2021-10-11 16:20:11 -0700 | [diff] [blame] | 157 | compatible with C++14. |
Keir Mierle | 72cae43 | 2021-04-10 02:03:40 -0700 | [diff] [blame] | 158 | |
| 159 | - :ref:`module-pw_tokenizer` - Replace string literals from log statements |
| 160 | with 32-bit tokens, to reduce flash use, reduce logging bandwidth, and save |
| 161 | formatting cycles from log statements at runtime. |
| 162 | |
| 163 | - :ref:`module-pw_kvs` - A key-value-store implementation for flash-backed |
| 164 | persistent storage with integrated wear levelling. This is a lightweight |
| 165 | alternative to a file system for embedded devices. |
| 166 | |
| 167 | - :ref:`module-pw_protobuf` - An early preview of our wire-format-oriented |
| 168 | protocol buffer implementation. This protobuf compiler makes a different set |
| 169 | of implementation tradeoffs than the most popular protocol buffer library in |
| 170 | this space, nanopb. |
| 171 | |
| 172 | See the :ref:`docs-module-guides` for the complete list of modules and their |
| 173 | documentation. |