1.. _docs-root: 2.. highlight:: sh 3 4.. toctree:: 5 :maxdepth: 1 6 :hidden: 7 8 Home <self> 9 docs/getting_started 10 docs/concepts/index 11 docs/release_notes/index 12 Source Code <https://cs.opensource.google/pigweed/pigweed> 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> 16 Issue Tracker <https://bugs.pigweed.dev/> 17 docs/contributing 18 docs/code_of_conduct 19 docs/embedded_cpp_guide 20 Style Guide <docs/style_guide> 21 Automated Analysis <automated_analysis> 22 docs/os_abstraction_layers 23 targets 24 Build System <build_system> 25 docs/size_optimizations 26 FAQ <docs/faq> 27 docs/module_structure 28 module_guides 29 third_party_support 30 31======= 32Pigweed 33======= 34Pigweed is an open source collection of embedded-targeted libraries--or as we 35like to call them, modules. These modules are building blocks and 36infrastructure that enable faster and more reliable development on 37small-footprint MMU-less 32-bit microcontrollers like the STMicroelectronics 38STM32L452 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 47Getting Started 48--------------- 49If you'd like to get set up with Pigweed, please visit the 50:ref:`docs-getting-started` guide. 51 52What does Pigweed offer? 53------------------------ 54There are many modules in Pigweed; this section showcases a selection that 55produce visual output. For more information about the different Pigweed module 56offerings, refer to :ref:`docs-module-guides` section. 57 58``pw_watch`` - Build, flash, run, & test on save 59------------------------------------------------ 60In the web development space, file system watchers are prevalent. These 61watchers trigger a web server reload on source change, making development much 62faster. In the embedded space, file system watchers are less prevalent; 63however, they are no less useful! The Pigweed watcher module makes it easy to 64instantly compile, flash, and run tests upon save. Combined with the GN-based 65build which expresses the full dependency tree, only the exact tests affected 66by a file change are run on saves. 67 68The demo below shows :ref:`module-pw_watch` building for a STMicroelectronics 69STM32F429I-DISC1 development board, flashing the board with the affected test, 70and verifying the test runs as expected. Once this is set up, you can attach 71multiple devices to run tests in a distributed manner to reduce the time it 72takes to run tests. 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---------------------------------------------- 80Presubmit checks are essential tools, but they take work to set up, and 81projects don’t always get around to it. The :ref:`module-pw_presubmit` module 82provides tools for setting up high quality presubmit checks for any project. We 83use this framework to run Pigweed’s presubmit on our workstations and in our 84automated building tools. 85 86The ``pw_presubmit`` module includes ``pw format``, a tool that provides a 87unified interface for automatically formatting code in a variety of languages. 88With ``pw format``, you can format C, C++, Python, GN, and Go code according to 89configurations defined by your project. ``pw format`` leverages existing tools 90like ``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--------------------------------------------------------- 98A classic problem in the embedded space is reducing the **time from git clone 99to having a binary executing on a device**. An entire suite of tools is needed 100for building non-trivial production embedded projects, and need to be 101installed. 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 111In the server space, container solutions like Docker or Podman solve this; 112however, container solutions are a mixed bag for embedded systems development 113where one frequently needs access to native system resources like USB devices, 114or must operate on Windows. 115 116:ref:`module-pw_env_setup` is our compromise solution for this problem that 117works on Mac, Windows, and Linux. It leverages the Chrome Infrastructure 118Packaging Deployment system (CIPD) to bootstrap a Python installation, which in 119turn inflates a virtual environment. The tooling is installed into your 120workspace, and makes no changes to your system. This tooling is designed to be 121reused by any project. 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-------------------------------------------- 129Unit testing is important, and Pigweed offers a portable library that’s broadly 130compatible with `Google Test <https://github.com/google/googletest>`_. Unlike 131Google Test, :ref:`module-pw_unit_test` is built on top of embedded friendly 132primitives; for example, it does not use dynamic memory allocation. 133Additionally, it is easy to port to new target platforms by implementing the 134`test event handler interface <https://cs.opensource.google/pigweed/pigweed/+/main:pw_unit_test/public/pw_unit_test/event_handler.h>`_. 135 136Like other modules in Pigweed, ``pw_unit_test`` is designed for use in 137established codebases with their own build system, without the rest of Pigweed 138or the Pigweed integrated GN build. However, when combined with Pigweed's 139build, the result is a flexible and powerful setup that enables easily 140developing code on your desktop (with tests), then running the same tests 141on-device. 142 143.. image:: docs/images/pw_status_test.png 144 :width: 800 145 :alt: pw_status test run natively on host 146 147And more! 148--------- 149Here 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 157 compatible with C++14. 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 172See the :ref:`docs-module-guides` for the complete list of modules and their 173documentation. 174
