1.. _docs-first-time-setup-guide: 2 3======================== 4Get started with Pigweed 5======================== 6 7.. _docs-first-time-setup-guide-express-setup: 8 9------------- 10Express setup 11------------- 12Run the following commands, and you should be ready to start developing with 13Pigweed: 14 15.. _Gatekeeper: https://support.apple.com/guide/security/gatekeeper-and-runtime-protection-sec5599b66df/web 16 17.. tab-set:: 18 19 .. tab-item:: Linux 20 :sync: linux 21 22 .. inclusive-language: disable 23 24 .. code-block:: sh 25 26 sudo apt install git build-essential 27 sudo curl -LJo /etc/udev/rules.d/60-openocd.rules https://raw.githubusercontent.com/openocd-org/openocd/master/contrib/60-openocd.rules 28 29 .. inclusive-language: enable 30 31 .. admonition:: Note 32 :class: tip 33 34 If you're using a Linux distribution that isn't based on Debian/Ubuntu, 35 see the manual setup directions below for prerequisite installation 36 instructions. 37 38 .. tab-item:: macOS 39 :sync: macos 40 41 .. inclusive-language: disable 42 43 .. code-block:: sh 44 45 xcode-select --install 46 sudo spctl --master-disable # Turn off Gatekeeper 47 48 .. inclusive-language: enable 49 50 `Gatekeeper`_ needs to be turned off in order to run the unsigned binaries 51 that Pigweed builds. 52 53 .. tab-item:: Windows 54 :sync: windows 55 56 .. code-block:: bat 57 58 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 59 setup_pigweed_prerequisites.bat 60 61 This script requires admin privileges. 62 63 .. admonition:: Note 64 :class: warning 65 66 Due to issues with long file path handling on Windows, Pigweed strongly 67 recommends you clone projects to a short path like ``C:\projects``. 68 69------------------------------ 70Manual setup with explanations 71------------------------------ 72This section expands the contents of the express setup into more detailed 73explanations of Pigweed's prerequisites. If you have already gone through the 74:ref:`docs-first-time-setup-guide-express-setup`, you don't need to go through 75these steps. 76 77Install prerequisites 78===================== 79 80 81.. tab-set:: 82 83 .. tab-item:: Linux 84 :sync: linux 85 86 Most Linux installations should work out-of-the-box and not require any manual 87 installation of prerequisites beyond basics like ``git`` and 88 ``build-essential`` (or the equivalent for your distro). If you already do 89 software development, you likely already have these installed. 90 91 To ensure you have the necessary prerequisites, you can run the following 92 command on Debian/Ubuntu-based distributions: 93 94 .. code-block:: sh 95 96 sudo apt install git build-essential 97 98 The equivalent command on Fedora-based distributions is: 99 100 .. code-block:: sh 101 102 sudo dnf groupinstall "Development Tools" 103 104 The equivalent command on Arch-based distributions is: 105 106 .. code-block:: sh 107 108 sudo pacman -S git base-devel 109 110 .. tab-item:: macOS 111 :sync: macos 112 113 **Xcode SDK** 114 115 Pigweed requires Xcode to build on macOS. While you don't need the full Xcode 116 SDK, you should at least have ``xcode-select``. 117 118 You can install ``xcode-select`` with the following command: 119 120 .. code-block:: sh 121 122 xcode-select --install 123 124 **SSL certificates** 125 126 Pigweed's bootstrap process requires a working version of Python that can make 127 HTTPS requests to kickstart the initial dependency fetches. By default, the 128 macOS system Python does not have SSL certificates installed. You can install 129 them with the following commands: 130 131 .. code-block:: sh 132 133 pyv=`python3 -c "import sys; v=sys.version_info; print('{0}.{1}'.format(v[0], v[1]))"`; /Applications/Python\ $pyv/Install\ Certificates.command 134 135 .. tab-item:: Windows 136 :sync: windows 137 138 * Install `Git <https://git-scm.com/download/win>`_. Git must be installed to 139 run from the command line and third-party software or be added to ``PATH``. 140 * Install `Python <https://www.python.org/downloads/windows/>`_. 141 * If you plan to flash devices with firmware, you'll need to 142 `install OpenOCD <https://github.com/openocd-org/openocd/releases/latest>`_ 143 and ensure it's on your system PATH. 144 145 146 147Configure system settings 148========================= 149 150.. tab-set:: 151 152 .. tab-item:: Linux 153 :sync: linux 154 155 .. inclusive-language: disable 156 157 To flash devices using `OpenOCD <https://openocd.org/>`_, you will need to 158 extend your system udev rules by adding a new configuration file in 159 ``/etc/udev/rules.d/`` or ``/usr/lib/udev/rules.d`` that lists the 160 hardware debuggers you'll be using. The OpenOCD repository has a good 161 `example udev rules file 162 <https://github.com/openocd-org/openocd/blob/master/contrib/60-openocd.rules>`_ 163 that includes many popular hardware debuggers. 164 165 .. inclusive-language: enable 166 167 .. tab-item:: macOS 168 :sync: macos 169 170 Pigweed relies on many tools not downloaded from the App Store. While you may 171 prefer to manually allow individual applications, this may be frustrating or 172 impractical due to the large number of tools required to build Pigweed. 173 174 It is usually most practical to globally allow tools not originating from the 175 App Store using the following command: 176 177 .. inclusive-language: disable 178 179 .. code-block:: sh 180 181 sudo spctl --master-disable 182 183 .. inclusive-language: enable 184 185 .. tab-item:: Windows 186 :sync: windows 187 188 * Ensure that `Developer Mode 189 <https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development>`_ 190 is enabled. This can also be done by running the following command as an 191 administrator: 192 193 .. code-block:: bat 194 195 REG ADD HKLM\Software\Microsoft\Windows\CurrentVersion\AppModelUnlock /t REG_DWORD /v AllowDevelopmentWithoutDevLicense /d 1 /f\"" 196 197 * Enable long file paths. This can be done using ``regedit`` or by running the 198 following command as an administrator: 199 200 .. code-block:: bat 201 202 REG ADD HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1 /f 203 204 * Enable Git symlinks: 205 206 .. code-block:: bat 207 208 git config --global core.symlinks true 209 210 211------------- 212Support notes 213------------- 214 215.. tab-set:: 216 217 .. tab-item:: Linux 218 :sync: linux 219 220 Linux is Pigweed's recommended platform for embedded software development. When 221 developing on Linux, you can enjoy all of Pigweed's benefits like tokenized 222 logging, automated on-device unit testing, RPC, and rich build system and IDE 223 integrations. 224 225 .. tab-item:: macOS 226 :sync: macos 227 228 macOS is a well-supported platform for embedded software development with 229 Pigweed. When developing on macOS, you can enjoy the vast majority of benefits 230 of Pigweed like automated on-device unit testing, RPC, and rich build system 231 and IDE integrations. 232 233 Due to the nature of OS implementation differences, the following features 234 are not supported on macOS: 235 236 * :ref:`pw_build_info GNU build IDs <module-pw_build_info-gnu-build-ids>`: Not 237 supported when building for macOS, but supported when building for embedded 238 devices. 239 * :ref:`pw_tokenizer string tokenization <module-pw_tokenizer-tokenization>`: 240 Not supported when building for macOS, but supported when building for 241 embedded devices. 242 243 Individual modules have the most recent status on OS compatibility, so when in 244 doubt check the documentation for the module of interest. 245 246 .. tab-item:: Windows 247 :sync: windows 248 249 While Windows is a supported platform for embedded software development with 250 Pigweed, the experience might not be quite as seamless when compared to macOS 251 and Linux. When developing on Windows, you can enjoy most of Pigweed's features 252 like automated on-device unit testing, RPC, and rich build system and IDE 253 integrations, but you may experience occasional snags along the way. 254 255 **Long file path issues** 256 257 Even though Pigweed's setup process enables long file path handling at a system 258 level, this doesn't mean that the problem is eliminated. Some applications are 259 hard-coded in ways that cause long file paths to continue to work incorrectly. 260 261 For example, `MinGW-w64 <https://www.mingw-w64.org/>`_-based GCC toolchains have 262 a `long-standing issue <https://issues.pigweed.dev/300995404>`_ with handling 263 long file paths on Windows. Unfortunately, this includes the Windows binaries 264 for `Arm's GNU toolchains <https://developer.arm.com/downloads/-/gnu-rm>`_. 265 266 For this reason, Pigweed strongly recommends cloning projects into a short path 267 like ``C:\projects``. It's also a good idea to be aware of the length of file 268 paths throughout your project. 269 270 **Other limitations** 271 272 Due to the nature of OS implementation differences, the following features 273 are not currently supported on Windows: 274 275 * Pigweed does not provide integrations for 276 `C++ sanitizers <https://github.com/google/sanitizers/wiki>`_ and 277 `fuzz testing <https://github.com/google/fuzztest?tab=readme-ov-file#fuzztest>`_ 278 on Windows. 279 * :ref:`pw_build_info GNU build IDs <module-pw_build_info-gnu-build-ids>`: Not 280 supported when building for Windows, but supported when building for embedded 281 devices. 282 * :ref:`pw_tokenizer string tokenization <module-pw_tokenizer-tokenization>`: 283 Not supported when building for Windows, but supported when building for 284 embedded devices. 285 286 Individual modules have the most recent status on OS compatibility, so when in 287 doubt check the documentation for the module of interest. 288