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