docs: Add FAQ section
Change-Id: Ia45a4ec0dcae0279b6ebc9bc542377f154f7a0b2
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/14780
Reviewed-by: David Rogers <davidrogers@google.com>
Commit-Queue: Keir Mierle <keir@google.com>
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index 60194ff..ea6935a 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -28,6 +28,7 @@
]
sources = [
"embedded_cpp_guide.rst",
+ "faq.rst",
"getting_started.md",
"module_structure.rst",
"style_guide.rst",
diff --git a/docs/faq.rst b/docs/faq.rst
new file mode 100644
index 0000000..090c08e
--- /dev/null
+++ b/docs/faq.rst
@@ -0,0 +1,168 @@
+.. _chapter-faq:
+
+--------------------------
+Frequently Asked Questions
+--------------------------
+
+Is Pigweed a framework?
+-----------------------
+There are three core components of Pigweed's offering:
+
+1. The environment setup system (bootstrap and activate)
+2. The GN-based build and test system
+3. The individual modules (mostly C++ code)
+
+We consider #1 and #2 combined as the "Pigweed Monolith" - since it has an
+integrated environment setup and build system. However, this part of the system
+is entirely optional; it is not only possible, but encouraged to take
+individual modules (like for example ``pw_tokenizer`` or ``pw_ring_buffer``)
+and integrate them into your existing environment setup approach and build
+system.
+
+So, to answer the question:
+
+1. **Is Pigweed's environment setup system a framework?** No. This component
+ solves (a) downloading compilers and (b) setting up a Python virtual
+ environment; what you do with the environment is up to you.
+2. **Is Pigweed's GN-based build & test setup system a framework?** In short,
+ yes. This is the most framework-like part of Pigweed, since you build your
+ code using Pigweed's GN-based primitives. However, it is optional.
+3. **Are Pigweed's C++ modules a framework?** No. They are libraries you can
+ independently take into your project and use like any other C++ library.
+
+Isn't C++ bloated and slow?
+---------------------------
+In general, no, but it is important to follow some guidelines as discussed in
+the :ref:`Embedded C++ Guide <chapter-embedded-cpp>`.
+
+At Google, we have made some quantitative analysis of various common embedded
+patterns in C++ to evaluate the cost of various constructs. We will open source
+this work at some point.
+
+How do I setup Pigweed for my project?
+--------------------------------------
+
+.. attention::
+
+ This FAQ entry should be an entire article, but isn't one yet; sorry!
+
+To use Pigweed, you must decide the answer to one question: Do you wish to use
+the Pigweed integrated environment and build, or just use individual modules?
+
+A la carte: Individual modules only
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This is best option if you have an existing project, with pre-existing build in
+place.
+
+To use the libraries, submodule or copy the relevant Pigweed modules into your
+project, and use them like any other C++ library. You can reference the
+existing GN files or CMake files when doing this. In the case of CMake, you can
+directly import Pigweed's build from your project with CMake's external project
+system, or just use a CMake include statement.
+
+Monolith: Using the integrated system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This may be a good option if you are starting a new project. However,
+there is a gap in our documentation and examples at the moment; sorry about
+that! You may need to ask us for help; try the mailing list or chat room.
+
+Note: Pigweed isn't quite ready for masses of projects to use the whole system
+just yet. We will be offering examples and material for this eventually.
+
+The summary is:
+
+- Create a new repository
+- Add Pigweed as a submodule; we suggest under ``third_party/pigweed`` or
+ ``vendor/pigweed``. It is also possible to use Android's repo tool, but we
+ suggest submodules.
+- Create your own ``BUILD.gn`` and ``BUILDCONFIG.gn``; we suggest starting by
+ copying the ones from Pigweed. You'll need to create your own toplevel
+ targets like those in Pigweed's root ``BUILD.gn``.
+- Create a bootstrap script in your project root that optionally does some
+ project specific setup, then invokes the Pigweed upstream bootstrap (or in
+ the other order).
+- If you have custom hardware, you will want to create a *target*. See the
+ `targets/` directory for examples like the STM32F429i-Discovery.
+
+.. attention::
+
+ This section is incomplete; if you need help please reach out in chat or on
+ the mailing list. We know this part of Pigweed is incomplete and will help
+ those who are interested in giving Pigweed a try.
+
+What development hosts are supported?
+-------------------------------------
+We support the following platforms:
+
++-------------------------------+---------------------------------------+
+| **Development host** | **Comments** |
++-------------------------------+---------------------------------------+
+| Linux on x86-64 | Most recent Linux distributions |
+| | will work. |
++-------------------------------+---------------------------------------+
+| macOS on x86-64 | Mojave or newer should work. |
++-------------------------------+---------------------------------------+
+| Windows 10 on x86-64 | Native Windows only; WSL1 or 2 not |
+| | supported. |
++-------------------------------+---------------------------------------+
+| Docker on x86-64 | Containers based on Ubuntu 18.04 |
+| | and newer. |
++-------------------------------+---------------------------------------+
+
+.. attention::
+
+ In all of the above supported platforms, the support is contingent on using
+ Pigweed's bootstrap (env setup) system. While it is possible to use Pigweed
+ without bootstrap, it is unsupported and undocumented at this time.
+
+Partially supported host platform: Chrome OS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Chromebooks are able to run some of the Pigweed components; notably all the
+"host" target builds and runs. However, due to USB access issues, it is not
+possible to flash and run on real hardware (like for example the STM32F429i
+Discovery).
+
+To run on ChromeOS:
+
+1. `Enable the Linux shell <https://support.google.com/chromebook/answer/9145439>`_
+2. ``sudo apt-install build-essential``
+3. Go through Pigweed setup.
+
+What about other host platforms?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+There are two key issues that make running the host tooling on other platforms
+challenging:
+
+1. Availability of up-to-date compilers
+2. Availability of up-to-date Python
+
+For both of these, Pigweed relies on Google-maintained binaries packaged in
+CIPD, which includes daily builds of LLVM, and recent versions of the ARM GCC
+toolchains. Platforms other than Mac/Windows/Linux running on x86-64 will need
+to provide equivalent binaries, which is some effort.
+
+Host platforms that we are likely to support in the future
+..........................................................
+
+- **Linux on ARM** - At time of writing (mid 2020), we do not support ARM-based
+ host platforms. However, we would like to support this eventually.
+- **Windows on WSL2 x86-64** - There are some minor issues preventing WSL2 on
+ Windows from being a smooth experience, but we are working on them.
+
+Platforms that we are unlikely to support
+.........................................
+
+- **Anything on x86-32** - While it's possible 32-bit x86 could be made to
+ work, we don't have enough users to make this worthwhile. If this is
+ something you are interested in and would be willing to support, let us know.
+
+Why name the project Pigweed?
+-----------------------------
+Pigweed, also known as amaranth, is a nutritious grain and leafy salad green
+that is also a rapidly growing weed. When developing the project that
+eventually became Pigweed, we wanted to find a name that was fun, playful, and
+reflective of how we saw Pigweed growing. Teams would start out using one
+module that catches their eye, and after that goes well, they’d quickly start
+using more.
+
+So far, so good 😁
diff --git a/docs/index.rst b/docs/index.rst
index d7eff04..a7230ed 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -21,5 +21,6 @@
Code Style <docs/style_guide>
targets
Build System <build_system>
+ FAQ <docs/faq>
docs/module_structure
module_guides