Lines Matching +full:get +full:- +full:coverage +full:- +full:files
7 order to avoid reinventing the wheel and to reuse as much well-established,
14 modules, an external project is required to have its own life-cycle outside
29 - Debugger integration
30 - Silicon vendor Hardware Abstraction Layers (HALs)
31 - Cryptography libraries
32 - File Systems
33 - Inter-Process Communication (IPC) libraries
36 references to optional :ref:`binary blobs <bin-blobs>`.
41 .. _modules-vs-projects:
47 <west-workspace>`. In fact, modules :ref:`do not require west
55 :ref:`West projects <west-manifests-projects>` are entries in the ``projects:``
71 under the zephyrproject-rtos GitHub organization.
103 * Modules should expose all provided header files with an include pathname
104 beginning with the module-name. (E.g., mcuboot should expose its
115 if this is required to get important updates in the module codebase. When
120 ----------------------------------
134 Force-pushing to a module's main branch is not allowed.
137 -----------------
197 * be the default assignee in pull-requests against the repository's
255 Non-trivial changes to a module's codebase, including changes in the module
264 -----------------------
299 All source files in a module's codebase shall include a license header,
301 files that do not include license headers.
303 Main license files shall be added in the module's codebase by Zephyr
305 and they contain a permissive OSI-compliant license. Main license files
307 SPDX license identifier. If multiple main license files are present it
311 Individual license headers in module source files supersede the main license.
314 license coverage.
319 headers and main license files. This not a hard requirement; should
322 multiple main license files), this practice may be accepted by and
331 * import the main license files, if they exist in the external project, and
336 --------------
417 contain :file:`CMakeLists.txt` and :file:`Kconfig` files describing how to
418 build and configure them, respectively. Module :file:`CMakeLists.txt` files are
420 :file:`Kconfig` files are included in the build's Kconfig menu tree.
433 ``-DEXTRA_ZEPHYR_MODULES=/<path>/foo`` then the module given by the command
444 See :ref:`west-basics` for more on west workspaces.
449 .. _module-yml:
464 ensure the module name is not changeable through user-defined directory names
465 or ``west`` manifest files:
467 .. code-block:: yaml
478 converted to uppercase and all non-alphanumeric characters are converted
480 As example, the module ``foo-bar`` must be referred to as
485 .. code-block:: yaml
496 Module integration files (in-module)
499 Inclusion of build files, :file:`CMakeLists.txt` and :file:`Kconfig`, can be
502 .. code-block:: yaml
505 cmake: <cmake-directory>
508 The ``cmake: <cmake-directory>`` part specifies that
509 :file:`<cmake-directory>` contains the :file:`CMakeLists.txt` to use. The
515 :file:`CMakeLists.txt` and :file:`Kconfig` files in the root directory of the
518 .. code-block:: yaml
533 sysbuild-specific build files, :file:`CMakeLists.txt` and :file:`Kconfig`, can
536 .. code-block:: yaml
539 sysbuild-cmake: <cmake-directory>
540 sysbuild-kconfig: <directory>/Kconfig
542 The ``sysbuild-cmake: <cmake-directory>`` part specifies that
543 :file:`<cmake-directory>` contains the :file:`CMakeLists.txt` to use. The
544 ``sysbuild-kconfig: <directory>/Kconfig`` part specifies the Kconfig file to
548 :file:`CMakeLists.txt` and :file:`Kconfig` files in the ``sysbuild`` directory of
551 .. code-block:: yaml
554 sysbuild-cmake: sysbuild
555 sysbuild-kconfig: sysbuild/Kconfig
558 specify that the build files, :file:`CMakeLists.txt` and :file:`Kconfig`, are
561 Build files located in a ``MODULE_EXT_ROOT`` can be described as:
563 .. code-block:: yaml
566 sysbuild-cmake-ext: True
567 sysbuild-kconfig-ext: True
572 .. _modules-vulnerability-monitoring:
581 It contains the field ``external-references`` that contains a list of references that needs to
584 - CPE (Common Platform Enumeration)
585 - PURL (Package URL)
587 .. code-block:: yaml
590 external-references:
591 - <module-related-cpe>
592 - <an-other-module-related-cpe>
593 - <module-related-purl>
597 .. code-block:: yaml
600 external-references:
601 - cpe:2.3:a:arm:mbed_tls:3.5.2:*:*:*:*:*:*:*
602 - pkg:github/Mbed-TLS/mbedtls@V3.5.2
606 <https://csrc.nist.gov/projects/security-content-automation-protocol/specifications/cpe>`_.
608 <https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rst>`_.
619 --------------
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
648 .. code-block:: cmake
654 In Kconfig, the variable may be used to find additional files to include.
657 .. code-block:: kconfig
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}``
669 processing. The module can source additional CMake files using these ``CURRENT``
672 .. code-block:: cmake
682 .. code-block:: cmake
691 ----------------
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
708 In Kconfig, the variable may be used to find additional files to include.
711 .. code-block:: kconfig
715 The module can source additional CMake files using these variables. For
718 .. code-block:: cmake
728 .. code-block:: cmake
734 ----------------------
737 a function which will be invoked by sysbuild at a pre-defined point in the
742 - ``<module-name>_pre_cmake(IMAGES <images>)``: This function is called for each
744 - ``<module-name>_post_cmake(IMAGES <images>)``: This function is called for each
746 - ``<module-name>_pre_domains(IMAGES <images>)``: This function is called for each
748 - ``<module-name>_post_domains(IMAGES <images>)``: This function is called for each
753 - ``<images>`` is the list of Zephyr images that will be created by the build system.
764 .. code-block:: cmake
782 .. code-block:: yaml
786 - <module>
791 .. code-block:: yaml
796 - bar
804 Module integration files (external)
807 Module integration files can be located externally to the Zephyr module itself.
809 files located externally to Zephyr modules.
811 Module integration files in Zephyr
812 ----------------------------------
815 files for certain known Zephyr modules.
817 Those files are located under
819 .. code-block:: none
827 Module integration files in a custom location
828 ---------------------------------------------
835 .. code-block:: none
844 and then build your application by specifying ``-DMODULE_EXT_ROOT`` parameter to
856 This allows you to overrule any integration files under
861 integration files for Zephyr modules via specifically named CMake variables.
873 .. code-block:: none
884 .. code-block:: cmake
889 Module integration files (zephyr/module.yml)
890 --------------------------------------------
893 that the build files, :file:`CMakeLists.txt` and :file:`Kconfig`, are located
896 Build files located in a ``MODULE_EXT_ROOT`` can be described as:
898 .. code-block:: yaml
901 cmake-ext: True
902 kconfig-ext: True
921 - ``board_root``: Contains additional boards that are available to the build
924 - ``dts_root``: Contains additional dts files related to the architecture/soc
925 families. Additional dts files must be located in a :file:`<dts_root>/dts`
927 - ``snippet_root``: Contains additional snippets that are available for use.
928 These snippets must be defined in :file:`snippet.yml` files underneath the
931 :file:`snippet.yml` files in :file:`<your-module>/foo/snippets` or any
933 - ``soc_root``: Contains additional SoCs that are available to the build
935 - ``arch_root``: Contains additional architectures that are available to the
938 - ``module_ext_root``: Contains :file:`CMakeLists.txt` and :file:`Kconfig` files
940 - ``sca_root``: Contains additional :ref:`SCA <sca>` tool implementations
948 .. code-block:: yaml
961 .. code-block:: none
963 <zephyr-module-root>
977 boards, the module file can point twister to the path where those files
981 .. code-block:: yaml
986 - samples
988 - tests
990 - boards
992 .. _modules-bin-blobs:
997 Zephyr supports fetching and using :ref:`binary blobs <bin-blobs>`, and their
1002 Binary blobs are fetched using :ref:`west blobs <west-blobs>`. If ``west`` is
1009 - ``path``: The path to the binary blob, relative to the :file:`zephyr/blobs/`
1011 - ``sha256``: `SHA-256 <https://en.wikipedia.org/wiki/SHA-2>`_ checksum of the
1013 - ``type``: The :ref:`type of binary blob <bin-blobs-types>`. Currently limited
1015 - ``version``: A version string
1016 - ``license-path``: Path to the license file for this blob, relative to the root
1018 - ``url``: URL that identifies the location the blob will be fetched from, as
1020 - ``description``: Human-readable description of the binary blob
1021 - ``doc-url``: A URL pointing to the location of the official documentation for
1036 ----------
1038 Calling ``west packages pip`` lists `requirement files`_ for Zephyr and modules.
1039 Passing ``--install`` installs these if there's an active virtual environment.
1042 requirement files in the ``scripts`` directory of the module.
1045 .. code-block:: yaml
1047 package-managers:
1049 requirement-files:
1050 - scripts/requirements-build.txt
1051 - scripts/requirements-doc.txt
1054 .. _modules-runners:
1059 If a module has out of tree boards that require custom :ref:`runners <west-runner>`,
1063 .. code-block:: yaml
1066 - file: scripts/my-runner.py
1078 ----------
1082 those. It does this by running :ref:`west list <west-built-in-misc>` to get
1084 just those projects which have the necessary module metadata files.
1088 - If the project contains a file named :file:`zephyr/module.yml`, then the
1089 content of that file will be used to determine which files should be added
1092 - Otherwise (i.e. if the project has no :file:`zephyr/module.yml`), the
1094 :file:`zephyr/Kconfig` files in the project. If both are present, the project
1095 is considered a module, and those files will be added to the build.
1097 - If neither of those checks succeed, the project is not considered a module,
1103 ------------
1108 either a :file:`zephyr/module.yml` file or the files
1114 .. code-block:: console
1116 cmake -DZEPHYR_MODULES=<path-to-module1>[;<path-to-module2>[...]] ...
1120 .. code-block:: cmake
1122 set(ZEPHYR_MODULES <path-to-module1> <path-to-module2> [...])
1128 #. In a separate CMake script which is pre-loaded to populate the CMake cache,
1131 .. code-block:: cmake
1133 # Put this in a file with a name like "zephyr-modules.cmake"
1134 set(ZEPHYR_MODULES <path-to-module1> <path-to-module2>
1135 CACHE STRING "pre-cached modules")
1137 You can tell the build system to use this file by adding ``-C
1138 zephyr-modules.cmake`` to your CMake command line.
1141 -----------------
1177 Please follow the process in :ref:`external-src-process` and obtain the TSC
1186 module related files and changes in relation to upstream need to be maintained
1195 .. code-block:: console
1197 - name: <name of repository>
1204 .. code-block:: console
1206 - name: my_module
1222 :ref:`expectations <contributor-expectations>`.
1227 .. code-block:: console
1229 - name: <name of repository>
1236 .. code-block:: console
1238 - name: my_module
1248 .. _CMake list: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#lists
1250 .. _GitHub issues: https://github.com/zephyrproject-rtos/zephyr/issues
1251 .. _requirement files: https://pip.pypa.io/en/stable/reference/requirements-file-format/