Skip to content

doc: Zephyr out-of-tree module.yml examples #28583

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
gregshue wants to merge 4 commits into from
Closed

doc: Zephyr out-of-tree module.yml examples #28583

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
63c7321
doc: Zephyr out-of-tree module.yml examples
Sep 21, 2020
065a31a
Update doc/glossary.rst
gregshue Jan 8, 2021
b8efaa7
Update doc/guides/modules.rst
gregshue Jan 8, 2021
1e4d785
Update doc/guides/modules.rst
Jan 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions doc/glossary.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,4 +96,35 @@ Glossary of Terms
term storage rather than copying it into RAM, saving writable memory for
dynamic data and not the static program code.

Zephyr downstream module
A Zephyr module that the :file:`zephyr` repository default configuration
and default manifest file are **not** aware of.

Zephyr manifest module
A Zephyr module which also contains one or more west manifest files.

Zephyr module
A YAML file named :file:`zephyr/module.yml` and all the content it
references, which define the extensions to be hooked into the Zephyr
infrastructure.
Comment on lines 106 to 109
Copy link
Copy Markdown
Contributor

@tejlmand tejlmand Jan 7, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

imo we consider the whole project a Zephyr module when it contains a zephyr/module.yml file, and not just the file itself.

The file is just used to identify that this project is a Zephyr module, and the content of the file defines how it should be integrated, as example, is it a DTS, board, soc root ? should it be included in the build flow (CMakeLists/Kconfig) ? should it integrate into twister.

Copy link
Copy Markdown
Author

@gregshue gregshue Jan 8, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tejlmand I started with your impression, then asked if it still made sense for repositories like project_chip and bacnet-stack, which have substantial content for non-Zephyr platforms and environments. It seems the content not reachable by the Zephyr glue code is beyond any Zephyr-module policies. I just didn't want developers in other Open Source projects to think all of their repository needed to comply with Zephyr policies.

Would you still like this changed?

Copy link
Copy Markdown
Contributor

@tejlmand tejlmand Jan 8, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need something in between. Cause I find the current description too limiting.

Personally, I would still refer to the project as a Zephyr module, although not all of the code in there may be used by Zephyr.
Just like https://github.com/zephyrproject-rtos/mbedtls is a Zephyr module, but as the code is developed by ARM, then the code itself will not comply with Zephyr policies.

Copy link
Copy Markdown
Author

@gregshue gregshue Jan 8, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tejlmand Suggestions welcome, and I can align with a more generic definition. Since we can imply a valid zephyr/module.yml from repos with both zephyr/CMakeLists.txt and zephyr/Kconfig (and/or deprecate it), how about:

"A repository with a valid zephyr/module.yml" ?


Zephyr Project module
A Zephyr module managed by the Zephyr Project. These modules will
be hosted at the Zephyr project organization on Github.

Zephyr upstream module
A Zephyr module that the :file:`zephyr` repository default configuration
and default manifest file are aware of.

:makevar:`ZEPHYR_MODULES`
The Zephyr build system CMake variable through which a list of paths to
Zephyr modules that should be included in the current build.

:makevar:`ZEPHYR_EXTRA_MODULES`
The Zephyr build system CMake variable through which paths to
Zephyr modules may be provided. This is provided to support module
development tangential to how :makevar:`ZEPHYR_MODULES` is being used.
Comment on lines 125 to 126
Copy link
Copy Markdown
Contributor

@tejlmand tejlmand Jan 7, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or it can be used in combination to west, where west knows about the manifest defined modules, but you have additional local modules or private repos (as example for testing or confidential code) that you want to include in a build.

Could be, as example, when working with the source for a closed source stack.

Copy link
Copy Markdown
Author

@gregshue gregshue Jan 8, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good to know. Please suggest replacement text if you feel that needs to be captured.

Copy link
Copy Markdown
Contributor

@tejlmand tejlmand Jan 8, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

will do some thinking.

(See :ref:`Integrate modules in Zephyr build system <modules>`
for a detailed description of the intended use case.)

.. _System on a chip: https://en.wikipedia.org/wiki/System_on_a_chip
156 changes: 139 additions & 17 deletions doc/guides/modules.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,23 @@ Zephyr depends on several categories of modules, including but not limited to:
- File Systems
- Inter-Process Communication (IPC) libraries

The Zephyr module mechanism also supports building extended functionality
in supplementary repositories, such as proprietary applications and drivers.
The Zephyr repository is independent of these modules. These modules are
downstream of the Zephyr repository and may be managed outside of the
Zephyr Project. Downstream modules may also be their own manifest repository
to support stand-alone module development and verification.
See :ref:`west-manifests` for more details on what this means.

