Lines Matching +full:do +full:- +full:not +full:- +full:merge
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
17 should not contain code that is written exclusively for Zephyr. Instead,
27 Zephyr depends on several categories of modules, including but not limited to:
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:
46 Zephyr modules, described in this page, are not the same as :ref:`west projects
47 <west-workspace>`. In fact, modules :ref:`do not require west
55 :ref:`West projects <west-manifests-projects>` are entries in the ``projects:``
57 West projects are often also modules, but not always. There are west projects
58 that are not included in the final firmware image (eg. tools) and thus do not
64 The contents of this page only apply to modules, and not to west projects in
71 under the zephyrproject-rtos GitHub organization.
84 Existing module repositories that do not conform to the above convention
85 do not need to be renamed to comply with the above convention.
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
120 ----------------------------------
125 *Rebase and merge*, or *Create a merge commit* option using Github UI). This
134 Force-pushing to a module's main branch is not allowed.
137 -----------------
148 the *Rebase & merge* operation. This approach is simple and
155 the external project is not hosted in an upstream Git repository.
162 Upstream changes brought in by performing a Git merge of the intended upstream
165 the *Create a merge commit* operation.
169 downside of this approach is that two additional merge commits are generated in
197 * be the default assignee in pull-requests against the repository's
213 Module owners are not required to be Zephyr
217 responsibility to merge approved pull requests in the main branch of a
239 have not been caught by Zephyr pull request CI runs.
252 * urgent changes that should not wait to be merged in the external project
255 Non-trivial changes to a module's codebase, including changes in the module
264 -----------------------
290 shall not affect the
301 files that do not include license headers.
305 and they contain a permissive OSI-compliant license. Main license files
319 headers and main license files. This not a hard requirement; should
336 --------------
380 on target platforms, so they do not need to provide integration tests.
382 The purpose of integration testing is not to provide functional verification
388 may (but are not required to) be part of the Zephyr test framework.
393 Modules may be deprecated for reasons including, but not limited to:
433 ``-DEXTRA_ZEPHYR_MODULES=/<path>/foo`` then the module given by the command
444 See :ref:`west-basics` for more on west workspaces.
447 not use modules at all if your application doesn't need them.
449 .. _module-yml:
464 ensure the module name is not changeable through user-defined directory names
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
490 If the ``name`` field is not specified then the Zephyr module name will be
496 Module integration files (in-module)
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
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
551 .. code-block:: yaml
554 sysbuild-cmake: sysbuild
555 sysbuild-kconfig: sysbuild/Kconfig
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 --------------
635 module.yml file does not specify a CMakeLists.txt.
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
651 # Do something if FOO exists.
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}``
672 .. code-block:: cmake
678 To do so, append the value to the list and then set the list in the PARENT_SCOPE
682 .. code-block:: cmake
691 ----------------
697 system. This variable's value is empty if the module.yml file does not specify
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
711 .. code-block:: kconfig
718 .. code-block:: cmake
724 To do so, append the value to the list and then set the list in the
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
812 ----------------------------------
819 .. code-block:: none
828 ---------------------------------------------
835 .. code-block:: none
844 and then build your application by specifying ``-DMODULE_EXT_ROOT`` parameter to
873 .. code-block:: none
884 .. code-block:: cmake
890 --------------------------------------------
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
927 - ``snippet_root``: Contains additional snippets that are available for use.
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>
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
1003 :ref:`not used <modules_without_west>`, they must be downloaded and
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 ----------
1039 Passing ``--install`` installs these if there's an active virtual environment.
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 ----------
1080 If west is installed and :makevar:`ZEPHYR_MODULES` is not already set, the
1082 those. It does this by running :ref:`west list <west-built-in-misc>` to get
1088 - If the project contains a file named :file:`zephyr/module.yml`, then the
1092 - Otherwise (i.e. if the project has no :file:`zephyr/module.yml`), the
1097 - If neither of those checks succeed, the project is not considered a module,
1098 and is not added to :makevar:`ZEPHYR_MODULES`.
1103 ------------
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.
1140 Not using modules
1141 -----------------
1160 request should be marked as ``DNM`` (Do Not Merge) or preferably a draft pull
1161 request to make sure it is not merged by mistake and to allow for the module to
1163 not automatically notifying anyone until marked as "Ready for review".
1177 Please follow the process in :ref:`external-src-process` and obtain the TSC
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/