1. Setup#

First things first: install prerequisite software and set up the Sense project.

Getting help

If you get stuck or confused at any point during the Sense tutorial, you’re welcome (and encouraged!) to talk to the Pigweed team in our Discord or issue tracker.

Install prerequisite software#

Prepare your computer for working with Pigweed-based projects:

  1. Complete the instructions in Express setup. You only need to complete the “express setup” instructions; come back to this page once you’re done with the express setup.

Set up the Sense project#

We recommend trying out this tutorial with Visual Studio Code (VS Code). This tutorial will also provide CLI-equivalent workflows if you can’t or don’t want to use VS Code.

  1. Install Visual Studio Code (VS Code).

  2. Clone the project:

    git clone https://pigweed.googlesource.com/pigweed/showcase/sense

  3. Open the Sense project in VS Code. One way to do this is to launch VS Code, click the Open folder link on the landing view, and then select your Sense directory A.K.A. folder.

    Warning

    Don’t use the Add Folder to Workspace workflow or any other workspace-oriented workflow. This project doesn’t play nicely with workspaces yet.

  4. For the Do you trust the authors of the files in this folder? popup click Yes, I trust the authors.

    If you want to try out the project’s building and flashing workflows, you must click Yes, I trust the authors or else the project doesn’t have sufficient permissions to perform these actions. You can still browse the tutorial if you click No, I don’t trust the authors but you won’t be able to do much more than that.

    https://storage.googleapis.com/pigweed-media/sense/trust.png

    Important

    The next few instructions show you how to deal with popups that you may or may not see. If you use VS Code a lot, you may already have the recommended tools and extensions installed, so you won’t see the popups. That’s OK; you can just skip the instructions for popups you didn’t see.

  5. For the Do you want to install the recommended ‘Pigweed’ extension from pigweed for this repository? popup click Install.

    The Pigweed extension is basically the project’s heart. Lots of things depend on this extension being installed.

    https://storage.googleapis.com/pigweed-media/sense/install_pigweed_extension.png

  6. For the popup that starts with Pigweed recommends using Bazelisk to manage your Bazel environment click Default.

    https://storage.googleapis.com/pigweed-media/sense/recommended_bazelisk_settings.png

  7. If you see the popup that starts with Buildifier was not found, open the //.vscode/settings.json file within the Sense repo (not your user settings file) and verify that a bazel.buildifierExecutable setting has been populated. If you see that setting, then Buildifier is set up and you can ignore the popup warning. If you don’t see that setting, then you can follow the instructions in Buildifier setup to set up Buildifier. You can also skip setting up Buildifier; you’ll still be able to complete the tutorial. Some Bazel files just might not get formatted correctly.

    Note

    // means the root directory of your Sense repository. If you cloned Sense to ~/sense, then //.vscode would be located at ~/sense/.vscode.

    https://storage.googleapis.com/pigweed-media/sense/buildifier_not_found.png

    Note

    This warning happens because VS Code doesn’t provide fine-tuned control over the extension loading order. Basically, the Bazel extension loads and it doesn’t detect Buildifier, so it displays that popup warning. But then the Pigweed extension does set up Buildifier soon after. The problem is that there’s no way to specify that the Pigweed extension should load before the Bazel extension.

  8. Make sure you’re running the latest version of the Pigweed extension by opening the Extensions view, going to the page for the Pigweed extension, and checking that your version is v1.3.0 or later.

    https://storage.googleapis.com/pigweed-media/sense/20240802/pigweed_extension.png

    Double-checking the Pigweed extension version#

    Caution

    If you see a legacy version of the Pigweed extension, uninstall it.

  1. Install Bazelisk. Come back to this page once you can successfully run bazelisk --version from your command line. It should print out the version of Bazel that you’re using.

    Note

    See CLI commands: bazelisk versus bazel for an explanation of the difference between Bazel and bazelisk.

  2. Clone the project:

    git clone https://pigweed.googlesource.com/pigweed/showcase/sense

  3. Set your working directory to the project root:

    cd sense

Summary#

Later on, if you decide to build a product on top of Pigweed, you can expect new teammates to onboard onto your codebase using workflows similar to how you just set up Sense.

One interesting thing to note about Bazel-based projects like Sense: no need for --recursive when cloning the repo! I.e. no need for Git submodules. Check out MODULE.bazel in the root directory of the repo to discover more about how dependencies are managed.

Next, head over to 2. Explore build targets to build up your top-down intution about how the Sense project is structured.

Appendix#

Buildifier setup#

The Pigweed extension for VS Code should set up Bazel’s Buildifier for you. If for some reason it doesn’t work, here’s how to set it up manually:

  1. First check //.vscode/settings.json. If you see a bazel.buildifierExecutable entry then the Pigweed extension actually already set up Buildifier correctly and no further work is needed on your part.

  2. Download the latest Buildifier release.

  3. Make sure that the Buildifier binary you download is executable:

    chmod +x buildifier-*

  4. Add a bazel.buildifierExecutable entry in //.vscode/settings.json:

    {
    "...": "...",
    "bazel.buildifierExecutable": "/path/to/buildifier-*-*"
}
On this page