third_party/pigweed/repo/docs/faq.rst

   1 .. _docs-faq:
   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
  36 the :ref:`Embedded C++ Guide <docs-embedded-cpp>`.
  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 😁