1# Getting Started 2 3This guide will walk you through setup and general use of Pigweed. 4We hope to make the setup process as smooth as possible. If any of this doesn't 5work, please [let us know](mailto:pigweed@googlegroups.com). 6 7## Express setup 8 9If you'd like to skip the detailed explanations, below is the shorter version of 10getting setup for Pigweed. If you run into trouble, look at the more in-depth 11guide below, starting at [Prerequisites](getting_started.md#prerequisites). The 12express setup configures Pigweed's watcher for three targets to give a taste of 13Pigweed: 14 151. **Host** - Mac, Linux, or Windows. Builds and runs tests 162. **Device/STM32F429** - Build only; Optionally, the STM32F429I-DISC1 kit to 17 follow along later in the guide to run tests directly on said device(s) 183. **Docs** - Builds the Pigweed docs 19 20To get setup: 21 22(1) Make sure you have Git and Python installed and on your path. 23 24(2) Clone Pigweed and bootstrap the environment (compiler setup & more). **Be 25 patient, this step downloads ~1GB of LLVM, GCC, and other tooling**. 26 27```bash 28$ cd ~ 29$ git clone https://pigweed.googlesource.com/pigweed/pigweed 30... 31$ cd pigweed 32$ source ./bootstrap.sh 33... 34``` 35 36(3) Configure the GN build. 37 38```bash 39$ gn gen out 40Done. Made 1047 targets from 91 files in 114ms 41``` 42 43(4) Start the watcher. The watcher will invoke Ninja to build all the targets 44 45```bash 46$ pw watch 47 48 ▒█████▄ █▓ ▄███▒ ▒█ ▒█ ░▓████▒ ░▓████▒ ▒▓████▄ 49 ▒█░ █░ ░█▒ ██▒ ▀█▒ ▒█░ █ ▒█ ▒█ ▀ ▒█ ▀ ▒█ ▀█▌ 50 ▒█▄▄▄█░ ░█▒ █▓░ ▄▄░ ▒█░ █ ▒█ ▒███ ▒███ ░█ █▌ 51 ▒█▀ ░█░ ▓█ █▓ ░█░ █ ▒█ ▒█ ▄ ▒█ ▄ ░█ ▄█▌ 52 ▒█ ░█░ ░▓███▀ ▒█▓▀▓█░ ░▓████▒ ░▓████▒ ▒▓████▀ 53 5420200707 17:24:06 INF Starting Pigweed build watcher 5520200707 17:24:06 INF Will build [1/1]: out 5620200707 17:24:06 INF Attaching filesystem watcher to $HOME/wrk/pigweed/... 5720200707 17:24:06 INF Triggering initial build... 58... 59``` 60 61(5) **Congratulations, you're ready to go!** Now take Pigweed for a spin with 62 the below steps. 63 64(6) With the watcher running in a separate window, edit 65 `pw_status/status_test.cc` to make an expectation fail; for example, add 66 `EXPECT_EQ(0, 1);` in a test. 67 68(7) Save the file. Observe the watcher rebuild & retest, and fail. Restore the 69 test if you feel like it. 70 71(8) Open the generated docs in `out/docs/gen/docs/html/index.html` in your 72 browser. 73 74(9) Edit `docs/getting_started.md` (this file!) and make any change. Save. See 75 the watcher rebuild the docs. Reload your browser, and see the changes. 76 77See below for equivalent Windows commands, and for more details on what each 78part does. 79 80**Note:** After running bootstrap once, use `source ./activate.sh` (or 81`activate.bat` on Windows) to re-activate the environment without 82re-bootstrapping. 83 84## Prerequisites 85 86**Linux**<br/> 87Most Linux installations should work out of box, and not require any manual 88installation of prerequisites beyond basics like `git` and `build-essential`. 89Make sure gcc is set to gcc-8. 90 91**macOS**<br/> 92To start using Pigweed on MacOS, you'll need to install XCode. Download it 93via the App Store, then install the relevant tools from the command line. 94 95```bash 96xcode-select --install 97``` 98 99On macOS you may get SSL certificate errors with the system Python 100installation. Run `sudo pip install certifi` to fix this. If you get SSL 101errors with the Python from [Homebrew](https://brew.sh) try running the 102following commands to ensure Python knows how to use OpenSSL. 103 104```bash 105brew install openssl 106brew uninstall python 107brew install python 108``` 109 110To flash firmware to a STM32 Discovery development board (and run `pw test`) 111from macOS, you will need to install OpenOCD. Install 112[Homebrew](https://brew.sh), then install OpenOCD with `brew install openocd`. 113 114**Windows**<br/> 115To start using Pigweed on Windows, you'll need to install 116[Git](https://git-scm.com/download/win) and 117[Python](https://www.python.org/downloads/windows/) (2.7 or above). We recommend 118you install Git to run from the command line and third party software. 119 120If you plan to flash devices with firmware, you'll need to install OpenOCD and 121ensure it's on your system path. 122 123## Bootstrap 124 125Once you satisfied the prerequisites, you will be able to clone Pigweed and 126run the bootstrap that initializes the Pigweed virtual environment. The 127bootstrap may take several minutes to complete, so please be patient. 128 129**Linux/macOS** 130```bash 131$ git clone https://pigweed.googlesource.com/pigweed/pigweed ~/pigweed 132$ cd ~/pigweed 133$ source ./bootstrap.sh 134``` 135 136**Windows** 137```batch 138:: Run git commands from the shell you set up to use with Git during install. 139> git clone https://pigweed.googlesource.com/pigweed/pigweed %HOMEPATH%\pigweed 140> cd %HOMEPATH%\pigweed 141> bootstrap.bat 142``` 143 144Below is a real-time demo with roughly what you should expect to see as output: 145 146 147 148Congratulations, you are now set up to start using Pigweed! 149 150## Pigweed Environment 151 152After going through the initial setup process, your current terminal will be in 153the Pigweed development environment that provides all the tools you should need 154to develop on Pigweed. If you leave that session, you can activate the 155environment in a new session with the following command: 156 157**Linux/macOS** 158```bash 159$ source ./activate.sh 160``` 161 162**Windows** 163```batch 164> activate.bat 165``` 166 167Some major changes may require triggering the bootstrap again, so if you run 168into host tooling changes after a pull it may be worth re-running bootstrap. 169 170## Build Pigweed for Host 171 172Pigweed's primary build system is GN/Ninja based. There are CMake and Bazel 173builds in-development, but they are incomplete and don't have feature parity 174with the GN build. We strongly recommend you stick to the GN build system. 175 176GN (Generate Ninja) just does what it says on the tin; GN generates 177[Ninja](https://ninja-build.org/) build files. 178 179The default GN configuration generates build files that allow you to build host 180binaries, device binaries, and upstream documentation all in one Ninja 181invocation. 182 183Run GN as seen below: 184 185```bash 186$ gn gen out 187``` 188 189Note that `out` is simply the directory the build files are saved to. Unless 190this directory is deleted or you desire to do a clean build, there's no need to 191run GN again; just rebuild using Ninja directly. 192 193Now that we have build files, it's time to build Pigweed! 194 195Now you *could* manually invoke the host build using `ninja -C out` every 196time you make a change, but that's tedious. Instead, let's use `pw_watch`. 197 198Go ahead and start `pw_watch`: 199 200```bash 201$ pw watch 202``` 203 204When `pw_watch` starts up, it will automatically build the directory we 205generated in `out`. Additionally, `pw_watch` watches source code files for 206changes, and triggers a Ninja build whenever it notices a file has been saved. 207You might be surprised how much time it can save you! 208 209With `pw watch` running, try modifying `pw_status/public/pw_status/status.h` and 210watch the build re-trigger when you save the file. 211 212See below for a demo of this in action: 213 214 215 216## Running Unit Tests 217 218Fun fact, you've been running the unit tests already! Ninja builds targeting the 219host automatically build and run the unit tests. Unit tests err on the side of 220being quiet in the success case, and only output test results when there's a 221failure. 222 223To see the a test failure, you can modify `pw_status/status_test.cc` to fail 224by changing one of the strings in the "KnownString" test. 225 226 227 228Running tests as part of the build isn't particularly expensive because GN 229caches passing tests. Each time you build, only the tests that are affected 230(whether directly or transitively) by the code changes since the last build will 231be re-built and re-run. 232 233Try running the `pw_status` test manually: 234```bash 235$ ./out/host_{clang,gcc}_debug/obj/pw_status/test/status_test 236``` 237 238Depending on your host OS, the compiler will default to either `clang` or `gcc`. 239 240## Building for a Device 241 242A Pigweed "target" is a build configuration that includes a toolchain, default 243library configurations, and more to result in binaries that run natively on the 244target. With the default build invocation, you're already building for a device 245target (the STMicroelectronics STM32F429I-DISC1) in parallel with the host 246build! 247 248If you want to build JUST for the device, you can kick of watch with: 249 250```bash 251$ pw watch stm32f429i 252``` 253 254This is equivalent to the following Ninja invocation: 255 256```bash 257$ ninja -C out stm32f429i 258``` 259 260 261## Running Tests on a Device 262 263While tests run automatically on the host, it takes a few more steps to get 264tests to run automatically on a device, too. Even though we've verified tests 265pass on the host, it's crucial to verify the same with on-device testing. We've 266encountered some unexpected bugs that can only be found by running the unit 267tests directly on the device. 268 269### 1. Connect Device(s) 270Connect any number of STM32F429I-DISC1 boards to your computer using the mini 271USB port on the board (**not** the micro USB). Pigweed will automatically detect 272the boards and distribute the tests across the devices. More boards = faster 273tests! Keep in mind that you may have to make some environment specific updates 274to ensure you have permissions to use the USB device. For example, on Linux you 275may need to update your udev rules and ensure you're in the plugdev and dialout 276groups. 277 278 279 280### 2. Launch Test Server 281To allow Ninja to run tests on an arbitrary number of devices, Ninja will send 282test requests to a server running in the background. Launch the server in 283another window using the command below (remember, you'll need to activate the 284Pigweed environment first). 285 286```shell 287 $ stm32f429i_disc1_test_server 288``` 289 290**Note:** If you attach or detach any more boards to your workstation you'll 291need to relaunch this server. 292 293### 3. Configure GN 294 295We can tell GN to use the testing server by enabling a build arg specific to 296the stm32f429i-disc1 target. 297 298```shell 299$ gn args out 300# Append this line to the file that opens in your editor to tell GN to run 301# on-device unit tests. 302pw_use_test_server = true 303``` 304 305### Done! 306 307Whenever you make code changes and trigger a build, all the affected unit tests 308will be run across the attached boards! 309 310See the demo below for an example of what this all looks like put together: 311 312 313 314## Building the Documentation 315 316In addition to the markdown documentation, Pigweed has a collection of 317information-rich RST files that are used to generate HTML documentation. All the 318docs are hosted at https://pigweed.dev/, and are built as a part of the default 319build invocation. This makes it easier to make changes and see how they turn 320out. Once built, you can find the rendered HTML documentation at 321`out/docs/gen/docs/html`. 322 323You can explicitly build just the documentation with the command below. 324 325```shell 326$ ninja -C out docs 327``` 328 329## Next steps 330 331This concludes the introduction to developing with Pigweed. If you'd like to see 332more of what Pigweed has to offer, feel free to dive into the per-module 333documentation. If you run into snags along the way, please [let us 334know](mailto:pigweed@googlegroups.com)! 335
