1.. _docs-getting-started: 2 3=============== 4Getting Started 5=============== 6This guide will walk you through the typical upstream development workflow. 7 8.. note:: 9 10 This documentation and the `sample project 11 <https://pigweed.googlesource.com/pigweed/sample_project/+/main/README.md>`_ 12 show how to use Pigweed as a library in your existing project. Using Pigweed 13 as the foundation for *new* projects is our intended use case, but you may 14 need more guidance than this documentation provides to do that right now. 15 16 We're happy to help you get your project setup; just drop in our `chat room 17 <https://discord.gg/M9NSeTA>`_ or send a note to the `mailing list 18 <https://groups.google.com/forum/#!forum/pigweed>`_. 19 20Express setup 21============= 22If you'd like to skip the detailed explanations, below is the shorter version 23of getting setup for Pigweed. If you run into trouble, look at the more 24in-depth guide below, starting at :ref:`prerequisites`. The express setup 25configures Pigweed's watcher for three targets to give a taste of Pigweed: 26 27#. **Host** - Mac, Linux, or Windows. Builds and runs tests 28#. **Device/STM32F429** - Build only; Optionally, the STM32F429I-DISC1 kit to 29 follow along later in the guide to run tests directly on said device(s) 30#. **Docs** - Builds the Pigweed docs 31 32To get setup: 33 34#. Make sure you have Git and Python installed and on your path. 35 36#. Clone Pigweed and bootstrap the environment (compiler setup & more). **Be 37 patient, this step downloads ~1GB of LLVM, GCC, and other tooling**. 38 39 .. code:: bash 40 41 $ cd ~ 42 $ git clone https://pigweed.googlesource.com/pigweed/pigweed 43 ... 44 $ cd pigweed 45 $ source ./bootstrap.sh (On Linux & Mac) 46 $ bootstrap.bat (On Windows) 47 ... 48 49#. Configure the GN build. 50 51 .. code:: bash 52 53 $ gn gen out 54 Done. Made 1047 targets from 91 files in 114ms 55 56#. Start the watcher. The watcher will invoke Ninja to build all the targets 57 58 .. code:: bash 59 60 $ pw watch 61 62 ▒█████▄ █▓ ▄███▒ ▒█ ▒█ ░▓████▒ ░▓████▒ ▒▓████▄ 63 ▒█░ █░ ░█▒ ██▒ ▀█▒ ▒█░ █ ▒█ ▒█ ▀ ▒█ ▀ ▒█ ▀█▌ 64 ▒█▄▄▄█░ ░█▒ █▓░ ▄▄░ ▒█░ █ ▒█ ▒███ ▒███ ░█ █▌ 65 ▒█▀ ░█░ ▓█ █▓ ░█░ █ ▒█ ▒█ ▄ ▒█ ▄ ░█ ▄█▌ 66 ▒█ ░█░ ░▓███▀ ▒█▓▀▓█░ ░▓████▒ ░▓████▒ ▒▓████▀ 67 68 20200707 17:24:06 INF Starting Pigweed build watcher 69 20200707 17:24:06 INF Will build [1/1]: out 70 20200707 17:24:06 INF Attaching filesystem watcher to $HOME/wrk/pigweed/... 71 20200707 17:24:06 INF Triggering initial build... 72 ... 73 74#. **Congratulations, you're ready to go!** Now take Pigweed for a spin by 75 making a test fail. 76 77#. With the watcher running in a separate window, edit 78 ``pw_status/status_test.cc`` to make an expectation fail; for example, add 79 ``EXPECT_EQ(0, 1);`` in a test. 80 81#. Save the file. Observe the watcher rebuild & retest, and fail. Restore the 82 test if you feel like it. 83 84#. Open the generated docs in ``out/docs/gen/docs/html/index.html`` in your 85 browser. 86 87#. Edit ``docs/getting_started.rst`` (this file!) and make any change. Save. 88 See the watcher rebuild the docs. Reload your browser, and see the changes. 89 90See below for equivalent Windows commands, and for more details on what each 91part does. 92 93**Note:** After running bootstrap once, use ``source ./activate.sh`` (or 94``activate.bat`` on Windows) to re-activate the environment without 95re-bootstrapping. 96 97.. _prerequisites: 98 99Prerequisites 100------------- 101**Linux** 102 103Most Linux installations should work out of box, and not require any manual 104installation of prerequisites beyond basics like ``git`` and 105``build-essential`` (or the equivalent for your distro). 106 107**macOS** 108 109To start using Pigweed on MacOS, you'll need to install XCode. Download it 110via the App Store, then install the relevant tools from the command line. 111 112.. code:: none 113 114 $ xcode-select --install 115 116On macOS you may get SSL certificate errors with the system Python 117installation. Run ``/Applications/Python <default_py_version>/Install Certificates.command`` 118to fix this. If you get SSL 119errors with the Python from `Homebrew <https://brew.sh>`_ try running the 120following commands to ensure Python knows how to use OpenSSL. 121 122.. code:: none 123 124 $ brew install openssl 125 $ brew uninstall python 126 $ brew install python 127 128To flash firmware to a STM32 Discovery development board (and run ``pw test``) 129from macOS, you will need to install OpenOCD. Install 130[Homebrew](https://brew.sh), then install OpenOCD with `brew install openocd`. 131 132**Windows** 133 134To start using Pigweed on Windows, you'll need to do the following: 135 136* Install `Git <https://git-scm.com/download/win>`_. Git must be installed to 137 run from the command line and third-party software or be added to ``PATH``. 138 Also, ensure that the **Enable symbolic links** option is selected. 139* Install `Python <https://www.python.org/downloads/windows/>`_. 140* Ensure that `Developer Mode 141 <https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development>`_ 142 is enabled. 143 144If you plan to flash devices with firmware, you'll need to install OpenOCD and 145ensure it's on your system path. 146 147Bootstrap 148========= 149 150Once you satisfied the prerequisites, you will be able to clone Pigweed and 151run the bootstrap that initializes the Pigweed virtual environment. The 152bootstrap may take several minutes to complete, so please be patient. 153 154**Linux & macOS** 155 156.. code:: bash 157 158 $ git clone https://pigweed.googlesource.com/pigweed/pigweed ~/pigweed 159 $ cd ~/pigweed 160 $ source ./bootstrap.sh 161 162**Windows** 163 164.. code:: batch 165 166 :: Run git commands from the shell you set up to use with Git during install. 167 > git clone https://pigweed.googlesource.com/pigweed/pigweed %HOMEPATH%\pigweed 168 > cd %HOMEPATH%\pigweed 169 > bootstrap.bat 170 171Below is a real-time demo with roughly what you should expect to see as output: 172 173.. image:: images/pw_env_setup_demo.gif 174 :width: 800 175 :alt: build example using pw watch 176 177Congratulations, you are now set up to start using Pigweed! 178 179Pigweed Environment 180=================== 181After going through the initial setup process, your current terminal will be in 182the Pigweed development environment that provides all the tools you should need 183to develop on Pigweed. If you leave that session, you can activate the 184environment in a new session with the following command: 185 186**Linux & macOS** 187 188.. code:: bash 189 190 $ source ./activate.sh 191 192**Windows** 193 194.. code:: batch 195 196 > activate.bat 197 198Some major changes may require triggering the bootstrap again, so if you run 199into host tooling changes after a pull it may be worth re-running bootstrap. 200 201Build Pigweed for Host 202====================== 203Pigweed's primary build system is GN/Ninja based. There are CMake and Bazel 204builds in-development, but they are incomplete and don't have feature parity 205with the GN build. We strongly recommend you stick to the GN build system. 206 207GN (Generate Ninja) just does what it says on the tin; GN generates 208`Ninja <https://ninja-build.org/>`_ build files. 209 210The default GN configuration generates build files that allow you to build host 211binaries, device binaries, and upstream documentation all in one Ninja 212invocation. 213 214Run GN as seen below: 215 216.. code:: bash 217 218 $ gn gen out 219 220Note that ``out`` is simply the directory the build files are saved to. Unless 221this directory is deleted or you desire to do a clean build, there's no need to 222run GN again; just rebuild using Ninja directly. 223 224Now that we have build files, it's time to build Pigweed! 225 226Now you *could* manually invoke the host build using ``ninja -C out`` every 227time you make a change, but that's tedious. Instead, let's use ``pw_watch``. 228 229Go ahead and start ``pw_watch``: 230 231.. code:: bash 232 233 $ pw watch 234 235When ``pw_watch`` starts up, it will automatically build the directory we 236generated in ``out``. Additionally, ``pw_watch`` watches source code files for 237changes, and triggers a Ninja build whenever it notices a file has been saved. 238You might be surprised how much time it can save you! 239 240With ``pw watch`` running, try modifying 241``pw_status/public/pw_status/status.h`` and watch the build re-trigger when you 242save the file. 243 244See below for a demo of this in action: 245 246.. image:: images/pw_watch_build_demo.gif 247 :width: 800 248 :alt: build example using pw watch 249 250Running Unit Tests 251================== 252Fun fact, you've been running the unit tests already! Ninja builds targeting 253the host automatically build and run the unit tests. Unit tests err on the side 254of being quiet in the success case, and only output test results when there's a 255failure. 256 257To see the a test failure, modify ``pw_status/status_test.cc`` to fail by 258changing one of the strings in the "KnownString" test. 259 260.. image:: images/pw_watch_test_demo.gif 261 :width: 800 262 :alt: example test failure using pw watch 263 264Running tests as part of the build isn't particularly expensive because GN 265caches passing tests. Each time you build, only the tests that are affected 266(whether directly or transitively) by the code changes since the last build 267will be re-built and re-run. 268 269Try running the ``pw_status`` test manually: 270 271.. code:: bash 272 273 $ ./out/host_{clang,gcc}_debug/obj/pw_status/test/status_test 274 275Depending on your host OS, the compiler will default to either ``clang`` or 276``gcc``. 277 278Building for a Device 279===================== 280A Pigweed "target" is a build configuration that includes a toolchain, default 281library configurations, and more to result in binaries that run natively on the 282target. With the default build invocation, you're already building for a device 283target (the STMicroelectronics STM32F429I-DISC1) in parallel with the host 284build! 285 286If you want to build JUST for the device, you can kick of watch with: 287 288.. code:: bash 289 290 $ pw watch stm32f429i 291 292This is equivalent to the following Ninja invocation: 293 294.. code:: bash 295 296 $ ninja -C out stm32f429i 297 298Running Tests on a Device 299========================= 300While tests run automatically on the host, it takes a few more steps to get 301tests to run automatically on a device, too. Even though we've verified tests 302pass on the host, it's crucial to verify the same with on-device testing. We've 303encountered some unexpected bugs that can only be found by running the unit 304tests directly on the device. 305 3061. Connect Device(s) 307-------------------- 308Connect any number of STM32F429I-DISC1 boards to your computer using the mini 309USB port on the board (**not** the micro USB). Pigweed will automatically 310detect the boards and distribute the tests across the devices. More boards = 311faster tests! Keep in mind that you may have to make some environment specific 312updates to ensure you have permissions to use the USB device. For example, on 313Linux you may need to update your udev rules and ensure you're in the plugdev 314and dialout groups. 315 316.. image:: images/stm32f429i-disc1_connected.jpg 317 :width: 800 318 :alt: development boards connected via USB 319 3202. Launch Test Server 321--------------------- 322To allow Ninja to run tests on an arbitrary number of devices, Ninja will send 323test requests to a server running in the background. Launch the server in 324another window using the command below (remember, you'll need to activate the 325Pigweed environment first). 326 327.. code:: bash 328 329 $ stm32f429i_disc1_test_server 330 331**Note:** If you attach or detach any more boards to your workstation you'll 332need to relaunch this server. 333 3343. Configure GN 335--------------- 336Tell GN to use the testing server by enabling a build arg specific to the 337stm32f429i-disc1 target. 338 339.. code:: bash 340 341 $ gn args out 342 # Append this line to the file that opens in your editor to tell GN to run 343 # on-device unit tests. 344 pw_use_test_server = true 345 346**Note:** There are several additional dependencies required to test on device: 347libusb-compat, libftdi, and hidapi at the time of writing. On MacOS, these 348dependencies should be installed to the default homebrew location: 349``/usr/local/opt/``. 350 351Done! 352----- 353Whenever you make code changes and trigger a build, all the affected unit tests 354will be run across the attached boards! 355 356See the demo below for an example of what this all looks like put together: 357 358.. image:: images/pw_watch_on_device_demo.gif 359 :width: 800 360 :alt: pw watch running on-device tests 361 362Building the Documentation 363========================== 364In addition to the markdown documentation, Pigweed has a collection of 365information-rich RST files that are used to generate HTML documentation. All 366the docs are hosted at https://pigweed.dev/, and are built as a part of the 367default build invocation. This makes it easier to make changes and see how they 368turn out. Once built, you can find the rendered HTML documentation at 369``out/docs/gen/docs/html``. 370 371You can explicitly build just the documentation with the command below. 372 373.. code:: bash 374 375 $ ninja -C out docs 376 377This concludes the introduction to developing for upstream Pigweed. 378 379Next steps 380========== 381 382Check out other modules 383----------------------- 384If you'd like to see more of what Pigweed has to offer, dive into the 385:ref:`docs-module-guides`. 386 387Check out the sample project 388---------------------------- 389We have a `sample project 390<https://pigweed.googlesource.com/pigweed/sample_project/+/main/README.md>`_ 391that demonstrates how to use Pigweed in your own project. Note that there are 392many ways to leverage Pigweed and the sample project is one approach. 393 394Check out the Hackaday Supercon talk about Pigweed 395-------------------------------------------------- 396We gave a talk at Hackaday's 2021 supercon, `Give Pigweed a Whirl 397<https://hackaday.com/2021/01/13/remoticon-video-pigweed-brings-embedded-unit-testing-library-integration-to-commandline/>`_ 398 399We've made improvements since we gave the talk; for example, we now have RTOS 400primitives. 401 402Set up Pigweed for your own project 403------------------------------------ 404We don't yet have thorough documentation for leveraging Pigweed in a separate 405project (our intended use case!). The `sample project 406<https://pigweed.googlesource.com/pigweed/sample_project/+/main/README.md>`_ 407shows how to use Pigweed as a library in your broader project, but you may need 408further guidance. 409 410Dropping into our `chat room <https://discord.gg/M9NSeTA>`_ is the most 411immediate way to get help. Alternatively, you can send a note to the `mailing 412list <https://groups.google.com/forum/#!forum/pigweed>`_. 413
