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