1.. _seed-0122: 2 3=================================== 40122: Organize Pigweed code samples 5=================================== 6.. seed:: 7 :number: 122 8 :name: Organize Pigweed code samples 9 :status: accepted 10 :proposal_date: 2024-01-09 11 :cl: 187121 12 :authors: Ted Pudlik 13 :facilitator: Kayce Basques 14 15------- 16Summary 17------- 18This SEED describes how Pigweed code samples will be organized. Implementation 19bug: https://pwbug.dev//322816792. 20 21---------- 22Motivation 23---------- 24Pigweed users need to see code samples that demonstrate Pigweed in action. 25However, there are a few different use cases for such code samples. 26Historically, we've not been explicit about what the use cases are, and how 27they should be served. This SEED will fill this gap. 28 29-------- 30Proposal 31-------- 32 33Repositories 34============ 35Pigweed will maintain the following types of code sample repositories: 36 37* **Quickstart**: `minimal, complete, reproducible 38 <https://stackoverflow.com/help/minimal-reproducible-example>`_ projects you 39 can clone to understand the basics of Pigweed and start a new `greenfield 40 project <https://en.wikipedia.org/wiki/Greenfield_project>`_. There will be 41 one Quickstart repository for each build system that Pigweed supports. 42* **Examples**: granular, comprehensive code examples of every Pigweed 43 module's API. The Examples repository can also demonstrate core use cases 44 that require using multiple modules together. There will only be one Examples 45 repository. 46* **Showcase**: Showstopper examples that demonstrate how to use Pigweed 47 to implement complex real-world applications. There will be many Showcase 48 repositories, each demonstrating a different application. These repositories 49 should inspire users, show them how to implement complex integrations, and 50 convince them that Pigweed is the best way to develop embedded projects. 51 52Standard board 53============== 54The Quickstart and Examples repositories will eventually focus on a single 55:ref:`seed-0122-standard-board`. But selecting the standard board is out of the 56scope of this SEED. 57 58--------------- 59Detailed design 60--------------- 61 62.. _seed-0122-quickstart: 63 64Quickstart repository 65===================== 66* **User journeys** these repositories serve: 67 68 * "I want to clone a minimal repository to create my own project from 69 scratch." 70 * "I want to understand the smallest set of steps needed to add Pigweed as a 71 dependency of my own existing project." 72 * "I'm just getting started with Pigweed and want a tutorial that will 73 put *some* code on device". 74 75* **Repository contents**: One repository per build system that demonstrates 76 the minimal set of Pigweed features: 77 78 #. Bootstrapping (downloading required tools, third-party dependencies, etc). 79 #. Building the minimal, viable, complete (MVC) application for 80 :ref:`target-host` and for the :ref:`seed-0122-standard-board`. 81 #. Flashing the application to the board. 82 #. Communicating with the board via :ref:`module-pw_console`. 83 84 Determining the exact content of the MVC app is out-of-scope for this SEED. 85 This is the subject of `SEED-0106 86 <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/155430>`_. 87 However, every Quickstart repository will implement the same set of MVC 88 features. 89 90 There will be tutorial documentation associated with each of these 91 repositories, but it will be hosted in pigweed.git. Documentation generation 92 with :ref:`module-pw_docgen` falls outside the scope of Quickstart. 93 94 We may also add separate Quickstart repositories for boards other than the 95 "standard board". 96 97* **Locations**: 98 99 * https://pigweed.googlesource.com/pigweed/quickstart/bazel.git 100 * https://pigweed.googlesource.com/pigweed/quickstart/gn.git 101 * (No CMake quickstart. We offer support for integrating Pigweed into an 102 existing CMake project, but don't recommend CMake for a greenfield Pigweed 103 project and so have no quickstart repository for it.) 104 105.. _seed-0122-examples: 106 107Examples repository 108=================== 109* **User journeys** this repository serves: 110 111 * "I want to see an example of how a module's API is used in the context of a 112 full, building project." 113 * "I want to use tokenized logging, how do I hook this up?" 114 * "I read you can customize the :ref:`module-pw_console`, can I see an example?" 115 * "I want to see how to configure a backend of this module." 116 * "How do I use method X from Pigweed module Y?" 117 * "How do I use Pigweed modules A and B together?" 118 119* **Repository contents**: One repository that contains a bunch of directories. 120 Each directory is meant to be consulted in isolation. Common use cases such 121 as logging over UART or blinking an LED, may get their own directories. 122 Related examples (e.g., examples for an individual module) may be grouped 123 into a directory hierarchy for clarity. 124 125 The individual examples may define their own build targets, but they are not 126 expected to set up independent builds. They're all part of one top-level build. 127 128 In general, it should be possible to build the examples using all of 129 Pigweed's supported build systems (Bazel, CMake, GN). However, if the 130 functionality being exemplified is only supported in some build systems (e.g. 131 :ref:`module-pw_docgen` is only supported in GN as of this writing), then its 132 examples can be restricted to those build systems. 133 134 Unlike Quickstart, this repository is a reference work: the user is not 135 expected to read through it "from beginning to end". Rather, they will come 136 here to view a specific example. We eventually expect to have hundreds or 137 even thousands of examples. 138 139 The documentation for the Examples repo will be hosted at http://pigweed.dev, 140 but will be built from source within the ``examples.git`` repo. Building 141 documentation using :ref:`module-pw_docgen` is one of the things we're 142 exemplifying. 143 144* **Location**: https://pigweed.googlesource.com/pigweed/examples.git 145 146Showcase repositories 147===================== 148* **User journeys** these repositories serve: 149 150 * "I want to see a cool project built using Pigweed." 151 * "I'm looking for a full-fledged demo of what Pigweed is capable of." 152 * "I'm looking for a Show HN submission." 153 * "I want to convince my team Pigweed is powerful enough for our use case." 154 * "I need proof that Pigweed is a better way to develop embedded projects." 155 * "I need proof that Pigweed is production-ready." 156 157* **Repository contents**: One repository per showcase project. These projects 158 are standalone, with documentation that explains what they do. They're not 159 necessarily easy to stand up yourself, and may require custom hardware that's 160 hard to source. :ref:`Kudzu <docs-blog-01-kudzu>` and `Gonk 161 <https://pigweed.googlesource.com/gonk.git>`_ are examples of showcase 162 projects. 163 164* **Locations**: Showcase projects can be hosted anywhere. Open-source projects 165 created by third parties and not hosted on https://pigweed.googlesource.com 166 can also be showcases. 167 168 We will host a list of Showcase projects, with brief descriptions, at 169 https://pigweed.dev/showcase. 170 171.. _seed-0122-standard-board: 172 173Standard board 174============== 175Pigweed will select a "standard board" for use in our code samples. Today, the 176de facto standard board is the STM32F429I-DISC1, but we expect to select a 177different standard board in the near future. Standard board selection will be 178discussed in a separate followup SEED. 179 180---- 181FAQs 182---- 183 184.. _seed-0122-existing-samples: 185 186How do existing code samples map to this scheme? 187================================================ 188* `example/echo <https://pigweed.googlesource.com/pigweed/example/echo.git>`_ 189 will be renamed to become :ref:`seed-0122-quickstart` for Bazel. 190* `sample_project 191 <https://pigweed.googlesource.com/pigweed/sample_project.git>`_ will be 192 renamed and reorganized to become the :ref:`seed-0122-examples`. 193* `Kudzu <https://pigweed.googlesource.com/pigweed/kudzu.git>`_ and `Gonk 194 <https://pigweed.googlesource.com/gonk.git>`_ are Showcase projects. 195 196 197What about inline code samples in the documentation? 198==================================================== 199We will continue to provide inline code samples in the documentation, and later 200in 2024 may prototype solutions for ensuring they compile and pass assertions. 201But this is out of scope for this SEED. 202 203-------------- 204Open questions 205-------------- 206A followup SEED will discuss the selection of the "standard board" for Pigweed 207Quickstart and Examples repositories. 208 209The exact feature set of the MVC application demonstrated by the Quickstart 210repos is the subject of `SEED-0106 211<https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/155430>`_. 212