An downstream module may be used to optionally provide:

- boards
- dts
- drivers
- subsystems
- samples/projects
- tests

This page summarizes a list of policies and best practices which aim at
better organizing the workflow in Zephyr modules.

Expand Down Expand Up @@ -423,6 +440,15 @@ The ``cmake: <cmake-directory>`` part specifies that
Neither is required: ``cmake`` defaults to ``zephyr``, and ``kconfig``
defaults to ``zephyr/Kconfig``.

Here is an example :file:`module.yml` file reflecting the default settings:

.. code-block:: yaml

build:
cmake: zephyr
kconfig: zephyr/Kconfig


Here is an example :file:`module.yml` file referring to
:file:`CMakeLists.txt` and :file:`Kconfig` files in the root directory of the
module:
Expand Down Expand Up @@ -511,12 +537,44 @@ Build settings supported in the :file:`module.yml` file are:
build system. Additional architectures must be located in a
:file:`<arch_root>/arch` folder.

Example of a :file:`module.yaml` file containing additional roots, and the
corresponding file system layout.
Example of a :file:`module.yml` file containing additional roots
corresponding to the directory structure of the Zephyr repository
put beneath the :file:`zephyrous` subdirectory.

.. code-block:: yaml

build:
Comment thread
gregshue marked this conversation as resolved.
Outdated
cmake: zephyrous
kconfig: zephyrous/Kconfig
settings:
board_root: zephyrous
dts_root: zephyrous
soc_root: zephyrous
arch_root: zephyrous

requires the following folder structure:

.. code-block:: none

<module-root>
├── zephyr/module.yml
└── zephyrous/
├── arch/
├── boards/
├── dts/
├── soc/
├── ...
├── CMakeLists.txt
└── Kconfig

Example of a :file:`module.yml` file containing additional roots located
at the top of the module repository, and the corresponding file system layout.

.. code-block:: yaml

build:
cmake: .
kconfig: Kconfig
settings:
board_root: .
dts_root: .
Expand All @@ -529,10 +587,14 @@ requires the following folder structure:
.. code-block:: none

<module-root>
├── arch
├── boards
├── dts
└── soc
├── zephyr/module.yml
├── arch/
├── boards/
├── dts/
├── soc/
├── ...
├── CMakeLists.txt
└── Kconfig



Expand All @@ -542,23 +604,83 @@ Twister (Test Runner)
To execute both tests and samples available in modules, the Zephyr test runner
(twister) should be pointed to the directories containing those samples and
tests. This can be done by specifying the path to both samples and tests in the
:file:`zephyr/module.yml` file. Additionally, if a module defines out of tree
boards, the module file can point twister to the path where those files
are maintained in the module. For example:
:file:`zephyr/module.yml` file. Additionally, if a module defines
supplementary boards, the module file can point twister to the path where
those files are maintained in the module.

Example of a :file:`module.yml` file containing samples and tests in
locations corresponding to the directory structure of the Zephyr repository
put beneath the :file:`zephyrous` subdirectory.

.. code-block:: yaml

build:
cmake: .
samples:
- samples
tests:
- tests
boards:
- boards
build:
Comment thread
gregshue marked this conversation as resolved.
Outdated
cmake: zephyrous
kconfig: zephyrous/Kconfig
samples:
- zephyrous/samples
tests:
- zephyrous/tests
boards:
- zephyrous/boards

Example of a :file:`module.yml` file containing samples, tests, and board
roots located at the top of the module repository,
and the corresponding file system layout.

.. code-block:: yaml

build:
cmake: .
kconfig: ./Kconfig
samples:
- samples
tests:
- tests
boards:
- boards


Complete Example
================

Example of a :file:`module.yml` file containing all the necessary tags and values
for the Zephyr build system to connect to the directory structure of the Zephyr
respository put beneath the :file:`zephyr` subdirectory.


.. code-block:: yaml

build:
cmake: zephyr
kconfig: zephyr/Kconfig
settings:
board_root: zephyr
dts_root: zephyr
soc_root: zephyr
arch_root: zephyr
samples:
- zephyr/samples
tests:
- zephyr/tests

requires the following folder and file structure:

.. code-block:: none

<module-root>
└── zephyr/
├── module.yml
├── arch/
├── boards/
├── dts/
├── samples/
├── soc/
├── tests/
├── ...
├── CMakeLists.txt
└── Kconfig

Module Inclusion
================

Expand Down