docs: Various refinements ahead of launch This is a series of changes across the documentation to improve the overall first-user experience. Key changes: 1. New "Express setup" section in the "Getting Started" page. 2. Rename and reorder the left-hand menu bar components 3. Fix various copyright dates 4. Add presubmit animated gif to the pw_presubmit docs Change-Id: I22a75ace8c2be15a6e5890d6e1b3618a1d53eefa
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 7ff895c..551d804 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md
@@ -1,4 +1,4 @@ -# Pigweed Code of Conduct +# Code of Conduct ## Our Pledge
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index db260a0..2670eed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md
@@ -6,16 +6,18 @@ ensure the changes make sense for upstream. We generally go through a design phase before making large changes. +Before participating in our community, please take a moment to review our [code +of conduct](CODE_OF_CONDUCT.md). We expect everyone who interacts with the +project to respect these guidelines. + Pigweed contribution overview: 1. One-time contributor setup: - * Sign the [Contributor License - Agreement](https://cla.developers.google.com/). - * Install the [gerrit commit hook](CONTRIBUTING.md#gerrit-commit-hook) to - automatically add a Change-ID to your CL. + * Sign the [Contributor License Agreement](https://cla.developers.google.com/). + * Install the [Gerrit commit hook](CONTRIBUTING.md#gerrit-commit-hook) to + automatically add a `Change-Id: ...` line to your commit * Install the Pigweed presubmit check hook (`pw presubmit --install`). (recommended) - 2. Ensure all files include a correct [copyright+license - header](CONTRIBUTING.md#source-code-headers). + 2. Ensure all files include a correct [copyright and license header](CONTRIBUTING.md#source-code-headers). 2. Upload the change with `git push origin HEAD:refs/for/master`. 3. Address any reviewer feedback by amending the commit (`git commit --amend`) 4. Submit change to CI builders to merge. @@ -34,7 +36,7 @@ ## Gerrit Commit Hook -Gerrit requires all changes to have a Change-ID tag at the bottom of each CL. +Gerrit requires all changes to have a `Change-Id` tag at the bottom of each CL. You should set this up to be done automatically using the instructions below. **Linux/macOS**<br/> @@ -73,7 +75,7 @@ Apache header for C and C++ files: ```javascript -// Copyright 2019 The Pigweed Authors +// Copyright 2020 The Pigweed Authors // // Licensed under the Apache License, Version 2.0 (the "License"); you may not // use this file except in compliance with the License. You may obtain a copy of @@ -91,7 +93,7 @@ Apache header for Python and GN files: ```python -# Copyright 2019 The Pigweed Authors +# Copyright 2020 The Pigweed Authors # # Licensed under the Apache License, Version 2.0 (the "License"); you may not # use this file except in compliance with the License. You may obtain a copy of
diff --git a/README.md b/README.md index c099ecd..74e8fe8 100644 --- a/README.md +++ b/README.md
@@ -6,13 +6,10 @@ 32-bit microcontrollers like the STMicroelectronics STM32L452 or the Nordic nRF52832. -Pigweed is in the early stages of development, and should be considered -experimental. We’re continuing to evolve the platform and add new modules. We +Pigweed is in the early stages of development, **and should be considered +experimental**. We’re continuing to evolve the platform and add new modules. We value developer feedback along the way. -Pigweed is an open source project with a [code of conduct](CODE_OF_CONDUCT.md) -that we expect everyone who interacts with the project to respect. - # Getting Started If you'd like to get set up with Pigweed, please visit the @@ -22,10 +19,10 @@ There are many modules in Pigweed, and this section only showcases a small selection that happen to produce visual output. For more information about the -different Pigweed module offerings, refer to "modules" section in the full +different Pigweed module offerings, refer to "Module Guides" section in the full documentation. -## pw_watch +## `pw_watch` - Build, flash, run, & test on save In the web development space, file system watchers are prevalent. These watchers trigger a web server reload on source change, making development much faster. In @@ -35,30 +32,31 @@ the full dependency tree, only the exact tests affected by a file change are run on saves. -The demo below shows pw_watch building for a STMicroelectronics STM32F429I-DISC1 -development board, flashing the board with the affected test, and verifying the -test runs as expected. Once this is set up, you can attach multiple devices to -run tests in a distributed manner to reduce the time it takes to run tests. +The demo below shows `pw_watch` building for a STMicroelectronics +STM32F429I-DISC1 development board, flashing the board with the affected test, +and verifying the test runs as expected. Once this is set up, you can attach +multiple devices to run tests in a distributed manner to reduce the time it +takes to run tests.  -## pw_presubmit +## `pw_presubmit` - Vacuum code lint on every commit Presubmit checks are essential tools, but they take work to set up, and projects -don’t always get around to it. The pw_presubmit module provides tools for +don’t always get around to it. The `pw_presubmit` module provides tools for setting up high quality presubmit checks for any project. We use this framework to run Pigweed’s presubmit on our workstations and in our automated building tools. -The pw_presubmit module includes pw format, a tool that provides a unified -interface for automatically formatting code in a variety of languages. With pw -format, you can format C, C++, Python, GN, and Go code according to -configurations defined by your project. pw format leverages existing tools like -clang-format, and it’s simple to add support for new languages. +The `pw_presubmit` module includes `pw format` command, a tool that provides a +unified interface for automatically formatting code in a variety of languages. +With `pw format`, you can format C, C++, Python, GN, and Go code according to +configurations defined by your project. `pw format` leverages existing tools +like `clang-format`, and it’s simple to add support for new languages.  -## pw_env_setup +## `pw_env_setup` - Cross platform embedded compiler setup A classic problem in the embedded space is reducing the time from git clone to having a binary executing on a device. The issue is that an entire suite of @@ -77,7 +75,7 @@ systems development where one frequently needs access to native system resources like USB devices, or must operate on Windows. -env_setup is our compromise solution for this problem that works on Mac, +`pw_env_setup` is our compromise solution for this problem that works on Mac, Windows, and Linux. It leverages the Chrome packaging system CIPD to bootstrap a Python installation, which in turn inflates a virtual environment. The tooling is installed into your workspace, and makes no changes to your system. This @@ -85,38 +83,52 @@  -## pw_unit_test +## `pw_unit_test` - Embedded testing for MCUs Unit testing is important, and Pigweed offers a portable library that’s broadly compatible with [Google Test](https://github.com/google/googletest). Unlike -Google Test, pw_unit_test is built on top of embedded friendly primitives; for +Google Test, `pw_unit_test` is built on top of embedded friendly primitives; for example, it does not use dynamic memory allocation. Additionally, it is easy to port to new target platforms by implementing the [test event handler interface](https://pigweed.googlesource.com/pigweed/pigweed/+/refs/heads/master/pw_unit_test/public/pw_unit_test/event_handler.h). +Like other modules in Pigweed, `pw_unit_test` is designed for use in +established codebases with their own build system, without the rest of Pigweed +or the Pigweed integrated GN build. However, when combined with Pigweed's +build, the result is a flexible and powerful setup that enables easily +developing code on your desktop (with tests), then running the same tests +on-device. +  ## And more! - - **pw_cpu_exception_armv7m**: Robust low level hardware fault handler for ARM +See the "Module Guides" in the documentation for the complete list and +documentation for each, but is a selection of some others: + + - `pw_cpu_exception_armv7m`: Robust low level hardware fault handler for ARM Cortex-M; the handler even has unit tests written in assembly to verify nested-hardware-fault handling! - - **pw_polyfill**: Similar to JavaScript “polyfill” libraries, this module + - `pw_polyfill`: Similar to JavaScript “polyfill” libraries, this module provides selected C++17 standard library components that are compatible with C++11 and C++14. - - **pw_minimal_cpp_stdlib**: An entirely incomplete implementation of the C++17 + - `pw_minimal_cpp_stdlib`: An entirely incomplete implementation of the C++17 standard library, that provides some of the primitives needed by Pigweed itself. Useful for projects that want to use Pigweed, but don’t enable the typical standard C++ libraries like GNU’s libstdc++ or LLVM’s libc++. Don’t use this module unless you know what you are doing. - - **pw_kvs**: A key-value-store implementation for flash-backed persistent + - `pw_tokenizer`: Replace string literals from log statements with 32-bit + tokens, to reduce flash use, reduce logging bandwidth, and save formatting + cycles from log statements at runtime. + + - `pw_kvs`: A key-value-store implementation for flash-backed persistent storage with integrated wear levelling. This is a lightweight alternative to a file system for embedded devices. - - **pw_protobuf**: An early preview of our wire-format-oriented protocol buffer + - `pw_protobuf`: An early preview of our wire-format-oriented protocol buffer implementation. This protobuf compiler makes a different set of implementation tradeoffs than the most popular protocol buffer library in this space, nanopb.
diff --git a/docs/BUILD.gn b/docs/BUILD.gn index 3b5162b..3e8e1b6 100644 --- a/docs/BUILD.gn +++ b/docs/BUILD.gn
@@ -27,7 +27,7 @@ sources = [ "embedded_cpp_guide.rst", "getting_started.md", - "module_guide.rst", + "module_structure.rst", "style_guide.rst", ] } @@ -44,7 +44,7 @@ "../CONTRIBUTING.md", "../README.md", "index.rst", - "modules.rst", + "module_guides.rst", "targets.rst", ] output_directory = target_gen_dir
diff --git a/docs/getting_started.md b/docs/getting_started.md index f328871..21f351d 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md
@@ -4,11 +4,95 @@ We hope to make the setup process as smooth as possible. If any of this doesn't work, please [file a bug](https://bugs.chromium.org/p/pigweed/issues/entry). +## Express setup + +If you're impatient, below is the shorter version of getting setup for Pigweed. +If you run into trouble, look at the more in-depth guide below, starting at +"Prerequisites". The express setup configures Pigweed's watcher for three +targets to give a taste of Pigweed: + +1. **Host** - Mac, Linux, or Windows. Builds and runs tests +2. **Device/STM32F429** - Build only; see later in the guide to run tests on + device +3. **Docs** - Builds the Pigweed docs + +To get setup: + +(1) Make sure you have Git and Python installed and on your path. + +(2) Clone Pigweed and bootstrap the environment (compiler setup & more). **Be + patient, this step downloads ~1GB of LLVM, GCC, and other tooling**. + +```bash +$ cd ~ +$ git clone https://pigweed.googlesource.com/pigweed/pigweed +... +$ cd pigweed +$ . ./bootstrap.sh +... +``` + +(3) Configure the three target GN builds: host, device, and docs. + +```bash +$ gn gen out/host +Done. Made 275 targets from 67 files in 417ms +$ gn gen --args='pw_target_config = "//targets/stm32f429i-disc1/target_config.gni"' out/disco +Done. Made 220 targets from 65 files in 424ms +$ gn gen --args='pw_target_config = "//targets/docs/target_config.gni"' out/docs +Done. Made 284 targets from 65 files in 415ms +``` + +(4) Start the watcher. The watcher will invoke Ninja to build all the targets + +```bash +$ pw watch + + ▒█████▄ █▓ ▄███▒ ▒█ ▒█ ░▓████▒ ░▓████▒ ▒▓████▄ + ▒█░ █░ ░█▒ ██▒ ▀█▒ ▒█░ █ ▒█ ▒█ ▀ ▒█ ▀ ▒█ ▀█▌ + ▒█▄▄▄█░ ░█▒ █▓░ ▄▄░ ▒█░ █ ▒█ ▒███ ▒███ ░█ █▌ + ▒█▀ ░█░ ▓█ █▓ ░█░ █ ▒█ ▒█ ▄ ▒█ ▄ ░█ ▄█▌ + ▒█ ░█░ ░▓███▀ ▒█▓▀▓█░ ░▓████▒ ░▓████▒ ▒▓████▀ + +20200319 01:41:37 INF Starting Pigweed build watcher +20200319 01:41:37 INF Searching for GN build dirs... +20200319 01:41:37 INF Will build [1/3]: out/host +20200319 01:41:37 INF Will build [2/3]: out/disco +20200319 01:41:37 INF Will build [3/3]: out/docs +20200319 01:41:39 INF Directory to watch: $HOME/wrk/pigweed +20200319 01:41:39 INF Watching for file changes. Ctrl-C exits. +20200319 01:41:39 INF Triggering initial build... +... +``` + +(5) **Congratulations, you're ready to go!** Now take Pigweed for a spin with + the below steps. + +(6) With the watcher running in a separate window, edit + `pw_status/status_test.cc` to make an expectation fail; for example, add + `EXPECT_EQ(0, 1);` in a test. + +(7) Save the file. Observe the watcher rebuild & retest, and fail. Restore the + test if you feel like it. + +(8) Open the generated docs in `out/docs/gen/docs/html/index.html` in your + browser. + +(9) Edit `docs/getting_started.md` (this file!) and make any change. Save. See + the watcher rebuild the docs. Reload your browser, and see the changes. + +See below for equivalent Windows commands, and for more details on what each +part does. + +**Note:** After running bootstrap once, use `. ./activate.sh` (or +`activate.bat` on Windows) to re-activate the environment without +re-bootstrapping. + ## Prerequisites **Linux**<br/> -Linux should work out of box, and not require any manual installation of -prerequisites. +Most Linux installations should work out of box, and not require any manual +installation of prerequisites beyond basics like `git` and `build-essential`. **macOS**<br/> macOS does not require any prerequisites to be installed, but you may run into @@ -165,8 +249,7 @@ **Windows** ```batch -> gn gen out/disco -> echo pw_target_config = ^"//targets/stm32f429i-disc1/target_config.gni^">> out\disco\args.gn +> gn gen "pw_target_config = ""//targets/stm32f429i-disc1/target_config.gni""" out/disco ``` Switch to the window running `pw_watch`, and quit using `ctrl+c`. @@ -242,8 +325,7 @@ **Windows** ```batch -> gn gen out/docs -> echo pw_target_config = ^"//targets/docs/target_config.gni^">> out\docs\args.gn +> gn gen --args="pw_target_config = ""//targets/docs/target_config.gni""" out/docs ``` Once again, either restart `pw_watch`, or manually run `ninja -C out/docs`. When
diff --git a/docs/index.rst b/docs/index.rst index c42abc8..d8b5e12 100644 --- a/docs/index.rst +++ b/docs/index.rst
@@ -9,11 +9,11 @@ :hidden: Home <self> + docs/getting_started.md CODE_OF_CONDUCT.md CONTRIBUTING.md - docs/getting_started.md docs/embedded_cpp_guide docs/style_guide - docs/module_guide targets - modules + docs/module_structure + module_guides
diff --git a/docs/modules.rst b/docs/module_guides.rst similarity index 69% rename from docs/modules.rst rename to docs/module_guides.rst index e253c7e..728deff 100644 --- a/docs/modules.rst +++ b/docs/module_guides.rst
@@ -1,8 +1,9 @@ -======= -Modules -======= +============= +Module Guides +============= Pigweed is a collection of embedded-focused and embedded-related modules. -Modules may contain code from multiple languages, including C, C++, and Python. +Modules may contain code from multiple languages, including C, C++, Go, Rust, +Shell, Batch and Python. .. toctree:: :maxdepth: 1
diff --git a/docs/module_guide.rst b/docs/module_structure.rst similarity index 98% rename from docs/module_guide.rst rename to docs/module_structure.rst index 594dc96..5a5858e 100644 --- a/docs/module_guide.rst +++ b/docs/module_structure.rst
@@ -4,9 +4,9 @@ .. _chapter-module-guide: -------------------- -What's in a module? -------------------- +---------------- +Module Structure +---------------- The Pigweed module structure is designed to keep as much code as possible for a particular slice of functionality in one place. That means including the code from multiple languages, as well as all the related documentation and tests.
diff --git a/docs/style_guide.rst b/docs/style_guide.rst index 285ded8..f69f2a3 100644 --- a/docs/style_guide.rst +++ b/docs/style_guide.rst
@@ -208,7 +208,7 @@ .. code-block:: cpp - // Copyright 2019 The Pigweed Authors + // Copyright 2020 The Pigweed Authors // // Licensed under the Apache License, Version 2.0 (the "License"); you may not // use this file except in compliance with the License. You may obtain a copy of
diff --git a/pw_presubmit/docs.rst b/pw_presubmit/docs.rst index a8d1ff1..be568c8 100644 --- a/pw_presubmit/docs.rst +++ b/pw_presubmit/docs.rst
@@ -11,6 +11,22 @@ checking and fixing code format. It also includes the presubmit check script for the Pigweed repository, ``pigweed_presubmit.py``. +Presubmit checks are essential tools, but they take work to set up, and +projects don’t always get around to it. The ``pw_presubmit`` module provides +tools for setting up high quality presubmit checks for any project. We use this +framework to run Pigweed’s presubmit on our workstations and in our automated +building tools. + +The ``pw_presubmit`` module also includes ``pw format``, a tool that provides a +unified interface for automatically formatting code in a variety of languages. +With ``pw format``, you can format C, C++, Python, GN, and Go code according to +configurations defined by your project. ``pw format`` leverages existing tools +like ``clang-format``, and it’s simple to add support for new languages. + +.. image:: ../docs/images/pw_presubmit_demo.gif + :alt: ``pw format`` demo + :align: left + Compatibility ============= Python 3
diff --git a/pw_tokenizer/docs.rst b/pw_tokenizer/docs.rst index 09f742d..1f5005c 100644 --- a/pw_tokenizer/docs.rst +++ b/pw_tokenizer/docs.rst
@@ -578,8 +578,8 @@ TransmitLogMessage(base64_buffer, base64_size); } -War story: deploying tokenized logging to an in-development product -=================================================================== +Deployment war story +==================== The tokenizer module was developed to bring tokenized logging to an in-development product. The product already had an established text-based logging system. Deploying tokenization was straightforward and had substantial