1.. _docs-faq: 2 3-------------------------- 4Frequently Asked Questions 5-------------------------- 6 7Is Pigweed a framework? 8----------------------- 9There are three core components of Pigweed's offering: 10 111. The environment setup system (bootstrap and activate) 122. The GN-based build and test system 133. The individual modules (mostly C++ code) 14 15We consider #1 and #2 combined as the "Pigweed Monolith" - since it has an 16integrated environment setup and build system. However, this part of the system 17is entirely optional; it is not only possible, but encouraged to take 18individual modules (like for example ``pw_tokenizer`` or ``pw_ring_buffer``) 19and integrate them into your existing environment setup approach and build 20system. 21 22So, to answer the question: 23 241. **Is Pigweed's environment setup system a framework?** No. This component 25 solves (a) downloading compilers and (b) setting up a Python virtual 26 environment; what you do with the environment is up to you. 272. **Is Pigweed's GN-based build & test setup system a framework?** In short, 28 yes. This is the most framework-like part of Pigweed, since you build your 29 code using Pigweed's GN-based primitives. However, it is optional. 303. **Are Pigweed's C++ modules a framework?** No. They are libraries you can 31 independently take into your project and use like any other C++ library. 32 33Isn't C++ bloated and slow? 34--------------------------- 35In general, no, but it is important to follow some guidelines as discussed in 36the :ref:`Embedded C++ Guide <docs-embedded-cpp>`. 37 38At Google, we have made some quantitative analysis of various common embedded 39patterns in C++ to evaluate the cost of various constructs. We will open source 40this work at some point. 41 42How do I setup Pigweed for my project? 43-------------------------------------- 44 45.. attention:: 46 47 This FAQ entry should be an entire article, but isn't one yet; sorry! 48 49To use Pigweed, you must decide the answer to one question: Do you wish to use 50the Pigweed integrated environment and build, or just use individual modules? 51 52A la carte: Individual modules only 53~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 54This option can work for small projects with a pre-existing build system in 55place. Large projects will probably need a more maintainable and scalable 56solution. 57 58To use the libraries, submodule or copy the relevant Pigweed modules into your 59project, and use them like any other C++ library. You'll need to also copy over 60the `transitive dependencies`_ of any module you use. You can find a module's 61transitive dependencies by inspecting its build files. If your project uses 62CMake, you can directly import Pigweed's build from your project with CMake's 63external project system, or just use a CMake include statement. 64 65.. _transitive dependencies: https://en.wikipedia.org/wiki/Transitive_dependency#Computer_programs 66 67Monolith: Using the integrated system 68~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 69This may be a good option if you are starting a new project. However, 70there is a gap in our documentation and examples at the moment; sorry about 71that! You may need to ask us for help; try the mailing list or chat room. 72 73Note: Pigweed isn't quite ready for masses of projects to use the whole system 74just yet. We will be offering examples and material for this eventually. 75 76The summary is: 77 78- Create a new repository 79- Add Pigweed as a submodule; we suggest under ``third_party/pigweed`` or 80 ``vendor/pigweed``. It is also possible to use Android's repo tool, but we 81 suggest submodules. 82- Create your own ``BUILD.gn`` and ``BUILDCONFIG.gn``; we suggest starting by 83 copying the ones from Pigweed. You'll need to create your own toplevel 84 targets like those in Pigweed's root ``BUILD.gn``. 85- Create a bootstrap script in your project root that optionally does some 86 project specific setup, then invokes the Pigweed upstream bootstrap (or in 87 the other order). 88- If you have custom hardware, you will want to create a *target*. See the 89 `targets/` directory for examples like the STM32F429i-Discovery. 90 91.. attention:: 92 93 This section is incomplete; if you need help please reach out in chat or on 94 the mailing list. We know this part of Pigweed is incomplete and will help 95 those who are interested in giving Pigweed a try. 96 97Why doesn't Pigweed allow shell scripting? 98------------------------------------------ 99Pigweed supports multiple platforms. The native shells on these differ and 100additionally "compatible" shells often have sububle differences in behavior. 101Pigweed uses Python instead of shell scripting wherever practical and changes to 102Pigweed that include shell scripting will likely be rejected. Users of Pigweed 103may use shell scripts in their own code and we have included support for 104`Shellcheck <https://www.shellcheck.net/>`_ during presubmit checks that is 105automatically enabled if ``shellcheck`` found in the path. 106 107What development hosts are supported? 108------------------------------------- 109We support the following platforms: 110 111+-------------------------------+---------------------------------------+ 112| **Development host** | **Comments** | 113+-------------------------------+---------------------------------------+ 114| Linux on x86-64 | Most recent Linux distributions | 115| | will work. | 116+-------------------------------+---------------------------------------+ 117| macOS on arm64 | Support in progress, file bugs for | 118| | any issues. Control whether Rosetta | 119| | is used via ``pigweed.json``. | 120+-------------------------------+---------------------------------------+ 121| macOS on x86-64 | Mojave or newer should work. | 122+-------------------------------+---------------------------------------+ 123| Windows 10 on x86-64 | Native Windows only; WSL1 or 2 not | 124| | supported. | 125+-------------------------------+---------------------------------------+ 126| Docker on x86-64 | Containers based on Ubuntu 18.04 | 127| | and newer. | 128+-------------------------------+---------------------------------------+ 129 130.. attention:: 131 132 In all of the above supported platforms, the support is contingent on using 133 Pigweed's bootstrap (env setup) system. While it is possible to use Pigweed 134 without bootstrap, it is unsupported and undocumented at this time. 135 136Partially supported host platform: Chrome OS 137~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 138Chromebooks are able to run some of the Pigweed components; notably all the 139"host" target builds and runs. However, due to USB access issues, it is not 140possible to flash and run on real hardware (like for example the STM32F429i 141Discovery). 142 143To run on ChromeOS: 144 1451. `Enable the Linux shell <https://support.google.com/chromebook/answer/9145439>`_ 1462. ``sudo apt-install build-essential`` 1473. Go through Pigweed setup. 148 149What about other host platforms? 150~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 151There are two key issues that make running the host tooling on other platforms 152challenging: 153 1541. Availability of up-to-date compilers 1552. Availability of up-to-date Python 156 157For both of these, Pigweed relies on Google-maintained binaries packaged in 158CIPD, which includes daily builds of LLVM, and recent versions of the ARM GCC 159toolchains. Platforms other than Mac/Windows/Linux running on x86-64 will need 160to provide equivalent binaries, which is some effort. 161 162Host platforms that we are likely to support in the future 163.......................................................... 164 165- **Linux on ARM** - We do not support ARM-based Linux host platforms. However, 166 we would like to support this eventually. In many cases we have configured 167 things so packages are downloaded correctly when on this platform 168- **Windows on WSL2 x86-64** - There are some minor issues preventing WSL2 on 169 Windows from being a smooth experience, but we are working on them. 170 171Platforms that we are unlikely to support 172......................................... 173 174- **Anything on x86-32** - While it's possible 32-bit x86 could be made to 175 work, we don't have enough users to make this worthwhile. If this is 176 something you are interested in and would be willing to support, let us know. 177 178Why name the project Pigweed? 179----------------------------- 180Pigweed, also known as amaranth, is a nutritious grain and leafy salad green 181that is also a rapidly growing weed. When developing the project that 182eventually became Pigweed, we wanted to find a name that was fun, playful, and 183reflective of how we saw Pigweed growing. Teams would start out using one 184module that catches their eye, and after that goes well, they’d quickly start 185using more. 186 187So far, so good �� 188