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:

Complete the instructions in Express setup. You only need to complete the “express setup” instructions.

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.

VS Code

Install Visual Studio Code (VS Code).

Clone the project:

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

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.

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.

Troubleshooting

If you see a popup that says spawn bazel ENOENT, try ignoring it and proceeding with the rest of the tutorial. When the Bazel extension for VS Code starts up, it tries to run queries right away, even though the Bazel environment isn’t completely ready yet. The Pigweed extension for VS Code ensures that the Bazel environment sets up properly.

If the spawn bazel ENOENT popup seems like a legitimate error, make sure that you have opened the correct folder i.e. directory. If you’re still seeing the issue after that, please ask the Pigweed team for help.
If you see 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.
If you see 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.
If you see the popup that starts with Pigweed recommends using Bazelisk to manage your Bazel environment click Default.
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.

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.
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.3 or later.

Double-checking the Pigweed extension version#

Caution

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

CLI

Install Bazelisk.

Note

See Bazel versus Bazelisk for an explanation of the difference between Bazel and Bazelisk.

Run the following command to verify your Bazelisk installation:

bazelisk version

You should see output similar to this:

Bazelisk version: v1.25.0
Starting local Bazel server and connecting to it...
Build target: @@//src/main/java/com/google/devtools/build/lib/bazel:BazelServer
Build time: Thu Jan 01 00:00:00 1970 (0)
Build timestamp: Thu Jan 01 00:00:00 1970 (0)
Build timestamp as int: 0

Clone the project:

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

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 like this.

When cloning Sense, did you notice that there was no need for the –recursive flag even though Sense has a few third-party dependencies? Most Bazel projects don’t need Git submodules. Check out Sense’s MODULE.bazel file and read about Bazel modules to learn more about how dependencies are managed in Bazel projects.

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:

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.
Download the latest Buildifier release.
Make sure that the Buildifier binary you download is executable:
```
chmod +x buildifier-*
```

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

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