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