Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 1 | .. _docs-faq: |
Keir Mierle | eaa7e92 | 2020-07-24 14:30:47 -0700 | [diff] [blame] | 2 | |
| 3 | -------------------------- |
| 4 | Frequently Asked Questions |
| 5 | -------------------------- |
| 6 | |
| 7 | Is Pigweed a framework? |
| 8 | ----------------------- |
| 9 | There are three core components of Pigweed's offering: |
| 10 | |
| 11 | 1. The environment setup system (bootstrap and activate) |
| 12 | 2. The GN-based build and test system |
| 13 | 3. The individual modules (mostly C++ code) |
| 14 | |
| 15 | We consider #1 and #2 combined as the "Pigweed Monolith" - since it has an |
| 16 | integrated environment setup and build system. However, this part of the system |
| 17 | is entirely optional; it is not only possible, but encouraged to take |
| 18 | individual modules (like for example ``pw_tokenizer`` or ``pw_ring_buffer``) |
| 19 | and integrate them into your existing environment setup approach and build |
| 20 | system. |
| 21 | |
| 22 | So, to answer the question: |
| 23 | |
| 24 | 1. **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. |
| 27 | 2. **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. |
| 30 | 3. **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 | |
| 33 | Isn't C++ bloated and slow? |
| 34 | --------------------------- |
| 35 | In general, no, but it is important to follow some guidelines as discussed in |
Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 36 | the :ref:`Embedded C++ Guide <docs-embedded-cpp>`. |
Keir Mierle | eaa7e92 | 2020-07-24 14:30:47 -0700 | [diff] [blame] | 37 | |
| 38 | At Google, we have made some quantitative analysis of various common embedded |
| 39 | patterns in C++ to evaluate the cost of various constructs. We will open source |
| 40 | this work at some point. |
| 41 | |
| 42 | How 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 | |
| 49 | To use Pigweed, you must decide the answer to one question: Do you wish to use |
| 50 | the Pigweed integrated environment and build, or just use individual modules? |
| 51 | |
| 52 | A la carte: Individual modules only |
| 53 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 54 | This is best option if you have an existing project, with pre-existing build in |
| 55 | place. |
| 56 | |
| 57 | To use the libraries, submodule or copy the relevant Pigweed modules into your |
| 58 | project, and use them like any other C++ library. You can reference the |
| 59 | existing GN files or CMake files when doing this. In the case of CMake, you can |
| 60 | directly import Pigweed's build from your project with CMake's external project |
| 61 | system, or just use a CMake include statement. |
| 62 | |
| 63 | Monolith: Using the integrated system |
| 64 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 65 | This may be a good option if you are starting a new project. However, |
| 66 | there is a gap in our documentation and examples at the moment; sorry about |
| 67 | that! You may need to ask us for help; try the mailing list or chat room. |
| 68 | |
| 69 | Note: Pigweed isn't quite ready for masses of projects to use the whole system |
| 70 | just yet. We will be offering examples and material for this eventually. |
| 71 | |
| 72 | The 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 | |
| 93 | What development hosts are supported? |
| 94 | ------------------------------------- |
| 95 | We 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 | |
| 118 | Partially supported host platform: Chrome OS |
| 119 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 120 | Chromebooks 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 |
| 122 | possible to flash and run on real hardware (like for example the STM32F429i |
| 123 | Discovery). |
| 124 | |
| 125 | To run on ChromeOS: |
| 126 | |
| 127 | 1. `Enable the Linux shell <https://support.google.com/chromebook/answer/9145439>`_ |
| 128 | 2. ``sudo apt-install build-essential`` |
| 129 | 3. Go through Pigweed setup. |
| 130 | |
| 131 | What about other host platforms? |
| 132 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 133 | There are two key issues that make running the host tooling on other platforms |
| 134 | challenging: |
| 135 | |
| 136 | 1. Availability of up-to-date compilers |
| 137 | 2. Availability of up-to-date Python |
| 138 | |
| 139 | For both of these, Pigweed relies on Google-maintained binaries packaged in |
| 140 | CIPD, which includes daily builds of LLVM, and recent versions of the ARM GCC |
| 141 | toolchains. Platforms other than Mac/Windows/Linux running on x86-64 will need |
| 142 | to provide equivalent binaries, which is some effort. |
| 143 | |
| 144 | Host 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 | |
| 152 | Platforms 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 | |
| 159 | Why name the project Pigweed? |
| 160 | ----------------------------- |
| 161 | Pigweed, also known as amaranth, is a nutritious grain and leafy salad green |
| 162 | that is also a rapidly growing weed. When developing the project that |
| 163 | eventually became Pigweed, we wanted to find a name that was fun, playful, and |
| 164 | reflective of how we saw Pigweed growing. Teams would start out using one |
| 165 | module that catches their eye, and after that goes well, they’d quickly start |
| 166 | using more. |
| 167 | |
| 168 | So far, so good 😁 |