Get started with Pigweed#

Express setup#

Run the following commands, and you should be ready to start developing with Pigweed:

sudo apt install git build-essential
curl -LJo /etc/udev/rules.d/60-openocd.rules https://raw.githubusercontent.com/openocd-org/openocd/master/contrib/60-openocd.rules

Note

If you’re using a Linux distribution that isn’t based on Debian/Ubuntu, see the manual setup directions below for prerequisite installation instructions.

xcode-select --install
pyv=`python3 -c "import sys; v=sys.version_info; print('{0}.{1}'.format(v[0], v[1]))"`; /Applications/Python\ $pyv/Install\ Certificates.command
sudo spctl --master-disable

curl https://pigweed.googlesource.com/pigweed/examples/+/main/tools/setup_windows_prerequisites.bat?format=TEXT > setup_pigweed_prerequisites.b64 && certutil -decode -f setup_pigweed_prerequisites.b64 setup_pigweed_prerequisites.bat && del setup_pigweed_prerequisites.b64
setup_pigweed_prerequisites.bat

This script requires admin privileges.

Note

Due to issues with long file path handling on Windows, Pigweed strongly recommends you clone projects to a short path like C:\projects.

Manual setup with explanations#

This section expands the contents of the express setup into more detailed explanations of Pigweed’s prerequisites. If you have already gone through the Express setup, you don’t need to go through these steps.

Install prerequisites#

Most Linux installations should work out-of-the-box and not require any manual installation of prerequisites beyond basics like git and build-essential (or the equivalent for your distro). If you already do software development, you likely already have these installed.

To ensure you have the necessary prerequisites, you can run the following command on Debian/Ubuntu-based distributions:

sudo apt install git build-essential

The equivalent command on Fedora-based distributions is:

sudo dnf groupinstall "Development Tools"

The equivalent command on Arch-based distributions is:

sudo pacman -S git base-devel

Xcode SDK

Pigweed requires Xcode to build on macOS. While you don’t need the full Xcode SDK, you should at least have xcode-select.

You can install xcode-select with the following command:

xcode-select --install

SSL certificates

Pigweed’s bootstrap process requires a working version of Python that can make HTTPS requests to kickstart the initial dependency fetches. By default, the macOS system Python does not have SSL certificates installed. You can install them with the following commands:

pyv=`python3 -c "import sys; v=sys.version_info; print('{0}.{1}'.format(v[0], v[1]))"`; /Applications/Python\ $pyv/Install\ Certificates.command

  • Install Git. Git must be installed to run from the command line and third-party software or be added to PATH.

  • Install Python.

  • If you plan to flash devices with firmware, you’ll need to install OpenOCD and ensure it’s on your system PATH.

Configure system settings#

To flash devices using OpenOCD, you will need to extend your system udev rules by adding a new configuration file in /etc/udev/rules.d/ that lists the hardware debuggers you’ll be using. The OpenOCD repository has a good example udev rules file that includes many popular hardware debuggers.

Pigweed relies on many tools not downloaded from the App Store. While you may prefer to manually allow individual applications, this may be frustrating or impractical due to the large number of tools required to build Pigweed.

It is usually most practical to globally allow tools not originating from the App Store using the following command:

sudo spctl --master-disable

  • Ensure that Developer Mode is enabled. This can also be done by running the following command as an administrator:

    REG ADD HKLM\Software\Microsoft\Windows\CurrentVersion\AppModelUnlock /t REG_DWORD /v AllowDevelopmentWithoutDevLicense /d 1 /f\""

  • Enable long file paths. This can be done using regedit or by running the following command as an administrator:

    REG ADD HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1 /f

  • Enable Git symlinks:

    git config --global core.symlinks true

Support notes#

Linux is Pigweed’s recommended platform for embedded software development. When developing on Linux, you can enjoy all of Pigweed’s benefits like tokenized logging, automated on-device unit testing, RPC, and rich build system and IDE integrations.

macOS is a well-supported platform for embedded software development with Pigweed. When developing on macOS, you can enjoy the vast majority of benefits of Pigweed like automated on-device unit testing, RPC, and rich build system and IDE integrations.

Due to the nature of OS implementation differences, the following features are not supported on macOS:

Individual modules have the most recent status on OS compatibility, so when in doubt check the documentation for the module of interest.

While Windows is a supported platform for embedded software development with Pigweed, the experience might not be quite as seamless when compared to macOS and Linux. When developing on Windows, you can enjoy most of Pigweed’s features like automated on-device unit testing, RPC, and rich build system and IDE integrations, but you may experience occasional snags along the way.

Long file path issues

Even though Pigweed’s setup process enables long file path handling at a system level, this doesn’t mean that the problem is eliminated. Some applications are hard-coded in ways that cause long file paths to continue to work incorrectly.

For example, MinGW-w64-based GCC toolchains have a long-standing issue with handling long file paths on Windows. Unfortunately, this includes the Windows binaries for Arm’s GNU toolchains.

For this reason, Pigweed strongly recommends cloning projects into a short path like C:\projects. It’s also a good idea to be aware of the length of file paths throughout your project.

Other limitations

Due to the nature of OS implementation differences, the following features are not currently supported on Windows:

Individual modules have the most recent status on OS compatibility, so when in doubt check the documentation for the module of interest.