diff --git a/doc/develop/getting_started/index.rst b/doc/develop/getting_started/index.rst index 4a1b345ee626d7..ffe5ad7f2c80a6 100644 --- a/doc/develop/getting_started/index.rst +++ b/doc/develop/getting_started/index.rst @@ -178,6 +178,8 @@ The current minimum required version for the main dependencies are: .. _install_py_requirements: .. _gs_python_deps: +.. _python_venv_step: + .. rst-class:: numbered-step Get Zephyr and install Python dependencies diff --git a/doc/develop/languages/cpp/index.rst b/doc/develop/languages/cpp/index.rst index 5ba5c7d7688adb..d23796ac7607fe 100644 --- a/doc/develop/languages/cpp/index.rst +++ b/doc/develop/languages/cpp/index.rst @@ -68,6 +68,10 @@ In order to make use of the C++ exceptions, the :kconfig:option:`CONFIG_CPP_EXCEPTIONS` must be selected in the application configuration file. +.. note:: + Additional C++ features can be added to Zephyr via the + :ref:`pigweed_cpp_support` module. + Zephyr Minimal C++ Library ************************** diff --git a/doc/develop/languages/cpp/pigweed.rst b/doc/develop/languages/cpp/pigweed.rst new file mode 100644 index 00000000000000..280b9de8338c8a --- /dev/null +++ b/doc/develop/languages/cpp/pigweed.rst @@ -0,0 +1,115 @@ +.. _pigweed_cpp_support: + +Enable C++ Support with Pigweed +############################### + +Additional C++ features that are currently not natively supported by Zephyr are +provided through a 3rd party module: `Pigweed`_. Pigweed provides some standard +library functionality like: + +.. list-table:: Pigweed support + :header-rows: 1 + + * - Pigweed module + - Description + * - `pw::thread`_ + - Provides C++ features to :c:struct:`k_thread` and functionality + provided by :ref:`threads_v2` + * - `pw::sync`_ + - Provides C++ features to :c:struct:`k_mutex` and :c:struct:`k_sem` + along with functionality provided by :ref:`mutexes_v2` and + :ref:`semaphores_v2` respectively. Features such as support for + ``std::lock_guard`` (:ref:`pigweed_example_lock_guard`). + * - `pw::chrono`_ + - Provides C++ features to :ref:`kernel_timing` and :ref:`timers_v2` along + with some STL chrono features such as the ability to cast, operate, or + convert different time units with fewer errors. + +Navigating Pigweed +****************** + +Pigweed uses a different definition for what a ``module`` is when compared to +Zephyr. When reviewing the documentation on `Pigweed`_'s page, a ``module`` can +be viewed as a collection of related libraries. + +.. _pigweed_example_lock_guard: + +Example: lock guard +******************* + +.. code-block:: C++ + + #include + + #include + + pw::sync::Mutex mutex; + + void ThreadSafeCriticalSection() { + std::lock_guard lock(mutex); + NotThreadSafeCriticalSection(); + } + +Getting started +############### + +Step 1: Add Pigweed to your Zephyr manifest +******************************************* + +.. code-block:: yaml + + remotes: + - name: pigweed + url-base: https://pigweed.googlesource.com/pigweed + + projects: + - name: pigweed + remote: pigweed + revision: main + +Step 2: Bootstrap the Pigweed environment +***************************************** + +.. warning:: + + If you've already set up a virtual environment in :ref:`python_venv_step` + you'll need to exit and delete it first. Pigweed will manage the virtual + environment for you. Trying to bootstrap from inside a virtual environment + will lead to undefined behavior. + +Bootstrapping the Pigweed environment is effectively like Zephyr's installation +of the ``requirements.txt`` file. After you bootstrap Pigweed, there will be a +virtual environment set up with all the Pigweed tools. Then, you install the +Zephyr requirements on top. + +.. code-block:: console + + cd ~/zephyrproject + source modules/lib/pigweed/bootstrap.sh + pip install zephyr/scripts/requirements.txt + +Once installed, the environment is set up. In future work sessions, run the +following command to enter your virtual environment: + +.. code-block:: console + + source modules/lib/pigweed/activate.sh + +Updating +========= + +You should re-run the bootstrapping process following any ``west update`` that +modifies either the Zephyr main tree or the Pigweed module. + +Step 3: Use Pigweed +******************* + +Pigweed modules can be enabled via Kconfigs and automatically link into your +application. The configurations and modules can be seen at +`Pigweed Zephyr Kconfig reference`_. + +.. _`Pigweed`: https://pigweed.dev/ +.. _`pw::thread`: https://pigweed.dev/pw_thread +.. _`pw::sync`: https://pigweed.dev/pw_sync +.. _`pw::chrono`: https://pigweed.dev/pw_chrono +.. _`Pigweed Zephyr Kconfig reference`: https://pigweed.dev/docs/os/zephyr/kconfig.html diff --git a/doc/develop/languages/index.rst b/doc/develop/languages/index.rst index 033b9084ac4fc3..efebf95b544143 100644 --- a/doc/develop/languages/index.rst +++ b/doc/develop/languages/index.rst @@ -8,3 +8,4 @@ Language Support c/index.rst cpp/index.rst + cpp/pigweed.rst