Lines Matching +full:- +full:- +full:must +full:- +full:staple
1 .. _docs-build-system:
8 configuration and post-processing of artifacts.
14 See :ref:`docs-python-build` for information about Python build automation with
30 ------------------------------
35 Multi-target builds
36 -------------------
42 designed our build system with first-class multi-target support in mind,
45 Multi-language support
46 ----------------------
49 Additionally, projects may have host-side tooling written in a wide variety of
53 ----------------
54 Embedded projects often require post-processing of build artifacts; these may
62 :ref:`module-pw_tokenizer`)
69 * :ref:`module-pw_build-python-action`
72 ------
74 Pigweed, we're no exception. Much of Pigweed's host-side tooling is written in
81 --------------
85 up-to-date and allows space usage to be tracked over time.
90 * :ref:`module-pw_bloat`
93 -------------
94 An oft-neglected part of software development, documentation is invaluable for
97 size reports, to provide high quality, up-to-date references for developers.
102 * :ref:`module-pw_docgen`
105 ------------
111 Host-side unit tests
118 Device-side unit tests
120 As useful as host-side tests are, they are not sufficient for developing actual
128 * :ref:`module-pw_unit_test`
129 * :ref:`module-pw_target_runner`
132 ---------------
136 things such as unit tests and size reports to re-run whenever any dependent
140 staple of Pigweed development, with most Pigweed users having it permanently
146 * :ref:`module-pw_watch`
152 Pigweed-based projects to choose the most suitable one for them.
154 Of the supported build systems, GN is the most full-featured, followed by CMake,
159 Pigweed)---it can refer to either a GN/Bazel build target, such as a ``source_set``
167 --
168 A perhaps unfamiliar name, `GN (Generate Ninja)`_ is a meta-build system that
173 recommended for Pigweed-based projects where possible.
178 .. _Ninja: https://ninja-build.org/
183 build conventions, and recommendations for Pigweed-based projects. While
191 ---------------
195 ``.gn`` must point to the location of a ``BUILDCONFIG.gn`` file for the project.
210 dir_pw_third_party_nanopb = "//third_party/nanopb-0.4.2"
214 -----------------------------
234 may make sense to define project-specific constants in ``BUILDCONFIG.gn``.
239 .. _top-level-build:
241 Top-level GN targets: //BUILD.gn
242 --------------------------------
257 * ``host`` -- builds ``pigweed_default`` with Clang or GCC, depending on the
259 * ``host_clang`` -- builds ``pigweed_default`` for the host with Clang
260 * ``host_gcc`` -- builds ``pigweed_default`` for the host with GCC
261 * ``stm32f429i`` -- builds ``pigweed_default`` for STM32F429i Discovery board
262 * ``docs`` -- builds the Pigweed documentation and size reports
264 Pigweed projects are recommended to follow this pattern, creating a top-level
296 files. All GN targets added to the build must be placed under one of these
314 * ``debug`` -- create debugging-friendly binaries (``-Og``)
315 * ``size_optimized`` -- optimize for size (``-Os``)
316 * ``speed_optimized`` -- optimized for speed, without increasing code size
317 (``-O2``)
328 In upstream, Pigweed splits its top-level GN targets into a few logical groups,
329 which are described below. In order to build a GN target, it *must* be listed in
334 Pigweed's top-level ``BUILD.gn`` file should not be used by downstream
349 This group defines host-side tooling binaries built for Pigweed.
353 This group defines host-side build targets for Clang runtime sanitizers.
356 * ``asan`` -- `AddressSanitizer`_ is a fast memory error detector.
357 * ``msan`` -- `MemorySanitizer`_ is a detector of uninitialized reads.
358 * ``ubsan`` -- `UndefinedBehaviorSanitizer`_ is a fast undefined behavior detector.
359 * ``ubsan_heuristic`` -- `UndefinedBehaviorSanitizer`_ with the following
363 * ``float-divide-by-zero``: Checks for floating point division by zero.
364 * ``implicit-conversion``: Checks for suspicious behavior of implicit conversions.
369 * ``tsan`` -- `ThreadSanitizer`_ is a tool that detects data races.
409 ----------------------------------
414 ----------------------------------------------------
415 Each Pigweed project must contain a Pigweed configuration file at a known
417 argument, which must be set to the GN build path to the root of the Pigweed
421 ----------------
425 Pigweed's modules, set relative to a project-specific ``dir_pigweed``.
432 # This must be imported before .gni files from any other Pigweed modules. To
433 # prevent gn format from reordering this import, it must be separated by a
439 -----------------------
450 ---------------
454 :ref:`docs-targets`.
457 -------------------
461 described in :ref:`top-level-build` to configure builds for each of their
472 Additionally, there are some cases where GN treats default and non-default
479 GN-based project).
482 -----------------------------
518 ninja -C out
522 is built must be specified on the Ninja command line.
528 ninja -C out host_gcc_debug/obj/foo/bin/foo
556 -----
557 A well-known name in C/C++ development, `CMake`_ is widely used by all kinds of
563 -----
576 build conventions, and recommendations for Pigweed-based projects. While
584 -------------
600 target (e.g. stm32f429i-discovery) a slight variation is required.
605 --platforms=@pigweed//pw_build/platforms:stm32f429i-disc1
618 Bazel's '--run_under' flag. To make this work create a Bazel target
632 bazel test //your:test --platforms=//your/platform --run_under=//your_handler
642 coverage --experimental_generate_llvm_lcov
643 coverage --combined_report=lcov
646 coverage report at the path 'bazel-out/_coverage/_coverage_report.dat'. e.g.
656 lcov --list bazel-out/_coverage/_coverage_report.dat
659 -------------
678 "@platforms//cpu:armv7e-m": [":arm_libs"],
705 building with a wild card for a non-host platform this target will be skipped
710 bazel build //... --platforms=@pigweed//pw_build/platforms:cortex_m0
759 bazel build //:some_target_that_needs_io --//:io=//:some_other_io
763 …reference: https://docs.bazel.build/versions/main/configurable-attributes.html#select-and-dependen…
765 …with reference: https://docs.bazel.build/versions/main/platforms.html#skipping-incompatible-targets
769 .. _docs-build_system-bazel_configuration:
785 :ref:`docs-module-structure-facades` section of :ref:`docs-module-structure`.
841 random micro-controller/FPGA combined with an RTOS. For now let's assume that by
849 --platforms=@pigweed//pw_build/platforms:freertos
858 @pigweed//pw_chrono:pw_chrono_facade <-----------.
869 @pigweed//pw_chrono -------> @pigweed_config//:pw_chrono_system_clock_backend
913 :ref:`docs-module-structure` and now want to implement your own backend for
922 --@pigweed_config//pw_chrono_system_clock_backend=//pw_chrono_my_hardware_rtc:system_clock
928 @pigweed//pw_chrono:pw_chrono_facade <-----.
934 @pigweed//pw_chrono -> @pigweed_config//:pw_chrono_system_clock_backend
948 So continuing on with our scenario, let's say we add a backup micro-controller,
1059 bazel build //:time_is_relative --platforms=//platforms:primary_computer
1065 @pigweed//pw_chrono:pw_chrono_facade <---.
1076 @pigweed//pw_chrono -> @pigweed_config//:pw_chrono_system_clock_backend