1.. _module-pw_build-project_builder: 2 3=============== 4Project Builder 5=============== 6.. pigweed-module-subpage:: 7 :name: pw_build 8 9The ``pw_build`` Python module contains a light-weight build command execution 10library used for projects that require running multiple commands to perform a 11build. For example: running ``cmake`` alongside ``gn``. 12 13.. grid:: 3 14 15 .. grid-item-card:: :octicon:`rocket` Get started 16 :link: module-pw_build-project_builder-start 17 :link-type: ref 18 :class-item: sales-pitch-cta-primary 19 20 How to write your own build script. 21 22 .. grid-item-card:: :octicon:`code-square` Reference 23 :link: module-pw_build-project_builder-reference 24 :link-type: ref 25 :class-item: sales-pitch-cta-secondary 26 27 Reference details about the ``pw_build`` Python API. 28 29 .. grid-item-card:: :octicon:`terminal` ``pw build`` CLI 30 :link: module-pw_build-project_builder-cli 31 :link-type: ref 32 :class-item: sales-pitch-cta-secondary 33 34 Command line interface usage. 35 36.. _module-pw_build-project_builder-start: 37 38----------- 39Get Started 40----------- 41The quickest way to get started with Project Builder is to create a build script 42based on existing examples. 43 44Example Build Scripts 45===================== 46Examples of Project Builder based ``pw build`` commands: 47 48- `Upstream Pigweed repo pigweed_upstream_build.py <https://cs.opensource.google/pigweed/pigweed/+/main:pw_build/py/pw_build/pigweed_upstream_build.py>`_ 49- `Examples repo build_project.py <https://cs.opensource.google/pigweed/examples/+/main:tools/sample_project_tools/build_project.py>`_ 50- `Kudzu repo build_project.py <https://pigweed.googlesource.com/pigweed/kudzu/+/refs/heads/main/tools/kudzu_tools/build_project.py>`_ 51 52 53.. _module-pw_build-project_builder-reference: 54 55--------- 56Reference 57--------- 58At a high level: 59 60- A single :py:class:`BuildRecipe <pw_build.build_recipe.BuildRecipe>` 61 contains many :py:class:`BuildCommands <pw_build.build_recipe.BuildCommand>` 62 which are run sequentially. 63- Multiple :py:class:`BuildRecipes <pw_build.build_recipe.BuildRecipe>` can be 64 created and passed into the 65 :py:class:`ProjectBuilder <pw_build.project_builder.ProjectBuilder>` class which 66 provides logging and terminal output options. 67- A :py:class:`ProjectBuilder <pw_build.project_builder.ProjectBuilder>` instance is 68 then passed to the :py:func:`run_builds <pw_build.project_builder.run_builds>` 69 function which allows specifying the number of parallel workers (the number of 70 recipes which are executed in parallel). 71 72.. mermaid:: 73 74 flowchart TB 75 subgraph BuildRecipeA ["<strong>BuildRecipe</strong>: ninja"] 76 buildCommandA1["<strong>BuildCommand</strong><br> gn gen out"] 77 buildCommandA2["<strong>BuildCommand</strong><br> ninja -C out default"] 78 buildCommandA1-->buildCommandA2 79 end 80 81 subgraph BuildRecipeB ["<strong>BuildRecipe</strong>: bazel"] 82 buildCommandB1["<strong>BuildCommand</strong><br> bazel build //...:all"] 83 buildCommandB2["<strong>BuildCommand</strong><br> bazel test //...:all"] 84 buildCommandB1-->buildCommandB2 85 end 86 87 ProjectBuilder["<strong>ProjectBuilder</strong>(build_recipes=...)"] 88 BuildRecipeA-->ProjectBuilder 89 BuildRecipeB-->ProjectBuilder 90 91 run_builds["<strong>run_builds</strong>(project_builder=..., workers=1)"] 92 ProjectBuilder-->run_builds 93 94BuildCommand 95============ 96.. autoclass:: pw_build.build_recipe.BuildCommand 97 98BuildCommand Run Filters 99------------------------ 100.. autofunction:: pw_build.build_recipe.should_gn_gen 101 102.. autofunction:: pw_build.build_recipe.should_gn_gen_with_args 103 104.. autofunction:: pw_build.build_recipe.should_regenerate_cmake 105 106BuildRecipe 107=========== 108.. autoclass:: pw_build.build_recipe.BuildRecipe 109 110ProjectBuilder 111============== 112.. autoclass:: pw_build.project_builder.ProjectBuilder 113 114.. autofunction:: pw_build.project_builder.run_builds 115 116 117.. _module-pw_build-project_builder-cli: 118 119-------------------------------------------------- 120Upstream ``pw build`` Command-Line Interface Usage 121-------------------------------------------------- 122.. argparse:: 123 :module: pw_build.pigweed_upstream_build 124 :func: _build_argument_parser 125 :prog: pw build 126 127 This is the command line interface provided by the ``pw build`` command 128 (`pigweed_upstream_build.py 129 <https://cs.opensource.google/pigweed/pigweed/+/main:pw_build/py/pw_build/pigweed_upstream_build.py>`_) 130 in upstream Pigweed. 131