Skip to content
Permalink
Browse files

doc: document submitting changes to modules

Instructions for submitting changes to modules and how they will be
integrated with the main tree.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
  • Loading branch information...
nashif committed May 11, 2019
1 parent 9d3be37 commit 2f126bb51f5ce2063964754f68de0212d0760daa
Showing with 147 additions and 79 deletions.
  1. +1 −1 doc/application/index.rst
  2. +7 −0 doc/contribute/index.rst
  3. +139 −78 doc/guides/modules.rst
@@ -289,7 +289,7 @@ should know about.

* :makevar:`ZEPHYR_MODULES`: A CMake list containing absolute paths of
additional directories with source code, Kconfig, etc. that should be used in
the application build. See :ref:`modules` below for details.
the application build. See :ref:`modules` for details.

.. _build_an_application:

@@ -545,6 +545,13 @@ workflow here:
Additional information about the CI system can be found in
`Continuous Integration`_.

Contributions to External Modules
**********************************

Follow the guidelines in the :ref:`modules` section for contributing
:ref:`new modules <submitting_new_modules>` and
submitting changes to :ref:`existing modules <changes_to_existing_module>`.

Commit Guidelines
*****************

@@ -8,11 +8,10 @@ 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, which is described in more detail in other sections on
Zephyr build system, as described in more detail in other sections on
this page.

There are several categories of external projects that Zephyr depends on,
including:
Zephyr depends on several categories of modules, including:

- Debugger integration
- Silicon vendor Hardware Abstraction Layers (HALs)
@@ -34,79 +33,20 @@ modules to this list by setting the :makevar:`ZEPHYR_EXTRA_MODULES` CMake
variable. 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.

Topologies supported
********************

The following three source code topologies supported by west:

* **T1**: Star topology with zephyr as the manifest repository:

- The zephyr repository acts as the central repository and includes a
complete list of projects used upstream
- Default (upstream) configuration
- Analogy with existing mechanisms: Git sub-modules with zephyr as the
super-project
- See :ref:`west-installation` for how mainline Zephyr is an example
of this topology

* **T2**: Star topology with an application repository as the manifest
repository:

- A repository containing a Zephyr application acts as the central repository
and includes a complete list of other projects, including the zephyr
repository, required to build it
- Useful for those focused on a single application
- Analogy with existing mechanisms: Git sub-modules with the application as
the super-project, zephyr and other projects as sub-modules
- An installation using this topology could look like this:

.. code-block:: none

app-manifest-installation
├── application
│   ├── CMakeLists.txt
│   ├── prj.conf
│   ├── src
│   │   └── main.c
│   └── west.yml
├── modules
│   └── lib
│   └── tinycbor
└── zephyr

* **T3**: Forest topology:

- A dedicated manifest repository which contains no Zephyr source code,
and specifies a list of projects all at the same "level"
- Useful for downstream distributions with no "central" repository
- Analogy with existing mechanisms: Google repo-based source distribution
- An installation using this topology could look like this:

.. code-block:: none

forest
├── app1
│   ├── CMakeLists.txt
│   ├── prj.conf
│   └── src
│   └── main.c
├── app2
│   ├── CMakeLists.txt
│   ├── prj.conf
│   └── src
│   └── main.c
├── manifest-repo
│   └── west.yml
├── modules
│   └── lib
│   └── tinycbor
└── zephyr

Module Initialization Using West
********************************


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
@@ -141,16 +81,16 @@ Each project in the ``west list`` output is tested like this:
cmake: .
kconfig: Kconfig
- Otherwise (i.e. if the project has no :file:`zephyr/module.yml`), then the
- 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`.

Module Initialization Without West
**********************************
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
@@ -187,12 +127,133 @@ section.
You can tell the build system to use this file by adding ``-C
zephyr-modules.cmake`` to your CMake command line.

Not Using Modules
*****************
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 licencing 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 organisation. 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

0 comments on commit 2f126bb

Please sign in to comment.
You can’t perform that action at this time.