Lines Matching +full:cmake +full:- +full:ext
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:``
61 <modules_using_west>`, or via the :ref:`ZEPHYR_MODULES CMake variable
71 under the zephyrproject-rtos GitHub organization.
104 beginning with the module-name. (E.g., mcuboot should expose its
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 -----------------------
305 and they contain a permissive OSI-compliant license. Main license files
336 --------------
415 The build system variable :makevar:`ZEPHYR_MODULES` is a `CMake list`_ of
419 added to the build using CMake's `add_subdirectory()`_ command, and the
425 modules to this list by setting the :makevar:`EXTRA_ZEPHYR_MODULES` CMake
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
467 .. code-block:: yaml
471 In CMake the location of the Zephyr module can then be referred to using the
472 CMake variable ``ZEPHYR_<MODULE_NAME>_MODULE_DIR`` and the variable
477 When used for CMake and Kconfig variables, all letters in module names are
478 converted to uppercase and all non-alphanumeric characters are converted
480 As example, the module ``foo-bar`` must be referred to as
481 ``ZEPHYR_FOO_BAR_MODULE_DIR`` in CMake and Kconfig.
485 .. code-block:: yaml
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
511 Neither is required: ``cmake`` defaults to ``zephyr``, and ``kconfig``
518 .. code-block:: yaml
521 cmake: .
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>`_.
616 and CMake variables.
619 --------------
621 In both Kconfig and CMake, the variable ``ZEPHYR_<MODULE_NAME>_MODULE_DIR``
632 In CMake, ``ZEPHYR_<MODULE_NAME>_CMAKE_DIR`` contains the
634 is included into CMake build system. This variable's value is empty if the
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
643 in both CMake and Kconfig.
648 .. code-block:: cmake
657 .. code-block:: kconfig
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``
672 .. code-block:: cmake
674 include(${ZEPHYR_CURRENT_MODULE_DIR}/cmake/code.cmake)
676 It is possible to append values to a Zephyr `CMake list`_ variable from the module's first
682 .. code-block:: cmake
691 ----------------
693 In both Kconfig and CMake, the variable ``SYSBUILD_CURRENT_MODULE_DIR``
694 contains the absolute path to the sysbuild module. In CMake,
696 containing the :file:`CMakeLists.txt` file that is included into CMake build
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
715 The module can source additional CMake files using these variables. For
718 .. code-block:: cmake
720 include(${SYSBUILD_CURRENT_MODULE_DIR}/cmake/code.cmake)
722 It is possible to append values to a Zephyr `CMake list`_ variable from the
728 .. code-block:: cmake
734 ----------------------
737 a function which will be invoked by sysbuild at a pre-defined point in the
738 CMake flow.
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
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.
755 If a module ``foo`` want to provide a post CMake configure function, then the
758 To facilitate naming of functions, the module name is provided by sysbuild CMake
759 through the ``SYSBUILD_CURRENT_MODULE_NAME`` CMake variable when loading the
764 .. code-block:: cmake
777 processed after another Zephyr module, due to dependencies of certain CMake
782 .. code-block:: yaml
786 - <module>
791 .. code-block:: yaml
796 - bar
812 ----------------------------------
819 .. code-block:: none
828 ---------------------------------------------
835 .. code-block:: none
839 ├── modules.cmake
844 and then build your application by specifying ``-DMODULE_EXT_ROOT`` parameter to
845 the CMake build system. The ``MODULE_EXT_ROOT`` accepts a `CMake list`_ of roots as
860 The :file:`modules.cmake` file must contain the logic that specifies the
861 integration files for Zephyr modules via specifically named CMake variables.
863 To include a module's CMake file, set the variable ``ZEPHYR_<MODULE_NAME>_CMAKE_DIR``
864 to the path containing the CMake file.
873 .. code-block:: none
877 ├── modules.cmake
882 and inside the :file:`modules.cmake` file, add the following content
884 .. code-block:: cmake
890 --------------------------------------------
898 .. code-block:: yaml
901 cmake-ext: True
902 kconfig-ext: True
907 The Zephyr repository itself is always added as a Zephyr module ext root.
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
943 :file:`sca.cmake`.
948 .. code-block:: yaml
961 .. code-block:: none
963 <zephyr-module-root>
981 .. code-block:: yaml
984 cmake: .
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 ----------
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
1059 ----------
1063 those. It does this by running :ref:`west list <west-built-in-misc>` to get
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
1078 - If neither of those checks succeed, the project is not considered a module,
1084 ------------
1093 #. At the CMake command line, like this:
1095 .. code-block:: console
1097 cmake -DZEPHYR_MODULES=<path-to-module1>[;<path-to-module2>[...]] ...
1101 .. code-block:: cmake
1103 set(ZEPHYR_MODULES <path-to-module1> <path-to-module2> [...])
1109 #. In a separate CMake script which is pre-loaded to populate the CMake cache,
1112 .. code-block:: cmake
1114 # Put this in a file with a name like "zephyr-modules.cmake"
1115 set(ZEPHYR_MODULES <path-to-module1> <path-to-module2>
1116 CACHE STRING "pre-cached modules")
1118 You can tell the build system to use this file by adding ``-C
1119 zephyr-modules.cmake`` to your CMake command line.
1122 -----------------
1158 Please follow the process in :ref:`external-src-process` and obtain the TSC
1176 .. code-block:: console
1178 - name: <name of repository>
1185 .. code-block:: console
1187 - name: my_module
1203 :ref:`expectations <contributor-expectations>`.
1208 .. code-block:: console
1210 - name: <name of repository>
1217 .. code-block:: console
1219 - name: my_module
1229 .. _CMake list: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#lists
1230 .. _add_subdirectory(): https://cmake.org/cmake/help/latest/command/add_subdirectory.html
1231 .. _GitHub issues: https://github.com/zephyrproject-rtos/zephyr/issues
1232 .. _requirement files: https://pip.pypa.io/en/stable/reference/requirements-file-format/