.. _modules: Modules (External projects) ############################ Zephyr relies on the source code of several externally maintained projects in order to avoid reinventing the wheel and to reuse as much well-established, mature code as possible when it makes sense. In the context of Zephyr's build system those are called *modules*. These modules must be integrated with the Zephyr build system, as described in more detail in other sections on this page. Zephyr depends on several categories of modules, including: - Debugger integration - Silicon vendor Hardware Abstraction Layers (HALs) - Cryptography libraries - File Systems - Inter-Process Communication (IPC) libraries The build system variable :makevar:`ZEPHYR_MODULES` is a `CMake list`_ of absolute paths to the directories containing Zephyr modules. These modules contain :file:`CMakeLists.txt` and :file:`Kconfig` files describing how to build and configure them, respectively. Module :file:`CMakeLists.txt` files are added to the build using CMake's `add_subdirectory()`_ command, and the :file:`Kconfig` files are included in the build's Kconfig menu tree. If you have :ref:`west ` installed, you don't need to worry about how this variable is defined unless you are adding a new module. The build system knows how to use west to set :makevar:`ZEPHYR_MODULES`. You can add additional modules to this list by setting the :makevar:`ZEPHYR_EXTRA_MODULES` CMake variable or by adding a :makevar:`ZEPHYR_EXTRA_MODULES` line to ``.zephyrrc`` (See the section on :ref:`env_vars` for more details). This can be useful if you want to keep the list of modules found with west and also add your own. See the section about :ref:`west-multi-repo` for more details. Finally, you can also specify the list of modules yourself in various ways, or not use modules at all if your application doesn't need them. Module Inclusion **************** .. _modules_using_west: Using West ========== If west is installed and :makevar:`ZEPHYR_MODULES` is not already set, the build system finds all the modules in your :term:`west installation` and uses those. It does this by running :ref:`west list ` to get the paths of all the projects in the installation, then filters the results to just those projects which have the necessary module metadata files. Each project in the ``west list`` output is tested like this: - If the project contains a file named :file:`zephyr/module.yml`, then its contents should look like this: .. code-block:: yaml build: cmake: kconfig: /Kconfig The ``cmake: `` part specifies that :file:`` contains the :file:`CMakeLists.txt` to use. The ``kconfig: /Kconfig`` part specifies the Kconfig file to use. Neither is required: ``cmake`` defaults to ``zephyr``, and ``kconfig`` defaults to ``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: .. code-block:: yaml build: cmake: . kconfig: Kconfig - To execute both tests and samples available in modules, the Zephyr test runner (sanitycheck) 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 sanitycheck to the path where those files are maintained in the module. For example: .. code-block:: yaml build: cmake: . samples: - samples tests: - tests boards: - boards - Otherwise (i.e. if the project has no :file:`zephyr/module.yml`), the build system looks for :file:`zephyr/CMakeLists.txt` and :file:`zephyr/Kconfig` files in the project. If both are present, the project is considered a module, and those files will be added to the build. - If neither of those checks succeed, the project is not considered a module, and is not added to :makevar:`ZEPHYR_MODULES`. Without West ============ If you don't have west installed or don't want the build system to use it to find Zephyr modules, you can set :makevar:`ZEPHYR_MODULES` yourself using one of the following options. Each of the directories in the list must contain either a :file:`zephyr/module.yml` file or the files :file:`zephyr/CMakeLists.txt` and :file:`Kconfig`, as described in the previous section. #. At the CMake command line, like this: .. code-block:: console cmake -DZEPHYR_MODULES=[;[...]] ... #. At the top of your application's top level :file:`CMakeLists.txt`, like this: .. code-block:: cmake set(ZEPHYR_MODULES [...]) find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) If you choose this option, make sure to set the variable **before** calling ``find_package(Zephyr ...)``, as shown above. #. In a separate CMake script which is pre-loaded to populate the CMake cache, like this: .. code-block:: cmake # Put this in a file with a name like "zephyr-modules.cmake" set(ZEPHYR_MODULES CACHE STRING "pre-cached modules") You can tell the build system to use this file by adding ``-C zephyr-modules.cmake`` to your CMake command line. Not using modules ================= If you don't have west installed and don't specify :makevar:`ZEPHYR_MODULES` yourself, then no additional modules are added to the build. You will still be able to build any applications that don't require code or Kconfig options defined in an external repository. .. _submitting_new_modules: Submitting changes to modules ****************************** When submitting new or making changes to existing modules the main repository Zephyr needs a reference to the changes to be able to verify the changes. In the main tree this is done using revisions. For code that is already merged and part of the tree we use the commit hash, a tag, or a branch name. For pull requests however, we require specifying the pull request number in the revision field to allow building the Zephyr main tree with the changes submitted to the module. To avoid merging changes to master with pull request information, the pull request should be marked as ``DNM`` (Do Not Merge) or preferably a draft pull request to make sure it is not merged by mistake and to allow for the module to be merged first and be assigned a permanent commit hash. Once the module is merged, the revision will need to be changed either by the submitter or by the maintainer to the commit hash of the module which reflects the changes. Note that multiple and dependent changes to different modules can be submitted using exactly the same process. In this case you will change multiple entries of all modules that have a pull request against them. Submitting a new module ======================== Requirements ------------- Modules to be included in the default manifest of the Zephyr project need to provide functionality or features endorsed and approved by the project technical steering committee and should follow the project licensing and :ref:`contribute_guidelines`. A request for a new module should be initialized using an RFC issue in the Zephyr project issue tracking system with details about the module and how it integrates into the project. If the request is approved, a new repository will created by the project team and initialized with basic information that would allow submitting code to the module project following the project contribution guidelines. All modules should be hosted in repositories under the Zephyr organization. The manifest should only point to repositories maintained under the Zephyr project. If a module is maintained as a fork of another project on Github, the Zephyr module related files and changes in relation to upstream need to be maintained in a special branch named ``zephyr``. Process ------- Follow the following steps to request a new module: #. Use `GitHub issues`_ to open an issue with details about the module to be created #. Propose a name for the repository to be created under the Zephyr project organization on Github. #. Maintainers from the Zephyr project will create the repository and initialize it. You will be added as a collaborator in the new repository. #. Submit the module content (code) to the new repository following the guidelines described :ref:`here `. #. Add a new entry to the :zephyr_file:`west.yml` with the following information: .. code-block:: console - name: path: revision: For example, to add *my_module* to the manifest: .. code-block:: console - name: my_module path: modules/lib/my_module revision: pull/23/head Where 23 in the example above indicated the pull request number submitted to the *my_module* repository. Once the module changes are reviewed and merged, the revision needs to be changed to the commit hash from the module repository. .. _changes_to_existing_module: Changes to existing modules =========================== #. Submit the changes using a pull request to an existing repository following the :ref:`contribution guidelines `. #. Submit a pull request changing the entry referencing the module into the :zephyr_file:`west.yml` of the main Zephyr tree with the following information: .. code-block:: console - name: path: revision: For example, to add *my_module* to the manifest: .. code-block:: console - name: my_module path: modules/lib/my_module revision: pull/23/head Where 23 in the example above indicated the pull request number submitted to the *my_module* repository. Once the module changes are reviewed and merged, the revision needs to be changed to the commit hash from the module repository. .. _CMake list: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#lists .. _add_subdirectory(): https://cmake.org/cmake/help/latest/command/add_subdirectory.html .. _GitHub issues: https://github.com/zephyrproject-rtos/zephyr/issues