Update docs
First pass at docs to bring them up to date with The Great GN Refactor.
More to follow.
Change-Id: I02dc977fcdc7bf3efa8fc9080282dee9b1455cdd
diff --git a/docs/getting_started.md b/docs/getting_started.md
index c09394f..d1fb372 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -33,21 +33,17 @@
...
```
-(3) Configure the three target GN builds: host, device, and docs.
+(3) Configure the GN build.
```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
+$ gn gen out
+Done. Made 1047 targets from 91 files in 114ms
```
(4) Start the watcher. The watcher will invoke Ninja to build all the targets
```bash
-$ pw watch
+$ pw watch out#default#stm32f429i
▒█████▄ █▓ ▄███▒ ▒█ ▒█ ░▓████▒ ░▓████▒ ▒▓████▄
▒█░ █░ ░█▒ ██▒ ▀█▒ ▒█░ █ ▒█ ▒█ ▀ ▒█ ▀ ▒█ ▀█▌
@@ -177,22 +173,23 @@
GN (Generate Ninja) just does what it says on the tin; GN generates
[Ninja](https://ninja-build.org/) build files.
-The default GN configuration generates build files that will result in
-executables that can be run on your host machine.
+The default GN configuration generates build files that allow you to build host
+binaries, device binaries, and upstream documentation all in one Ninja
+invocation.
Run GN as seen below:
```bash
-$ gn gen out/host
+$ gn gen out
```
-Note that `out/host` is simply the directory the build files are saved to.
-Unless this directory is deleted or you desire to do a clean build, there's no
-need to run GN again; just rebuild using Ninja directly.
+Note that `out` is simply the directory the build files are saved to. Unless
+this directory is deleted or you desire to do a clean build, there's no need to
+run GN again; just rebuild using Ninja directly.
Now that we have build files, it's time to build Pigweed!
-Now you *could* manually invoke the host build using `ninja -C out/host` every
+Now you *could* manually invoke the host build using `ninja -C out` every
time you make a change, but that's tedious. Instead, let's use `pw_watch`.
Go ahead and start `pw_watch`:
@@ -202,7 +199,7 @@
```
When `pw_watch` starts up, it will automatically build the directory we
-generated in `out/host`. Additionally, `pw_watch` watches source code files for
+generated in `out`. Additionally, `pw_watch` watches source code files for
changes, and triggers a Ninja build whenever it notices a file has been saved.
You might be surprised how much time it can save you!
@@ -232,34 +229,36 @@
Try running the `pw_status` test manually:
```bash
-$ ./out/host/obj/pw_status/status_test
+$ ./host_[compiler]/obj/pw_status/status_test
```
+Depending on your host OS, `[compiler]` will default to either Clang or GCC.
+
## Building for a Device
As mentioned previously, Pigweed builds for host by default. 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
+Pigweed, a Pigweed "target" is a build configuration that includes a toolchain,
+default library configurations, and more to result in binaries that run
natively on the target.
-Let's generate another build directory, but this time specifying a different
-target:
-
-**Linux/macOS**
-```bash
-$ gn gen --args='pw_target_config = "//targets/stm32f429i-disc1/target_config.gni"' out/disco
-```
-
-**Windows**
-```batch
-> gn gen --args="pw_target_config = ""//targets/stm32f429i-disc1/target_config.gni""" out/disco
-```
-
-Switch to the window running `pw_watch`, and quit using `ctrl+c`.
-To get `pw_watch` to build the new directory as well, re-launch it:
+Switch to the window running `pw_watch`, and quit using `ctrl+c`. To get
+`pw_watch` to build the new STM32F429I-DISC1 target, re-launch by specifying
+which Ninja targets to build:
```bash
-$ pw watch
+$ pw watch out#default#stm32f429i
+```
+
+This is equivalent to the following Ninja invocation:
+
+```bash
+$ ninja -C out default stm32f429i
+```
+
+Or since the "default" target builds host and docs,
+
+```bash
+$ ninja -C out host docs stm32f429i
```
Now `pw_watch` is building for host and a device!
@@ -296,7 +295,7 @@
### 3. Configure GN
We can tell GN to use the testing server by enabling a build arg specific to
-the stm32f429i-disc1.
+the stm32f429i-disc1 target.
```shell
$ gn args out/disco
@@ -316,24 +315,16 @@
## Building the Documentation
-In addition to the markdown documentation, pigweed has a collection of
-information-rich RST files that can be built by adding another build target.
+In addition to the markdown documentation, Pigweed has a collection of
+information-rich RST files that are built by the default invocation of GN. You
+will find the documents at `out/docs/gen/docs/html`.
-To generate documentation build files, invoke GN again:
+You can build the documentation manually by with the command below.
-**Linux/macOS**
-```bash
-$ gn gen --args='pw_target_config = "//targets/docs/target_config.gni"' out/docs
+```shell
+$ ninja -C out docs
```
-**Windows**
-```batch
-> 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
-the build completes, you will find the documents at `out/docs/gen/docs/html`.
-
## Next steps
This concludes the introduction to developing with Pigweed. If you'd like to see
diff --git a/pw_assert_basic/docs.rst b/pw_assert_basic/docs.rst
index 97967f5..bc649d2 100644
--- a/pw_assert_basic/docs.rst
+++ b/pw_assert_basic/docs.rst
@@ -11,5 +11,5 @@
--------
Overview
--------
-This is a simple assert backend to complement the ``pw_assert`` facade.
+This is a simple assert backend to implement the ``pw_assert`` facade.
diff --git a/pw_boot_armv7m/docs.rst b/pw_boot_armv7m/docs.rst
index 1f74216..7bebba6 100644
--- a/pw_boot_armv7m/docs.rst
+++ b/pw_boot_armv7m/docs.rst
@@ -115,8 +115,9 @@
Configuration
=============
-These configuration options can be controlled by appending to
-``pw_boot_armv7m_config.defines`` as part of a Pigweed target config file.
+These configuration options can be controlled by appending list items to
+``pw_boot_armv7m_LINK_CONFIG_DEFINES`` as part of a Pigweed target
+configuration.
``PW_BOOT_HEAP_SIZE`` (required):
How much memory (in bytes) to reserve for the heap. This can be zero.
diff --git a/pw_doctor/docs.rst b/pw_doctor/docs.rst
index 15f0eb3..a9ddd99 100644
--- a/pw_doctor/docs.rst
+++ b/pw_doctor/docs.rst
@@ -6,3 +6,6 @@
``pw doctor`` confirms the environment is set up correctly. With ``--strict``
it checks that things exactly match what is expected and it checks that things
look compatible without.
+
+.. note::
+ The documentation for this module is currently incomplete.
diff --git a/pw_protobuf_compiler/docs.rst b/pw_protobuf_compiler/docs.rst
index 43a4355..e33099e 100644
--- a/pw_protobuf_compiler/docs.rst
+++ b/pw_protobuf_compiler/docs.rst
@@ -29,7 +29,7 @@
| | | point to a local nanopb installation. |
+-------------+------------+---------------------------------------------------+
-The build variable ``pw_protobuf_generators`` tells the module the generators
+The build variable ``pw_protobuf_GENERATORS`` tells the module the generators
for which it should compile code. It is defined as a list of generator codes.
GN template
@@ -45,7 +45,7 @@
.. code::
- pw_protobuf_generators = [ "pwpb", "py" ]
+ pw_protobuf_GENERATORS = [ "pwpb", "py" ]
pw_proto_library("test_protos") {
sources = [ "test.proto" ]
diff --git a/pw_sys_io/docs.rst b/pw_sys_io/docs.rst
index 38b5ef7..c87e0ac 100644
--- a/pw_sys_io/docs.rst
+++ b/pw_sys_io/docs.rst
@@ -35,8 +35,8 @@
This module requires relatively minimal setup:
1. Chose a ``pw_sys_io`` backend, or write one yourself.
- 2. If using GN build, Specify the ``dir_pw_sys_io_backend`` GN global
- variable to point to your ``pw_sys_io`` backend.
+ 2. If using GN build, Specify the ``pw_sys_io_BACKEND`` GN build arg to point
+ the library that provides a ``pw_sys_io`` backend.
Module usage
============
diff --git a/pw_sys_io_stdio/docs.rst b/pw_sys_io_stdio/docs.rst
index d4c1954..31a9357 100644
--- a/pw_sys_io_stdio/docs.rst
+++ b/pw_sys_io_stdio/docs.rst
@@ -26,8 +26,7 @@
This module requires relatively minimal setup:
1. Write code against the ``pw_sys_io`` facade.
- 2. Specify the ``dir_pw_sys_io_backend`` GN global variable to point to this
- backend.
+ 2. Direct the ``pw_sys_io_BACKEND`` GN build arg to point to this backend.
Module usage
============
diff --git a/pw_trace/docs.rst b/pw_trace/docs.rst
index 37e0234..7d5822e 100644
--- a/pw_trace/docs.rst
+++ b/pw_trace/docs.rst
@@ -129,7 +129,7 @@
.. cpp:function:: PW_TRACE_END(label, group_label, trace_id)
Modules
----------
+-------
In addition to these arguments, traces can be grouped into modules similar to
logging. This is done by redefining the ``PW_TRACE_MODULE_NAME``.
@@ -199,9 +199,9 @@
.. cpp:function:: PW_TRACE_FUNCTION()
.. cpp:function:: PW_TRACE_FUNCTION(group_label)
--------------
+-----------
Backend API
--------------
+-----------
Each of the trace event macros get sent to one of two macros which are
implemented by the backend:
diff --git a/pw_unit_test/docs.rst b/pw_unit_test/docs.rst
index a5c93b5..7955f6c 100644
--- a/pw_unit_test/docs.rst
+++ b/pw_unit_test/docs.rst
@@ -113,7 +113,7 @@
Build system integration
^^^^^^^^^^^^^^^^^^^^^^^^
``pw_unit_test`` integrates directly into Pigweed's GN build system. To define
-simple unit tests, set the ``pw_unit_test_main`` build variable to a target
+simple unit tests, set the ``pw_unit_test_MAIN`` build variable to a target
which configures the test framework as described in the :ref:`running-tests`
section, and use the ``pw_test`` template to register your test code.
diff --git a/targets/host/target_docs.rst b/targets/host/target_docs.rst
index 41ff40f..41e879f 100644
--- a/targets/host/target_docs.rst
+++ b/targets/host/target_docs.rst
@@ -17,19 +17,12 @@
.. code:: sh
- $ gn gen --args='pw_target_config = "//targets/host/target_config.gni"' out/host
- $ ninja -C out/host
+ $ ninja -C out host
-or
-
-.. code:: sh
-
- $ gn gen out/host
- $ gn args
- # Modify and save the args file to update the pw_target_config.
- pw_target_config = "//targets/host/target_config.gni"
- $ ninja -C out/host
-
+There are two host toolchains, and both of them can be manually invoked by
+replacing `host` with `host_clang` or `host_gcc`. Not all toolchains are
+supported on all platforms. Unless working specifically on one toolchain, it is
+recommended to leave this to the default.
Running Tests
=============
@@ -40,21 +33,14 @@
... code:: sh
- $ ./out/host/obj/pw_status/status_test
+ $ ./out/host_[compiler]/obj/pw_status/status_test
Configuration
=============
-
The host target exposes a few options that may be used to change the host build
behavior.
-pw_target_toolchain
--------------------
-The toolchain to build Pigweed with may be overriden using this build argument.
-The default toolchain is ``pw_toolchain``'s ``host_gcc_og`` (Linux/Windows) or
-``host_clang_og`` (macOS).
-
-pw_build_host_tools
+pw_build_HOST_TOOLS
-------------------
Pigweed includes a number of host-only tooling that may be built as part of the
host build. These tools are included as part of the bootstrap, so it's only
diff --git a/targets/lm3s6965evb-qemu/target_docs.rst b/targets/lm3s6965evb-qemu/target_docs.rst
index 1ab20e5..0b95d89 100644
--- a/targets/lm3s6965evb-qemu/target_docs.rst
+++ b/targets/lm3s6965evb-qemu/target_docs.rst
@@ -16,27 +16,15 @@
Building
========
-To build for this target, change the ``pw_target_config`` GN build arg to point
-to this target's configuration file.
+To build for this Pigweed target, simply build the top-level "qemu" Ninja
+target.
.. code:: sh
- $ gn gen --args='pw_target_config = "//targets/lm3s6965evb-qemu/target_config.gni"' out/qemu
- $ ninja -C out/qemu
-
-or
-
-.. code:: sh
-
- $ gn gen out/qemu
- $ gn args
- # Modify and save the args file to update the pw_target_config.
- pw_target_config = "//targets/lm3s6965evb-qemu/target_config.gni"
- $ ninja -C out/qemu
+ $ ninja -C out qemu
Testing
=======
-
This target does not yet support automatic test running (though it would be
relatively easy to do so). To run a QEMU binary, see the instructions below.
@@ -45,8 +33,6 @@
When running a QEMU binary, you may chose to run it interactively with GDB, or
allow the binary to run in a hands-off manner.
-Note: qemu-system-arm is not currently provided by the Pigweed environment.
-
Running Without GDB
-------------------
When running without GDB, the firmware will execute normally without requiring
diff --git a/targets/stm32f429i-disc1/target_docs.rst b/targets/stm32f429i-disc1/target_docs.rst
index f556cf0..b2d897b 100644
--- a/targets/stm32f429i-disc1/target_docs.rst
+++ b/targets/stm32f429i-disc1/target_docs.rst
@@ -12,34 +12,23 @@
Building
========
-To build for this target, change the ``pw_target_config`` GN build arg to point
-to this target's configuration file.
+To build for this Pigweed target, simply build the top-level "stm32f429i" Ninja
+target.
.. code:: sh
- $ gn gen --args='pw_target_config = "//targets/stm32f429i-disc1/target_config.gni"' out/disco
- $ ninja -C out/disco
-
-or
-
-.. code:: sh
-
- $ gn gen out/disco
- $ gn args
- # Modify and save the args file to update the pw_target_config.
- pw_target_config = "//targets/stm32f429i-disc1/target_config.gni"
- $ ninja -C out/disco
+ $ ninja -C out stm32f429i
Testing
=======
-The default Pigweed build target will build all Pigweed modules' unit tests.
+When working in upstream Pigweed, building this target will build all Pigweed modules' unit tests.
These tests can be run on-device in a few different ways.
Run a unit test
---------------
If using ``out/disco`` as a build directory, tests will be located in
-``out/disco/obj/[module name]/[test_name].elf``. To run these on device, the
-stm32f429i-disc1 target provides a helper script that flashes the test to a
+``out/stm32f429i/obj/[module name]/[test_name].elf``. To run these on device,
+the stm32f429i-disc1 target provides a helper script that flashes the test to a
device and then runs it.
.. code:: sh
@@ -63,7 +52,7 @@
# Setup Pigweed environment.
$ . pw_env_setup/setup.sh
# Run test.
- $ pw test --root out/disco/ --runner stm32f429i_disc1_unit_test_runner
+ $ pw test --root out/stm32f429i/ --runner stm32f429i_disc1_unit_test_runner
Run tests affected by code changes
----------------------------------
@@ -108,6 +97,6 @@
Step 3: Build changes
^^^^^^^^^^^^^^^^^^^^^
-Whenever you run ``ninja -C out/disco``, affected tests will be built and run on
-the attached device(s). Alternatively, you may use ``pw watch`` to set up
+Whenever you run ``ninja -C out stm32f429i``, affected tests will be built and
+run on the attached device(s). Alternatively, you may use ``pw watch`` to set up
Pigweed to build/test whenever it sees changes to source files.
