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 is best option if you have an existing project, with pre-existing build in 55place. 56 57To use the libraries, submodule or copy the relevant Pigweed modules into your 58project, and use them like any other C++ library. You can reference the 59existing GN files or CMake files when doing this. In the case of CMake, you can 60directly import Pigweed's build from your project with CMake's external project 61system, or just use a CMake include statement. 62 63Monolith: Using the integrated system 64~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 65This may be a good option if you are starting a new project. However, 66there is a gap in our documentation and examples at the moment; sorry about 67that! You may need to ask us for help; try the mailing list or chat room. 68 69Note: Pigweed isn't quite ready for masses of projects to use the whole system 70just yet. We will be offering examples and material for this eventually. 71 72The summary is: 73 74- Create a new repository 75- Add Pigweed as a submodule; we suggest under ``third_party/pigweed`` or 76 ``vendor/pigweed``. It is also possible to use Android's repo tool, but we 77 suggest submodules. 78- Create your own ``BUILD.gn`` and ``BUILDCONFIG.gn``; we suggest starting by 79 copying the ones from Pigweed. You'll need to create your own toplevel 80 targets like those in Pigweed's root ``BUILD.gn``. 81- Create a bootstrap script in your project root that optionally does some 82 project specific setup, then invokes the Pigweed upstream bootstrap (or in 83 the other order). 84- If you have custom hardware, you will want to create a *target*. See the 85 `targets/` directory for examples like the STM32F429i-Discovery. 86 87.. attention:: 88 89 This section is incomplete; if you need help please reach out in chat or on 90 the mailing list. We know this part of Pigweed is incomplete and will help 91 those who are interested in giving Pigweed a try. 92 93What development hosts are supported? 94------------------------------------- 95We support the following platforms: 96 97+-------------------------------+---------------------------------------+ 98| **Development host** | **Comments** | 99+-------------------------------+---------------------------------------+ 100| Linux on x86-64 | Most recent Linux distributions | 101| | will work. | 102+-------------------------------+---------------------------------------+ 103| macOS on x86-64 | Mojave or newer should work. | 104+-------------------------------+---------------------------------------+ 105| Windows 10 on x86-64 | Native Windows only; WSL1 or 2 not | 106| | supported. | 107+-------------------------------+---------------------------------------+ 108| Docker on x86-64 | Containers based on Ubuntu 18.04 | 109| | and newer. | 110+-------------------------------+---------------------------------------+ 111 112.. attention:: 113 114 In all of the above supported platforms, the support is contingent on using 115 Pigweed's bootstrap (env setup) system. While it is possible to use Pigweed 116 without bootstrap, it is unsupported and undocumented at this time. 117 118Partially supported host platform: Chrome OS 119~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 120Chromebooks are able to run some of the Pigweed components; notably all the 121"host" target builds and runs. However, due to USB access issues, it is not 122possible to flash and run on real hardware (like for example the STM32F429i 123Discovery). 124 125To run on ChromeOS: 126 1271. `Enable the Linux shell <https://support.google.com/chromebook/answer/9145439>`_ 1282. ``sudo apt-install build-essential`` 1293. Go through Pigweed setup. 130 131What about other host platforms? 132~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 133There are two key issues that make running the host tooling on other platforms 134challenging: 135 1361. Availability of up-to-date compilers 1372. Availability of up-to-date Python 138 139For both of these, Pigweed relies on Google-maintained binaries packaged in 140CIPD, which includes daily builds of LLVM, and recent versions of the ARM GCC 141toolchains. Platforms other than Mac/Windows/Linux running on x86-64 will need 142to provide equivalent binaries, which is some effort. 143 144Host platforms that we are likely to support in the future 145.......................................................... 146 147- **Linux on ARM** - At time of writing (mid 2020), we do not support ARM-based 148 host platforms. However, we would like to support this eventually. 149- **Windows on WSL2 x86-64** - There are some minor issues preventing WSL2 on 150 Windows from being a smooth experience, but we are working on them. 151 152Platforms that we are unlikely to support 153......................................... 154 155- **Anything on x86-32** - While it's possible 32-bit x86 could be made to 156 work, we don't have enough users to make this worthwhile. If this is 157 something you are interested in and would be willing to support, let us know. 158 159Why name the project Pigweed? 160----------------------------- 161Pigweed, also known as amaranth, is a nutritious grain and leafy salad green 162that is also a rapidly growing weed. When developing the project that 163eventually became Pigweed, we wanted to find a name that was fun, playful, and 164reflective of how we saw Pigweed growing. Teams would start out using one 165module that catches their eye, and after that goes well, they’d quickly start 166using more. 167 168So far, so good �� 169