This guide will walk you through setup and general use of Pigweed. We hope to make the setup process as smooth as possible. If any of this doesn't work, please let us know.
If you‘d like to skip the detailed explanations, below is the shorter version of getting setup for Pigweed. If you run into trouble, look at the more in-depth guide below, starting at Prerequisites. The express setup configures Pigweed’s watcher for three targets to give a taste of Pigweed:
To get setup:
(1) Make sure you have Git and Python installed and on your path.
(2) Clone Pigweed and bootstrap the environment (compiler setup & more). Be patient, this step downloads ~1GB of LLVM, GCC, and other tooling.
$ cd ~ $ git clone https://pigweed.googlesource.com/pigweed/pigweed ... $ cd pigweed $ source ./bootstrap.sh ...
(3) Configure the GN build.
$ gn gen out Done. Made 1047 targets from 91 files in 114ms
(4) Start the watcher. The watcher will invoke Ninja to build all the targets
$ pw watch ▒█████▄ █▓ ▄███▒ ▒█ ▒█ ░▓████▒ ░▓████▒ ▒▓████▄ ▒█░ █░ ░█▒ ██▒ ▀█▒ ▒█░ █ ▒█ ▒█ ▀ ▒█ ▀ ▒█ ▀█▌ ▒█▄▄▄█░ ░█▒ █▓░ ▄▄░ ▒█░ █ ▒█ ▒███ ▒███ ░█ █▌ ▒█▀ ░█░ ▓█ █▓ ░█░ █ ▒█ ▒█ ▄ ▒█ ▄ ░█ ▄█▌ ▒█ ░█░ ░▓███▀ ▒█▓▀▓█░ ░▓████▒ ░▓████▒ ▒▓████▀ 20200707 17:24:06 INF Starting Pigweed build watcher 20200707 17:24:06 INF Will build [1/1]: out 20200707 17:24:06 INF Attaching filesystem watcher to $HOME/wrk/pigweed/... 20200707 17:24:06 INF Triggering initial build... ...
(5) Congratulations, you're ready to go! Now take Pigweed for a spin with the below steps.
(6) With the watcher running in a separate window, edit
pw_status/status_test.cc to make an expectation fail; for example, add
EXPECT_EQ(0, 1); in a test.
(7) Save the file. Observe the watcher rebuild & retest, and fail. Restore the test if you feel like it.
(8) Open the generated docs in
out/docs/gen/docs/html/index.html in your browser.
docs/getting_started.md (this file!) and make any change. Save. See the watcher rebuild the docs. Reload your browser, and see the changes.
See below for equivalent Windows commands, and for more details on what each part does.
Note: After running bootstrap once, use
source ./activate.sh (or
activate.bat on Windows) to re-activate the environment without re-bootstrapping.
Most Linux installations should work out of box, and not require any manual installation of prerequisites beyond basics like
build-essential. Make sure gcc is set to gcc-8.
To start using Pigweed on MacOS, you'll need to install XCode. Download it via the App Store, then install the relevant tools from the command line.
On macOS you may get SSL certificate errors with the system Python installation. Run
sudo pip install certifi to fix this. If you get SSL errors with the Python from Homebrew try running the following commands to ensure Python knows how to use OpenSSL.
brew install openssl brew uninstall python brew install python
To flash firmware to a STM32 Discovery development board (and run
pw test) from macOS, you will need to install OpenOCD. Install Homebrew, then install OpenOCD with
brew install openocd.
If you plan to flash devices with firmware, you‘ll need to install OpenOCD and ensure it’s on your system path.
Once you satisfied the prerequisites, you will be able to clone Pigweed and run the bootstrap that initializes the Pigweed virtual environment. The bootstrap may take several minutes to complete, so please be patient.
$ git clone https://pigweed.googlesource.com/pigweed/pigweed ~/pigweed $ cd ~/pigweed $ source ./bootstrap.sh
:: Run git commands from the shell you set up to use with Git during install. > git clone https://pigweed.googlesource.com/pigweed/pigweed %HOMEPATH%\pigweed > cd %HOMEPATH%\pigweed > bootstrap.bat
Below is a real-time demo with roughly what you should expect to see as output:
Congratulations, you are now set up to start using Pigweed!
After going through the initial setup process, your current terminal will be in the Pigweed development environment that provides all the tools you should need to develop on Pigweed. If you leave that session, you can activate the environment in a new session with the following command:
$ source ./activate.sh
Some major changes may require triggering the bootstrap again, so if you run into host tooling changes after a pull it may be worth re-running bootstrap.
Pigweed‘s primary build system is GN/Ninja based. There are CMake and Bazel builds in-development, but they are incomplete and don’t have feature parity with the GN build. We strongly recommend you stick to the GN build system.
GN (Generate Ninja) just does what it says on the tin; GN generates Ninja build files.
The default GN configuration generates build files that allow you to build host binaries, device binaries, and upstream documentation all in one Ninja invocation.
Run GN as seen below:
$ gn gen out
out is simply the directory the build files are saved to. Unless this directory is deleted or you desire to do a clean build, there's no need to run GN again; just rebuild using Ninja directly.
Now that we have build files, it's time to build Pigweed!
Now you could manually invoke the host build using
ninja -C out every time you make a change, but that‘s tedious. Instead, let’s use
Go ahead and start
$ pw watch
pw_watch starts up, it will automatically build the directory we generated in
pw_watch watches source code files for changes, and triggers a Ninja build whenever it notices a file has been saved. You might be surprised how much time it can save you!
pw watch running, try modifying
pw_status/public/pw_status/status.h and watch the build re-trigger when you save the file.
See below for a demo of this in action:
Fun fact, you‘ve been running the unit tests already! Ninja builds targeting the host automatically build and run the unit tests. Unit tests err on the side of being quiet in the success case, and only output test results when there’s a failure.
To see the a test failure, you can modify
pw_status/status_test.cc to fail by changing one of the strings in the “KnownString” test.