third_party/pigweed/repo/README.md

   1 # Pigweed
   2
   3 Pigweed is an open source collection of embedded-targeted libraries--or as we
   4 like to call them, modules. These modules are building blocks and infrastructure
   5 that enable faster and more reliable development on small-footprint MMU-less
   6 32-bit microcontrollers like the STMicroelectronics STM32L452 or the Nordic
   7 nRF52832.
   8
   9 Pigweed is in the early stages of development, **and should be considered
  10 experimental**. We’re continuing to evolve the platform and add new modules. We
  11 value developer feedback along the way.
  12
  13 # Quick links
  14
  15  - [Getting started guide](docs/getting_started.md)
  16  - [Source code](https://pigweed.googlesource.com/pigweed/pigweed/+/refs/heads/master)
  17  - [Code reviews](https://pigweed-review.googlesource.com/)
  18  - [Issue tracker](https://bugs.chromium.org/p/pigweed/issues/list)
  19  - [Mailing list](https://groups.google.com/forum/#!forum/pigweed)
  20  - [Chat room (Discord)](https://discord.gg/M9NSeTA)
  21  - [Open Source blog post](https://opensource.googleblog.com/2020/03/pigweed-collection-of-embedded-libraries.html)
  22
  23 Get the code: `git clone https://pigweed.googlesource.com/pigweed/pigweed`
  24
  25 # Getting Started
  26
  27 If you'd like to get set up with Pigweed, please visit the
  28 [getting started guide](docs/getting_started.md).
  29
  30 # What does Pigweed offer?
  31
  32 There are many modules in Pigweed, and this section only showcases a small
  33 selection that happen to produce visual output. For more information about the
  34 different Pigweed module offerings, refer to "Module Guides" section in the full
  35 documentation.
  36
  37 Note: For now the full documentation is not available online; you must build
  38 it. Building the docs is easy; see the [getting started
  39 guide](docs/getting_started.md) for how.
  40
  41 ## `pw_watch` - Build, flash, run, & test on save
  42
  43 In the web development space, file system watchers are prevalent. These watchers
  44 trigger a web server reload on source change, making development much faster. In
  45 the embedded space, file system watchers are less prevalent; however, they are
  46 no less useful! The Pigweed watcher module makes it easy to instantly compile,
  47 flash, and run tests upon save. Combined with the GN-based build which expresses
  48 the full dependency tree, only the exact tests affected by a file change are run
  49 on saves.
  50
  51 The demo below shows `pw_watch` building for a STMicroelectronics
  52 STM32F429I-DISC1 development board, flashing the board with the affected test,
  53 and verifying the test runs as expected. Once this is set up, you can attach
  54 multiple devices to run tests in a distributed manner to reduce the time it
  55 takes to run tests.
  56
  57 ![pw watch running on-device tests](docs/images/pw_watch_on_device_demo.gif)
  58
  59 ## `pw_presubmit` - Vacuum code lint on every commit
  60
  61 Presubmit checks are essential tools, but they take work to set up, and projects
  62 don’t always get around to it. The `pw_presubmit` module provides tools for
  63 setting up high quality presubmit checks for any project. We use this framework
  64 to run Pigweed’s presubmit on our workstations and in our automated building
  65 tools.
  66
  67 The `pw_presubmit` module includes `pw format` command, a tool that provides a
  68 unified interface for automatically formatting code in a variety of languages.
  69 With `pw format`, you can format C, C++, Python, GN, and Go code according to
  70 configurations defined by your project. `pw format` leverages existing tools
  71 like `clang-format`, and it’s simple to add support for new languages.
  72
  73 ![pw presubmit demo](pw_presubmit/docs/pw_presubmit_demo.gif)
  74
  75 ## `pw_env_setup` - Cross platform embedded compiler setup
  76
  77 A classic problem in the embedded space is reducing the time from git clone to
  78 having a binary executing on a device. The issue is that an entire suite of
  79 tools is needed for non-trivial production embedded projects. For example:
  80
  81  - A C++ compiler for your target device, and also for your host
  82  - A build system or three; for example, GN, Ninja, CMake, Bazel
  83  - A code formatting program like clang-format
  84  - A debugger like OpenOCD to flash and debug your embedded device
  85  - A known Python version with known modules installed for scripting
  86  - A Go compiler for the Go-based command line tools
  87  - ... and so on
  88
  89 In the server space, container solutions like Docker or Podman solve this;
  90 however, in our experience container solutions are a mixed bag for embedded
  91 systems development where one frequently needs access to native system resources
  92 like USB devices, or must operate on Windows.
  93
  94 `pw_env_setup` is our compromise solution for this problem that works on Mac,
  95 Windows, and Linux. It leverages the Chrome packaging system CIPD to bootstrap a
  96 Python installation, which in turn inflates a virtual environment. The tooling
  97 is installed into your workspace, and makes no changes to your system. This
  98 tooling is designed to be reused by any project.
  99
 100 ![pw environment setup demo](docs/images/pw_env_setup_demo.gif)
 101
 102 ## `pw_unit_test` - Embedded testing for MCUs
 103
 104 Unit testing is important, and Pigweed offers a portable library that’s broadly
 105 compatible with [Google Test](https://github.com/google/googletest). Unlike
 106 Google Test, `pw_unit_test` is built on top of embedded friendly primitives; for
 107 example, it does not use dynamic memory allocation. Additionally, it is easy to
 108 port to new target platforms by implementing the
 109 [test event handler interface](https://pigweed.googlesource.com/pigweed/pigweed/+/refs/heads/master/pw_unit_test/public/pw_unit_test/event_handler.h).
 110
 111 Like other modules in Pigweed, `pw_unit_test` is designed for use in
 112 established codebases with their own build system, without the rest of Pigweed
 113 or the Pigweed integrated GN build. However, when combined with Pigweed's
 114 build, the result is a flexible and powerful setup that enables easily
 115 developing code on your desktop (with tests), then running the same tests
 116 on-device.
 117
 118 ![pw_status test run natively on host](docs/images/pw_status_test.png)
 119
 120 ## And more!
 121
 122 See the "Module Guides" in the documentation for the complete list and
 123 documentation for each, but is a selection of some others:
 124
 125  - `pw_cpu_exception_cortex_m`: Robust low level hardware fault handler for ARM
 126    Cortex-M; the handler even has unit tests written in assembly to verify
 127    nested-hardware-fault handling!
 128
 129  - `pw_polyfill`: Similar to JavaScript “polyfill” libraries, this module
 130    provides selected C++17 standard library components that are compatible with
 131    C++11 and C++14.
 132
 133  - `pw_minimal_cpp_stdlib`: An entirely incomplete implementation of the C++17
 134    standard library, that provides some of the primitives needed by Pigweed
 135    itself. Useful for projects that want to use Pigweed, but don’t enable the
 136    typical standard C++ libraries like GNU’s libstdc++ or LLVM’s libc++. Don’t
 137    use this module unless you know what you are doing.
 138
 139  - `pw_tokenizer`: Replace string literals from log statements with 32-bit
 140    tokens, to reduce flash use, reduce logging bandwidth, and save formatting
 141    cycles from log statements at runtime.
 142
 143  - `pw_kvs`: A key-value-store implementation for flash-backed persistent
 144    storage with integrated wear levelling. This is a lightweight alternative to
 145    a file system for embedded devices.
 146
 147  - `pw_protobuf`: An early preview of our wire-format-oriented protocol buffer
 148    implementation. This protobuf compiler makes a different set of
 149    implementation tradeoffs than the most popular protocol buffer library in
 150    this space, nanopb.