61e79bb1eb
This commit updates the Zephyr documentation with changes introduced by Zephyr CMake package. It removes 'zephyr-env.sh/cmd' where no longer needed, and updates boilerplate inclusion to find_package. Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
281 lines
10 KiB
ReStructuredText
281 lines
10 KiB
ReStructuredText
.. _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 <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 <west-multi-repo-misc>` 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: <cmake-directory>
|
|
kconfig: <directory>/Kconfig
|
|
|
|
The ``cmake: <cmake-directory>`` part specifies that
|
|
:file:`<cmake-directory>` contains the :file:`CMakeLists.txt` to use. The
|
|
``kconfig: <directory>/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=<path-to-module1>[;<path-to-module2>[...]] ...
|
|
|
|
#. At the top of your application's top level :file:`CMakeLists.txt`, like this:
|
|
|
|
.. code-block:: cmake
|
|
|
|
set(ZEPHYR_MODULES <path-to-module1> <path-to-module2> [...])
|
|
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 <path-to-module1> <path-to-module2>
|
|
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 <modules_using_west>`.
|
|
#. Add a new entry to the :zephyr_file:`west.yml` with the following
|
|
information:
|
|
|
|
.. code-block:: console
|
|
|
|
- name: <name of repository>
|
|
path: <path to where the repository should be cloned>
|
|
revision: <ref pointer to module pull request>
|
|
|
|
|
|
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 <contribute_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: <name of repository>
|
|
path: <path to where the repository should be cloned>
|
|
revision: <ref pointer to module pull request>
|
|
|
|
|
|
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
|