Update readme and extend Pigweed documentation
Trims setup information out of the README.md, and pushes setup and
developer guides into their own pages.
Change-Id: I7fc80213e6a00c270fc9c664c8a7f54a19c05778
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index ab99c5e..0635e99 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -15,8 +15,15 @@
import("$dir_pw_docgen/docs.gni")
pw_doc_group("core_docs") {
+ inputs = [
+ "images/pw_watch_build_demo.gif",
+ "images/pw_watch_test_demo.gif",
+ "images/stm32f429i-disc1_connected.jpg",
+ ]
sources = [
+ "developer_guide.md",
"embedded_cpp_guide.rst",
+ "setup.md",
"style_guide.rst",
]
}
@@ -29,6 +36,7 @@
pw_doc_gen("docs") {
conf = "conf.py"
sources = [
+ "../CODE_OF_CONDUCT.md",
"../README.md",
"index.rst",
"modules.rst",
diff --git a/docs/conf.py b/docs/conf.py
index 0d72f9c..df8e052 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -39,6 +39,9 @@
extensions = ['sphinx.ext.autodoc', 'm2r']
+# Tell m2r to parse links to .md files and add them to the build.
+m2r_parse_relative_links = True
+
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'sphinx_rtd_theme'
@@ -90,4 +93,4 @@
# Markdown files imported using m2r aren't marked as "referenced," so exclude
# them from the error reference checking.
-exclude_patterns = ['*.md']
+exclude_patterns = ['README.md']
diff --git a/docs/developer_guide.md b/docs/developer_guide.md
new file mode 100644
index 0000000..cd160ad
--- /dev/null
+++ b/docs/developer_guide.md
@@ -0,0 +1,185 @@
+# Pigweed Developer Guide
+
+Pigweed is an assortment of tooling and libraries for embedded projects. One
+of the key goals is that you may chose to use things from Pigweed in an *à la
+carte* fashion. Pigweed is a bundle of helper libraries, but it doesn't provide
+an application image that can be run on a device. Because of this, the binaries
+produced when building upstream Pigweed are unit tests (which can be directly
+flashed to a device and run) and host tools.
+
+If you haven't already, you'll need to go through the [Pigweed setup](setup.md)
+process to ensure you have the necessary tools before running the commands
+throughout this guide.
+
+## Pigweed Environment
+
+After going through the initial setup process, your current terminal will be in
+the Pigweed development environment that provides all the tools you should need
+to develop on Pigweed. If leave that session, you can activate the
+environment in a new session with the following command:
+
+**Linux/macOS**
+```bash
+$ . pw_env_setup/env_setup.sh
+```
+
+**Windows**
+```batch
+> call pw_env_setup\env_setup.bat
+```
+
+This will provide you with GN, Ninja, a host and Cortex-M compiler,
+clang-format, a recent version of Python, a kitted out Python virtual
+environment (venv), and more—all without messing with your current system
+configuration or requiring manual installation.
+
+## Building Pigweed With GN
+
+Pigweed's primary build system is GN/Ninja based. There are
+CMake and Bazel builds in-development, but they are incomplete and don't have
+feature parity with the GN build. We strongly recommend you stick to the GN
+build system.
+
+GN (Generate Ninja) just does what it says on the tin; GN generates
+[Ninja](https://ninja-build.org/) build files.
+
+```bash
+$ gn gen out/host
+```
+
+The default GN build configuration is set up to build with the host as the
+target (more on targets later). Note that `out/host` is the output directory
+that Ninja files are generated to, it doesn't imply any configuration. Now that
+the build files have been generated, you can begin the build using Ninja:
+
+```bash
+$ ninja -C out/host
+```
+
+Whenever you make changes to the source or build files, you only need to run
+`ninja`. Running GN again is only necessary if you delete your build directory
+and need to generate a new one.
+
+No build system is perfect, so you might have the desire to clean your build
+directory if you're doubting the correctness of the build. Doing a clean build
+is relatively simple: delete the build directory `out/[target]`, and
+re-generate it using `gn gen`.
+
+## pw_watch
+
+Manually invoking the build can be tedious, though. You need to switch window
+focus and re-run Ninja. Fortunately, one of Pigweed's modules addresses this!
+pw_watch is a module that watches the Pigweed repository for changes to files
+with certain extensions.
+
+To start pw_watch, simply run `pw watch`:
+
+
+
+Whenever you modify files, pw watch will trigger a build for all the build
+subdirectories found in `out/`. Try it, you might be surprised how much time it
+can save you!
+
+## Running Unit Tests
+
+Fun fact, you've been running the unit tests already! Host builds automatically
+build and run the unit tests. Unit tests err on the side of being quiet in the
+success case, and only output test results when there's a failure. If you want
+to try this out, modify one of the tests to fail:
+
+
+
+Running tests as part of the build isn't particularly expensive because GN
+caches passing tests. Only affected tests are re-built/rerun on a code change
+(thanks to GN's dependency resolution).
+
+## Selecting a Build Target
+
+As mentioned previously, Pigweed builds for host by default. This builds unit
+tests and any host tools. In the context of Pigweed, a Pigweed "target" is a
+build configuration that sets a toolchain, default library configurations,
+and more to result in binaries that may be run natively on the target.
+
+Here are some targets of interest:
+
+ - **Host** (//targets/host/host.gni): Builds unit tests and host tools.
+
+ - **Docs** (//targets/docs/target_config.gni): Builds these docs! This requires
+ a build target because of the binary size reporting automatically generated
+ with the documents.
+
+ - **STM32F429I-DISC1** (//targets/stm32f429i-disc1/target_config.gni): Builds
+ unit tests for STMicroelectronics's Discovery development board (MPN:
+ STM32F429I-DISC1). This is the device Pigweed uses for upstream development.
+ It's a relatively easy to acquire Cortex-M4 development board, and has an
+ integrated STLink to simplify flashing and debugging of the device.
+
+Rather than having tens or hundreds of exposed GN arguments that configure the
+build and are easy to accidentally modify, we use target configuration files
+that only expose arguments relevant to the target. This also makes it easier
+to check in changes to target configurations.
+
+**Setting the build target**
+
+To set the target configuration for a build, set the `pw_target_config` GN build
+arg to point to the target configuration `.gni` file you wish to use.
+
+In this example, we generating Ninja build files for the stm32f429i-disc1.
+```bash
+$ gn gen --args='pw_target_config = "//targets/stm32f429i-disc1/target_config.gni"' out/disco
+```
+
+At this time, you may either run `ninja -C out/disco` or restart pw_watch to
+build for the STM32F429I-DISC1.
+
+## Running Tests on a Device
+
+Even though we've verified tests pass on the host, it's critical to verify the
+same with the board. We've encountered some unexpected bugs that can only be
+found by running the unit tests directly on the device. This section will help
+you get set up to enable on-device testing integrated into the Ninja build
+(pw_watch comptible!) in three simple steps.
+
+### 1. Connect Device(s)
+Connect any number of STM32F429I-DISC1 boards to your computer using the mini
+USB port on the board (**not** the micro USB). Pigweed will automatically detect
+the boards and distribute the tests across the devices. More boards = faster
+tests!
+
+
+
+### 2. Launch Test Server
+To allow Ninja to run tests on an arbitrary number of devices, Ninja will send
+test requests to a server running in the background. Launch the server in
+another window using the command below (remember, you'll need to activate the
+Pigweed env first).
+
+```shell
+ $ stm32f429i_disc1_test_server
+```
+
+**Note:** If you attach or detach any more boards to your workstation you'll
+need to relaunch this server.
+
+### 3. Configure GN
+
+We can tell GN to use the testing server by enabling a build arg specific to
+the stm32f429i-disc1.
+
+```shell
+$ gn args out/disco
+# Modify and save the args file to tell GN to run on-device unit tests.
+pw_use_test_server = true
+```
+
+### Done!
+
+Whenever you make code changes and trigger a build, all the affected unit tests
+will be run across the attached boards!
+
+## Next steps
+
+This concludes the introduction to developing with Pigweed. If you'd like to see
+more of what Pigweed has to offer, feel free to dive into the per-module
+documentation. If you run into snags along the way, please [file
+bugs](https://bugs.chromium.org/p/pigweed/issues/entry)!
diff --git a/docs/images/pw_watch_build_demo.gif b/docs/images/pw_watch_build_demo.gif
new file mode 100644
index 0000000..877d849
--- /dev/null
+++ b/docs/images/pw_watch_build_demo.gif
Binary files differ
diff --git a/docs/images/pw_watch_test_demo.gif b/docs/images/pw_watch_test_demo.gif
new file mode 100644
index 0000000..83a6a0b
--- /dev/null
+++ b/docs/images/pw_watch_test_demo.gif
Binary files differ
diff --git a/docs/images/stm32f429i-disc1_connected.jpg b/docs/images/stm32f429i-disc1_connected.jpg
new file mode 100644
index 0000000..37643b5
--- /dev/null
+++ b/docs/images/stm32f429i-disc1_connected.jpg
Binary files differ
diff --git a/docs/index.rst b/docs/index.rst
index 7643e4d..1b33054 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -9,6 +9,9 @@
:hidden:
Home <self>
+ CODE_OF_CONDUCT.md
+ docs/setup.md
+ docs/developer_guide.md
docs/embedded_cpp_guide
docs/style_guide
targets
diff --git a/docs/setup.md b/docs/setup.md
new file mode 100644
index 0000000..6606a81
--- /dev/null
+++ b/docs/setup.md
@@ -0,0 +1,70 @@
+# Setup
+
+Pigweed uses a combination of CIPD and Python virtual environments to provide
+you with the tools necessary for Pigweed development without modifying your
+system's development environment.
+
+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).
+
+## Prerequisites
+
+**Linux**<br/>
+Linux should work out of box, and not require any manual installation of
+prerequisites.
+
+**macOS**<br/>
+macOS does not require any prerequisites to be installed, but you may run into
+some Mac-specific configuration issues when you begin the bootstrap process.
+
+If you're using Homebrew and you get an error saying
+`module 'http.client' has no attribute 'HTTPSConnection'` then your
+Homebrew Python was not set up to support SSL. Ensure it's installed with
+`brew install openssl` and then run
+`brew uninstall python && brew install python`.
+
+To flash firmware to a STM32 Discovery development board (and run `pw test`)
+from macOS, you will need to install OpenOCD. Install Homebrew using the latest
+instructions at https://brew.sh/, then install OpenOCD with
+`brew install openocd`.
+
+**Windows**<br/>
+To start using Pigweed on Windows, you'll need to install Git and Python (2.7 or
+above). We recommend you install Git to run from the command line and third
+party software.
+
+## Setup
+
+Once you have prerequisites satisfied, you should be able to clone Pigweed and
+run the bootstrap that initializes the Pigweed virtual environment.
+
+**Linux/macOS**
+```bash
+$ git clone sso://pigweed.googlesource.com/pigweed/pigweed ~/pigweed
+$ cd ~/pigweed
+$ pw_env_setup/py/pw_env_setup/cipd_setup/wrapper.py auth-login
+$ . pw_env_setup/bootstrap.sh
+```
+
+**Windows**
+```batch
+:: Run git commands from the shell you set up to use with Git during install.
+> git clone sso://pigweed.googlesource.com/pigweed/pigweed %HOME%\pigweed
+> cd %HOME%\pigweed
+> python pw_env_setup\py\pw_env_setup\cipd_setup\wrapper.py auth-login
+> call pw_env_setup\env_setup.bat
+```
+
+## Contributors
+
+If you plan to contribute to Pigweed, you'll need to set up a commit hook for
+Gerrit.
+
+```bash
+$ f=`git rev-parse --git-dir`/hooks/commit-msg ; mkdir -p $(dirname $f) ; curl -Lo $f https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x $f
+```
+
+
+## Congratulations!
+You should now be set up to start using Pigweed. If you are interested in seeing
+some of what Pigweed can do, check out the [developer guide](developer_guide.md).
