Lines Matching +full:build +full:- +full:docs
1 .. _docs-get-started-upstream:
9 :ref:`docs-get-started` if you're looking for instructions on how to use
22 If you haven't already, :ref:`docs-first-time-setup`.
24 -------------
26 -------------
29 all the steps to :ref:`docs-first-time-setup`. The express setup
32 #. **Host** - Mac, Linux, or Windows. Builds and runs tests
33 #. **Device/STM32F429** - Build only; Optionally, the STM32F429I-DISC1 kit to
35 #. **Docs** - Builds the Pigweed docs
44 .. code-block:: bash
59 #. Configure the GN build.
61 .. code-block:: bash
66 #. Start the watcher. The watcher will invoke Ninja to build all the targets
68 .. code-block:: bash
78 20200707 17:24:06 INF Starting Pigweed build watcher
79 20200707 17:24:06 INF Will build [1/1]: out
81 20200707 17:24:06 INF Triggering initial build...
94 #. Open the generated docs in ``out/docs/gen/docs/html/index.html`` in your
97 #. Edit ``docs/getting_started.rst`` (this file!) and make any change. Save.
98 See the watcher rebuild the docs. Reload your browser, and see the changes.
104 ``activate.bat`` on Windows) to re-activate the environment without
105 re-bootstrapping.
107 ---------
109 ---------
116 .. code-block:: bash
124 .. code-block:: batch
131 Below is a real-time demo with roughly what you should expect to see as output:
133 .. image:: https://storage.googleapis.com/pigweed-media/pw_env_setup_demo.gif
135 :alt: build example using pw watch
139 .. _activate-pigweed-environment:
141 ---------------------------------
143 ---------------------------------
151 .. code-block:: bash
157 .. code-block:: batch
162 into host tooling changes after a pull it may be worth re-running bootstrap.
164 ----------------------
165 Build Pigweed for host
166 ----------------------
167 Pigweed's primary build system is GN/Ninja based. There are CMake and Bazel
168 builds in-development, but they are incomplete and don't have feature parity
169 with the GN build. We strongly recommend you stick to the GN build system.
172 `Ninja <https://ninja-build.org/>`_ build files.
174 The default GN configuration generates build files that allow you to build host
180 .. code-block:: bash
185 ``out`` is simply the directory the build files are saved to. Unless
186 this directory is deleted or you desire to do a clean build, there's no need
190 Unless your build directory (the ``out`` in ``gn gen out``) is exactly one
197 simple, single directory build directories for now.**
199 Now that we have build files, it's time to build Pigweed!
201 Now you *could* manually invoke the host build using ``ninja -C out`` every
206 .. code-block:: bash
210 When ``pw_watch`` starts up, it will automatically build the directory we
212 changes, and triggers a Ninja build whenever it notices a file has been saved.
216 ``pw_status/public/pw_status/status.h`` and watch the build re-trigger when you
221 .. image:: https://storage.googleapis.com/pigweed-media/pw_watch_build_demo.gif
223 :alt: build example using pw watch
225 ------------------
227 ------------------
229 the host automatically build and run the unit tests. Unit tests err on the side
236 .. image:: https://storage.googleapis.com/pigweed-media/pw_watch_test_demo.gif
240 Running tests as part of the build isn't particularly expensive because GN
241 caches passing tests. Each time you build, only the tests that are affected
242 (whether directly or transitively) by the code changes since the last build
243 will be re-built and re-run.
247 .. code-block:: bash
254 ---------------------
256 ---------------------
257 A Pigweed "target" is a build configuration that includes a toolchain, default
259 target. With the default build invocation, you're already building for a device
260 target (the STMicroelectronics STM32F429I-DISC1) in parallel with the host
261 build!
263 If you want to build JUST for the device, you can kick of watch with:
265 .. code-block:: bash
271 .. code-block:: bash
273 $ ninja -C out stm32f429i
275 -------------------------
277 -------------------------
280 pass on the host, it's crucial to verify the same with on-device testing. We've
286 Connect any number of STM32F429I-DISC1 boards to your computer using the mini
294 .. image:: https://storage.googleapis.com/pigweed-media/stm32f429i-disc1_connected.jpg
305 .. code-block:: bash
314 Tell GN to use the testing server by enabling a build arg specific to the
315 stm32f429i-disc1 target.
317 .. code-block:: bash
321 # on-device unit tests.
326 Whenever you make code changes and trigger a build, all the affected unit tests
331 .. image:: https://storage.googleapis.com/pigweed-media/pw_watch_on_device_demo.gif
333 :alt: pw watch running on-device tests
335 --------------------------
337 --------------------------
339 information-rich RST files that are used to generate HTML documentation. All
340 the docs are hosted at https://pigweed.dev/, and are built as a part of the
341 default build invocation. This makes it easier to make changes and see how they
343 ``out/docs/gen/docs/html``.
345 You can explicitly build just the documentation with the command below.
347 .. code-block:: bash
349 $ ninja -C out docs
353 ---------------------------
355 ---------------------------
356 Sometimes it's faster to incrementally build a single test target rather than
357 waiting for the whole world to build and all tests to run. GN has a built-in
358 tool, ``gn outputs``, that will translate a GN build step into a Ninja build
359 step. In order to build and run the right test, it's important to explicitly
360 specify which target to build the test under (e.g. host, SM32F529I-DISC1).
362 after the desired GN build step label as seen in the example below.
364 .. code-block:: none
369 $ ninja -C out pw_strict_host_clang_debug/obj/pw_status/status_test.run.pw_pystamp
373 The ``.run`` following the test target name is a sub-target created as part of
374 the ``pw_test`` GN template. If you remove ``.run``, the test will build but
379 .. code-block:: bash
381 …s:status_test.run(//targets/host/pigweed_internal:pw_strict_host_clang_debug)" | xargs ninja -C out
383 ----------
385 ----------
389 Ready to submit a patch upstream? See our :ref:`docs-contributing` guide for our
394 Visit :ref:`docs-get-started` to learn how to set up a new Bazel-based
395 project, how to add Pigweed to an existing Bazel-based project, and more.
400 :ref:`docs-module-guides`.
402 The :ref:`docs-kudzu` repo demonstrates how to use Pigweed in your own project.
408 Check out the :ref:`module-pw_ide` for setting up editor configurations or run
411 .. code-block:: bash
418 <https://hackaday.com/2021/01/13/remoticon-video-pigweed-brings-embedded-unit-testing-library-integ…