Lines Matching full:module
23 :ref:`module licensing requirements<modules_licensing>` and
25 Zephyr developer that is committed to maintain the module codebase.
53 Modules are repositories that contain a :file:`zephyr/module.yml` file, so that
65 general (unless they are a module themselves).
67 Module Repositories
73 * The module repository codebase shall include a *module.yml* file in a
76 * Module repository names should follow the convention of using lowercase
78 new module repositories, except for repositories that are directly
84 Existing module repositories that do not conform to the above convention
87 * Module repositories names should be explicitly set in the :file:`zephyr/module.yml` file.
90 branch. Branches for specific purposes, for example, a module branch for
93 * If the module has an external (upstream) project repository, the module
98 It is not required in module repositories to maintain a 'master'
100 is not recommended as this may generate confusion around the module's
104 beginning with the module-name. (E.g., mcuboot should expose its
112 It is preferred to synchronize a module repository with the latest stable
114 update a Zephyr module repository with the latest development branch tip,
115 if this is required to get important updates in the module codebase. When
116 synchronizing a module with upstream it is mandatory to document the
122 Changes to the main branch of a module repository, including synchronization
127 *downstream* module repository history is incremental (that is, existing
130 changes that are to be brought into the module repository.
134 Force-pushing to a module's main branch is not allowed.
140 followed in all modules repositories. It is up to the module code owner
143 module repository.
147 pull request against the module's main branch, which may be merged using
150 upstream history in the module repository.
158 version to which the module is updated (upstream version, tag, commit SHA,
164 pull request against the module main branch, and merging the pull request using
168 (that is, the original commit SHAs) is preserved in the module repository. The
182 To facilitate management of Zephyr module repositories, the following
185 **Administrator:** Each Zephyr module shall have an administrator
186 who is responsible for managing access to the module repository,
188 at the request of the module owner. Module administrators are
190 members with admin rights to module GitHub repositories.
192 **Module owner:** Each module shall have a module code owner. Module
194 Zephyr module repository. In particular, a module owner will:
196 * coordinate code reviewing in the module repository
201 * regularly synchronize the module repository with its upstream
205 and update the module repository to include security fixes, as
208 module codebase, in Zephyr release notes.
213 Module owners are not required to be Zephyr
218 module repository.
221 Maintaining the module codebase
225 may require patching a module's codebase. The responsibility for keeping
226 the module codebase up to date is shared between the **contributor** of
227 such updates in Zephyr and the module **owner**. In particular:
230 the corresponding changes that are required in module repositories, to
232 well as the module integration testing are successful.
234 * the module owner has the overall responsibility for synchronizing
235 and testing the module codebase with the zephyr main tree.
236 This includes occasional advanced testing of the module's codebase
238 The module owner is required to fix issues in the module's codebase that
247 Submitting and merging changes directly to a module's codebase, that is,
255 Non-trivial changes to a module's codebase, including changes in the module
256 design or functionality should be discouraged, if the module has an upstream
261 detail the process of contributing changes to module repositories.
270 an approval by the PR assignee. In addition to this, pull requests in module
275 The merging of pull requests in the main branch of a module
279 **Issue Reporting:** `GitHub issues`_ are intentionally disabled in module
284 labels corresponding to each module, where applicable.
299 All source files in a module's codebase shall include a license header,
300 unless the module repository has **main license file** that covers source
303 Main license files shall be added in the module's codebase by Zephyr
308 shall be made clear which license applies to each source file in a module's
311 Individual license headers in module source files supersede the main license.
313 Any new content to be added in a module repository will require to have
318 Zephyr recommends conveying module licensing via individual license
321 applies in the module's codebase (for example, by having a single or
323 be referred to in the Zephyr module, as long as licensing requirements,
329 When creating a module repository a developer shall:
332 * document (for example in the module README or .yml file) the default license
333 that covers the module's codebase.
339 adds new content in module repositories.
345 All Zephyr module repositories shall include an .rst file documenting:
347 * the scope and the purpose of the module
348 * how the module integrates with Zephyr
349 * the owner of the module repository
353 The file shall be required for the inclusion of the module and the contained
366 * should verify basic usage of the module (configuration,
369 twister runs in pull requests that introduce changes in module
383 of the module; this should be part of the testing framework of the external
395 * Lack of maintainership in the module
399 The module information shall indicate whether a module is
401 when trying to build Zephyr using a deprecated module.
418 build and configure them, respectively. Module :file:`CMakeLists.txt` files are
423 this variable is defined unless you are adding a new module. The build system
432 If the module ``FOO`` is provided by :ref:`west <west>` but also given with
433 ``-DEXTRA_ZEPHYR_MODULES=/<path>/foo`` then the module given by the command
451 Module yaml file description
454 A module can be described using a file named :file:`zephyr/module.yml`.
455 The format of :file:`zephyr/module.yml` is described in the following:
457 Module name
460 Each Zephyr module is given a name by which it can be referred to in the build
463 The name should be specified in the :file:`zephyr/module.yml` file. This will
464 ensure the module name is not changeable through user-defined directory names
471 In CMake the location of the Zephyr module can then be referred to using the
474 containing the module's :file:`CMakeLists.txt` file.
477 When used for CMake and Kconfig variables, all letters in module names are
480 As example, the module ``foo-bar`` must be referred to as
483 Here is an example for the Zephyr module ``foo``:
490 If the ``name`` field is not specified then the Zephyr module name will be
491 set to the name of the module folder.
492 As example, the Zephyr module located in :file:`<workspace>/modules/bar` will
493 use ``bar`` as its module name if nothing is specified in
494 :file:`zephyr/module.yml`.
496 Module integration files (in-module)
514 Here is an example :file:`module.yml` file referring to
516 module:
547 Here is an example :file:`module.yml` file referring to
549 the module:
557 The module description file :file:`zephyr/module.yml` can also be used to
570 Zephyr module.
577 The module description file :file:`zephyr/module.yml` can be used to improve vulnerability monitori…
579 If your module needs to track vulnerabilities using an external reference
580 (e.g your module is forked from another repository), you can use the ``security`` section.
582 be monitored for your module. The supported formats are:
591 - <module-related-cpe>
592 - <an-other-module-related-cpe>
593 - <module-related-purl>
595 A real life example for ``mbedTLS`` module could look like this:
614 When a module has a :file:`module.yml` file, it will automatically be included into
615 the Zephyr build system. The path to the module is then accessible through Kconfig
622 contains the absolute path to the module.
625 (in case the module declares blobs) symbols are automatically generated for available
627 which depend on the module or blobs from the module. To satisfy compliance checking
628 when building Zephyr without the module present, it's recommended for the module to
635 module.yml file does not specify a CMakeLists.txt.
637 To read these variables for a Zephyr module named ``foo``:
639 - In CMake: use ``${ZEPHYR_FOO_MODULE_DIR}`` for the module's top level directory, and ``${ZEPHYR_F…
640 - In Kconfig: use ``$(ZEPHYR_FOO_MODULE_DIR)`` for the module's top level directory
642 Notice how a lowercase module name ``foo`` is capitalized to ``FOO``
645 These variables can also be used to test whether a given module exists.
646 For example, to verify that ``foo`` is the name of a Zephyr module:
655 For example, to include the file :file:`some/Kconfig` in module ``foo``:
661 During CMake processing of each Zephyr module, the following variables are
664 - the current module's name: ``${ZEPHYR_CURRENT_MODULE_NAME}``
665 - the current module's top level directory: ``${ZEPHYR_CURRENT_MODULE_DIR}``
666 - the current module's :file:`CMakeLists.txt` directory: ``${ZEPHYR_CURRENT_CMAKE_DIR}``
668 This removes the need for a Zephyr module to know its own name during CMake
669 processing. The module can source additional CMake files using these ``CURRENT``
676 It is possible to append values to a Zephyr `CMake list`_ variable from the module's first
694 contains the absolute path to the sysbuild module. In CMake,
697 system. This variable's value is empty if the module.yml file does not specify
700 To read these variables for a sysbuild module:
702 - In CMake: use ``${SYSBUILD_CURRENT_MODULE_DIR}`` for the module's top level
705 - In Kconfig: use ``$(SYSBUILD_CURRENT_MODULE_DIR)`` for the module's top level
715 The module can source additional CMake files using these variables. For
723 module's first CMakeLists.txt file.
736 Sysbuild provides an infrastructure which allows a sysbuild module to define
742 - ``<module-name>_pre_cmake(IMAGES <images>)``: This function is called for each
743 sysbuild module before CMake configure is invoked for all images.
744 - ``<module-name>_post_cmake(IMAGES <images>)``: This function is called for each
745 sysbuild module after CMake configure has completed for all images.
746 - ``<module-name>_pre_domains(IMAGES <images>)``: This function is called for each
747 sysbuild module before domains yaml is created by sysbuild.
748 - ``<module-name>_post_domains(IMAGES <images>)``: This function is called for each
749 sysbuild module after domains yaml has been created by sysbuild.
751 arguments passed from sysbuild to the function defined by a module:
755 If a module ``foo`` want to provide a post CMake configure function, then the
756 module's sysbuild :file:`CMakeLists.txt` file must define function ``foo_post_cmake()``.
758 To facilitate naming of functions, the module name is provided by sysbuild CMake
760 module's sysbuild :file:`CMakeLists.txt` file.
762 Example of how the ``foo`` sysbuild module can define ``foo_post_cmake()``:
772 Zephyr module dependencies
775 A Zephyr module may be dependent on other Zephyr modules to be present in order
776 to function correctly. Or it might be that a given Zephyr module must be
777 processed after another Zephyr module, due to dependencies of certain CMake
786 - <module>
788 Here is an example for the Zephyr module ``foo`` that is dependent on the Zephyr
789 module ``bar`` to be present in the build system:
804 Module integration files (external)
807 Module integration files can be located externally to the Zephyr module itself.
811 Module integration files in Zephyr
827 Module integration files in a custom location
848 A Zephyr module can automatically be added to the ``MODULE_EXT_ROOT``
849 list using the module description file :file:`zephyr/module.yml`, see
863 To include a module's CMake file, set the variable ``ZEPHYR_<MODULE_NAME>_CMAKE_DIR``
866 To include a module's Kconfig file, set the variable ``ZEPHYR_<MODULE_NAME>_KCONFIG``
869 The following is an example on how to add support the ``FOO`` module.
889 Module integration files (zephyr/module.yml)
892 The module description file :file:`zephyr/module.yml` can be used to specify
905 Zephyr module.
907 The Zephyr repository itself is always added as a Zephyr module ext root.
915 including the module into the build system.
917 All ``root`` settings are relative to the root of the module.
919 Build settings supported in the :file:`module.yml` file are:
930 ``snippet_root: foo``, then you should place your module's
931 :file:`snippet.yml` files in :file:`<your-module>/foo/snippets` or any
945 Example of a :file:`module.yaml` file containing additional roots, and the
963 <zephyr-module-root>
976 :file:`zephyr/module.yml` file. Additionally, if a module defines out of tree
977 boards, the module file can point twister to the path where those files
978 are maintained in the module. For example:
998 metadata is contained entirely in :file:`zephyr/module.yml`. This is because
999 a binary blob must always be associated with a Zephyr module, and thus the
1000 blob metadata belongs in the module's description itself.
1006 The ``blobs`` section in :file:`zephyr/module.yml` consists of a sequence of
1010 folder in the module repository
1017 of the module repository
1032 ``module.yml`` file.
1041 The following example demonstrates a ``zephyr/module.yml`` file with some
1042 requirement files in the ``scripts`` directory of the module.
1053 Module Inclusion
1065 just those projects which have the necessary module metadata files.
1069 - If the project contains a file named :file:`zephyr/module.yml`, then the
1073 - Otherwise (i.e. if the project has no :file:`zephyr/module.yml`), the
1076 is considered a module, and those files will be added to the build.
1078 - If neither of those checks succeed, the project is not considered a module,
1089 either a :file:`zephyr/module.yml` file or the files
1138 module.
1142 request to make sure it is not merged by mistake and to allow for the module to
1145 Once the module is
1147 maintainer to the commit hash of the module which reflects the changes.
1155 Process for submitting a new module
1159 approval to integrate the external source code as a module
1163 allow submitting code to the module project following the project contribution
1166 If a module is maintained as a fork of another project on Github, the Zephyr
1167 module related files and changes in relation to upstream need to be maintained
1172 module content (code) to the new repository following the guidelines described
1180 revision: <ref pointer to module pull request>
1193 *my_module* repository. Once the module changes are reviewed and merged, the
1194 revision needs to be changed to the commit hash from the module repository.
1204 #. Submit a pull request changing the entry referencing the module into the
1212 revision: <ref pointer to module pull request>
1224 *my_module* repository. Once the module changes are reviewed and merged, the
1225 revision needs to be changed to the commit hash from the module repository.