1.. _showcase-sense-tutorial-setup: 2 3======== 41. Setup 5======== 6First things first: install prerequisite software and set up the 7Sense project. 8 9.. _showcase-sense-tutorial-setup-help: 10 11------------ 12Getting help 13------------ 14If you get stuck or confused at any point during the Sense tutorial, you're 15welcome (and encouraged!) to talk to the Pigweed team in our 16`Discord <https://discord.gg/M9NSeTA>`_ or 17`issue tracker <https://pwbug.dev>`_. 18 19.. _showcase-sense-tutorial-setup-prereqs: 20 21----------------------------- 22Install prerequisite software 23----------------------------- 24Prepare your computer for working with Pigweed-based projects: 25 26#. Complete the instructions in :ref:`docs-first-time-setup-guide-express-setup`. 27 **You only need to complete the "express setup" instructions**. 28 29.. _showcase-sense-tutorial-setup-sense: 30 31------------------------ 32Set up the Sense project 33------------------------ 34We recommend trying out this tutorial with Visual Studio Code (VS Code). This 35tutorial will also provide CLI-equivalent workflows if you can't or don't want 36to use VS Code. 37 38.. _Visual Studio Code: https://code.visualstudio.com/Download 39.. _Pigweed extension: https://marketplace.visualstudio.com/items?itemName=pigweed.pigweed-vscode 40.. _Extensions view: https://code.visualstudio.com/docs/editor/extension-marketplace#_browse-for-extensions 41.. _user settings file: https://code.visualstudio.com/docs/getstarted/settings#_settings-file-locations 42 43.. tab-set:: 44 45 .. tab-item:: VS Code 46 :sync: vsc 47 48 #. Install `Visual Studio Code`_ (VS Code). 49 50 #. Clone the project: 51 52 .. code-block:: console 53 54 git clone https://pigweed.googlesource.com/pigweed/showcase/sense 55 56 #. Open the Sense project in VS Code. One way to do this is to 57 launch VS Code, click the **Open folder** link on the landing view, 58 and then select your Sense directory A.K.A. folder. 59 60 .. warning:: 61 62 Don't use the **Add Folder to Workspace** workflow or any other 63 workspace-oriented workflow. This project doesn't play nicely 64 with workspaces yet. 65 66 .. admonition:: Important 67 68 The next few instructions show you how to deal with popups that 69 you **may or may not** see. If you use VS Code a lot, you may 70 already have the recommended tools and extensions installed, so 71 you won't see the popups. That's OK; you can just skip the 72 instructions for popups you didn't see. 73 74 .. admonition:: Troubleshooting 75 76 If you see a popup that says ``spawn bazel ENOENT``, try ignoring it 77 and proceeding with the rest of the tutorial. When the Bazel extension 78 for VS Code starts up, it tries to run queries right away, even though 79 the Bazel environment isn't completely ready yet. The Pigweed extension 80 for VS Code ensures that the Bazel environment sets up properly. 81 82 If the ``spawn bazel ENOENT`` popup seems like a legitimate error, 83 make sure that you have opened the correct folder i.e. directory. 84 If you're still seeing the issue after that, please 85 :ref:`ask the Pigweed team for help <showcase-sense-tutorial-setup-help>`. 86 87 #. If you see the **Do you trust the authors of the files in this folder?** popup 88 click **Yes, I trust the authors**. 89 90 If you want to try out the project's building and flashing workflows, you must 91 click **Yes, I trust the authors** or else the project doesn't have sufficient 92 permissions to perform these actions. You can still browse the tutorial 93 if you click **No, I don't trust the authors** but you won't be able to do 94 much more than that. 95 96 .. figure:: https://storage.googleapis.com/pigweed-media/sense/trust.png 97 98 #. If you see the **Do you want to install the recommended 'Pigweed' extension 99 from pigweed for this repository?** popup click **Install**. 100 101 The Pigweed extension is basically the project's heart. Lots of 102 things depend on this extension being installed. 103 104 .. figure:: https://storage.googleapis.com/pigweed-media/sense/install_pigweed_extension.png 105 106 #. If you see the popup that starts with **Pigweed recommends using Bazelisk to manage your 107 Bazel environment** click **Default**. 108 109 .. figure:: https://storage.googleapis.com/pigweed-media/sense/recommended_bazelisk_settings.png 110 111 #. If you see the popup that starts with **Buildifier was not found**, 112 open the ``//.vscode/settings.json`` file **within the Sense repo** 113 (*not* your `user settings file`_) and verify that a 114 ``bazel.buildifierExecutable`` setting has been populated. If you 115 see that setting, then Buildifier is set up and you can ignore the 116 popup warning. If you don't see that setting, then you can follow 117 the instructions in :ref:`showcase-sense-tutorial-appendix-buildifier` 118 to set up Buildifier. You can also skip setting up Buildifier; you'll 119 still be able to complete the tutorial. Some Bazel files just might 120 not get formatted correctly. 121 122 .. note:: 123 124 ``//`` means the root directory of your Sense repository. 125 If you cloned Sense to ``~/sense``, then ``//.vscode`` would 126 be located at ``~/sense/.vscode``. 127 128 .. figure:: https://storage.googleapis.com/pigweed-media/sense/buildifier_not_found.png 129 130 .. note:: 131 132 This warning happens because VS Code doesn't provide fine-tuned 133 control over the extension loading order. Basically, the Bazel 134 extension loads and it doesn't detect Buildifier, so it displays 135 that popup warning. But then the Pigweed extension does set up 136 Buildifier soon after. The problem is that there's no way to 137 specify that the Pigweed extension should load before the Bazel 138 extension. 139 140 #. Make sure you're running the latest version of the Pigweed extension 141 by opening the `Extensions view`_, going to the page for the Pigweed 142 extension, and checking that your version is ``v1.3.3`` or later. 143 144 .. figure:: https://storage.googleapis.com/pigweed-media/sense/20240802/pigweed_extension.png 145 146 Double-checking the Pigweed extension version 147 148 .. caution:: 149 150 If you see a legacy version of the Pigweed extension, uninstall it. 151 152 .. tab-item:: CLI 153 :sync: cli 154 155 #. :ref:`Install Bazelisk <docs-install-bazel>`. 156 157 .. note:: 158 159 See :ref:`docs-install-bazel-bazelisk` for an explanation of the 160 difference between Bazel and Bazelisk. 161 162 #. Run the following command to verify your Bazelisk installation: 163 164 .. code-block:: console 165 166 bazelisk version 167 168 You should see output similar to this: 169 170 .. code-block:: text 171 172 Bazelisk version: v1.25.0 173 Starting local Bazel server and connecting to it... 174 Build target: @@//src/main/java/com/google/devtools/build/lib/bazel:BazelServer 175 Build time: Thu Jan 01 00:00:00 1970 (0) 176 Build timestamp: Thu Jan 01 00:00:00 1970 (0) 177 Build timestamp as int: 0 178 179 #. Clone the project: 180 181 .. code-block:: console 182 183 git clone https://pigweed.googlesource.com/pigweed/showcase/sense 184 185 #. Set your working directory to the project root: 186 187 .. code-block:: console 188 189 cd sense 190 191------- 192Summary 193------- 194.. _Bazelisk: https://bazel.build/install/bazelisk 195.. _MODULE.bazel: https://cs.opensource.google/pigweed/showcase/sense/+/main:MODULE.bazel 196.. _Bazel modules: https://bazel.build/external/module 197 198Later on, if you decide to build a product on top of Pigweed, you can 199expect new teammates to onboard onto your codebase using workflows 200like this. 201 202.. _--recursive: https://explainshell.com/explain?cmd=git+clone+--recursive 203 204When cloning Sense, did you notice that there was no need for the 205`--recursive`_ flag even though Sense has a few third-party dependencies? 206Most Bazel projects don't need Git submodules. Check out Sense's `MODULE.bazel`_ 207file and read about `Bazel modules`_ to learn more about how dependencies 208are managed in Bazel projects. 209 210Next, head over to :ref:`showcase-sense-tutorial-explore` to build 211up your top-down intution about how the Sense project is structured. 212 213-------- 214Appendix 215-------- 216 217.. _showcase-sense-tutorial-appendix-buildifier: 218 219Buildifier setup 220================ 221The Pigweed extension for VS Code should set up Bazel's Buildifier 222for you. If for some reason it doesn't work, here's how to set it 223up manually: 224 225#. First check ``//.vscode/settings.json``. If you see a 226 ``bazel.buildifierExecutable`` entry then the Pigweed extension 227 actually already set up Buildifier correctly and no further 228 work is needed on your part. 229 230#. Download the latest `Buildifier 231 release <https://github.com/bazelbuild/buildtools/releases>`_. 232 233#. Make sure that the Buildifier binary you download is executable: 234 235 .. code-block:: console 236 237 chmod +x buildifier-* 238 239#. Add a ``bazel.buildifierExecutable`` entry in 240 ``//.vscode/settings.json``: 241 242 .. code-block:: json 243 244 { 245 "...": "...", 246 "bazel.buildifierExecutable": "/path/to/buildifier-*-*" 247 } 248
