docs/faq.rst - 3p/google/pigweed - Git at Google


            
            .. _docs-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 <docs-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 😁
	.. _docs-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 <docs-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 😁