Skip to content

Commit f7f0889

Browse files
carlescuficarlescufi
committed
doc: application: Describe application types
Move the application types descriptions from the CMake documentation section to the application development one, to give them visibility and also because they application development chapter is a better home for them. Signed-off-by: Carles Cufi <[email protected]>
1 parent ae3e29a commit f7f0889

File tree

2 files changed

+107
-87
lines changed

2 files changed

+107
-87
lines changed

‎doc/build/zephyr_cmake_package.rst‎

Lines changed: 12 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,14 @@ Zephyr CMake Package
55

66
The Zephyr `CMake package`_ is a convenient way to create a Zephyr-based application.
77

8-
The Zephyr CMake package ensures that CMake can automatically select a Zephyr to use for building
9-
the application, whether it is a Zephyr repository application, Zephyr workspace application, or a
10-
Zephyr freestanding application.
8+
.. note::
9+
The :ref:`zephyr-app-types` section introduces the application types
10+
used in this page.
11+
12+
The Zephyr CMake package ensures that CMake can automatically select a Zephyr installation to use for building
13+
the application, whether it is a :ref:`Zephyr repository application <zephyr-repo-app>`,
14+
a :ref:`Zephyr workspace application <zephyr-workspace-app>`, or a
15+
:ref:`Zephyr freestanding application <zephyr-freestanding-app>`.
1116

1217
When developing a Zephyr-based application, then a developer simply needs to write
1318
``find_package(Zephyr)`` in the beginning of the application :file:`CMakeLists.txt` file.
@@ -68,87 +73,8 @@ To also export the Zephyr Unittest CMake package, run the following command in a
6873
6974
cmake -P <PATH-TO-ZEPHYR>/share/zephyrunittest-package/cmake/zephyr_export.cmake
7075
71-
7276
.. _zephyr_cmake_package_zephyr_base:
7377

74-
75-
Zephyr application structure
76-
****************************
77-
78-
An application can be placed anywhere on your disk, but to better understand how the Zephyr
79-
package is used, we will name three specific layouts.
80-
81-
82-
Zephyr repository application
83-
=============================
84-
85-
A Zephyr repository has the following structure:
86-
87-
.. code-block:: none
88-
89-
<projects>/zephyr-workspace
90-
└── zephyr
91-
├── arch
92-
├── boards
93-
├── cmake
94-
├── samples
95-
│ ├── hello_world
96-
│ └── ...
97-
├── tests
98-
└── ...
99-
100-
Any application located inside this tree, is simply referred to as a Zephyr repository application.
101-
In this example ``hello_world`` is a Zephyr repository application.
102-
103-
104-
Zephyr workspace application
105-
============================
106-
107-
A Zephyr workspace has the following structure:
108-
109-
.. code-block:: none
110-
111-
<projects>/zephyr-workspace
112-
├── zephyr
113-
├── bootloader
114-
├── modules
115-
├── tools
116-
├── <vendor/private-repositories>
117-
└── my_applications
118-
└── my_first_app
119-
120-
Any application located in such workspace, but outside the Zephyr repository itself, is referred to
121-
as a Zephyr workspace application.
122-
In this example ``my_first_app`` is a Zephyr workspace application.
123-
124-
.. note:: The root of a Zephyr workspace is identical to ``west topdir`` if the workspace was
125-
installed using ``west``
126-
127-
128-
.. _freestanding_application:
129-
130-
Zephyr freestanding application
131-
===============================
132-
133-
A Zephyr freestanding application is a Zephyr application located outside of a Zephyr workspace.
134-
135-
136-
.. code-block:: none
137-
138-
<projects>/zephyr-workspace
139-
├── zephyr
140-
├── bootloader
141-
└── ...
142-
143-
<home>/app
144-
├── CMakeLists.txt
145-
├── prj.conf
146-
└── src
147-
└── main.c
148-
149-
In this example ``app`` is a Zephyr freestanding application.
150-
151-
15278
Zephyr Base Environment Setting
15379
*******************************
15480

@@ -198,6 +124,9 @@ the following criteria will be used:
198124
in this example, ``my_first_app`` will use ``<projects>/zephyr-workspace/zephyr`` as this Zephyr
199125
is located in the same workspace as the Zephyr workspace application.
200126

127+
.. note::
128+
The root of a Zephyr workspace is identical to ``west topdir`` if the workspace was
129+
installed using ``west``
201130

202131
* Zephyr freestanding application will use the Zephyr registered in the CMake user package registry.
203132
For example:
@@ -451,7 +380,7 @@ Zephyr Build Configuration CMake package (Freestanding application)
451380
*******************************************************************
452381

453382
The Zephyr Build Configuration CMake package can be located outside a Zephyr
454-
workspace, for example located with a :ref:`freestanding_application`.
383+
workspace, for example located with a :ref:`zephyr-freestanding-app`.
455384

456385
Create the build configuration as described in the previous section, and then
457386
refer to the location of your Zephyr Build Configuration CMake package using

‎doc/develop/application/index.rst‎

Lines changed: 95 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -67,12 +67,103 @@ generated in a build directory; Zephyr does not support "in-tree" builds.
6767
The following sections describe how to create, build, and run Zephyr
6868
applications, followed by more detailed reference material.
6969

70-
Example standalone application
70+
.. _zephyr-app-types:
71+
72+
Application types
73+
*****************
74+
75+
Based on where the source code of the application is located we can distinguish
76+
between three basic application types.
77+
78+
* Zephyr repository application
79+
* Zephyr workspace application
80+
* Zephyr freestanding application
81+
82+
You can find out more about how the build system supports all the application
83+
types described in this section in the :ref:`cmake_pkg` section.
84+
85+
.. _zephyr-repo-app:
86+
87+
Zephyr repository application
88+
=============================
89+
90+
An application located within the ``zephyr`` folder in a Zephyr :ref:`west
91+
workspace <west-workspaces>` is referred to as a Zephyr repository application.
92+
In the following example, the :ref:`hello_world sample <hello_world>` is a
93+
Zephyr repository application:
94+
95+
.. code-block:: none
96+
97+
zephyrproject/
98+
├─── .west/
99+
│ └─── config
100+
└─── zephyr/
101+
├── arch/
102+
├── boards/
103+
├── cmake/
104+
├── samples/
105+
│ ├── hello_world/
106+
│ └── ...
107+
├── tests/
108+
└── ...
109+
110+
.. _zephyr-workspace-app:
111+
112+
Zephyr workspace application
113+
============================
114+
115+
An application located within a :ref:`workspace <west-workspaces>`, but outside
116+
the Zephyr repository (and thus folder) itself, is referred to as a Zephyr
117+
workspace application. In the following example, ``app`` is a Zephyr workspace
118+
application:
119+
120+
.. code-block:: none
121+
122+
zephyrproject/
123+
├─── .west/
124+
│ └─── config
125+
├─── zephyr/
126+
├─── bootloader/
127+
├─── modules/
128+
├─── tools/
129+
├─── <vendor/private-repositories>/
130+
└─── applications/
131+
└── app/
132+
133+
.. _zephyr-freestanding-app:
134+
135+
Zephyr freestanding application
136+
===============================
137+
138+
A Zephyr application located outside of a Zephyr :ref:`workspace
139+
<west-workspaces>` is referred to as a Zephyr freestanding application. In the
140+
following example, ``app`` is a Zephyr freestanding application:
141+
142+
.. code-block:: none
143+
144+
<home>/
145+
├─── zephyrproject/
146+
│ ├─── .west/
147+
│ │ └─── config
148+
│ ├── zephyr/
149+
│ ├── bootloader/
150+
│ ├── modules/
151+
│ └── ...
152+
│
153+
└─── app/
154+
├── CMakeLists.txt
155+
├── prj.conf
156+
└── src/
157+
└── main.c
158+
159+
Example workspace application
71160
******************************
72161

73-
A reference standalone application contained in its own Git repository can be found in the `Example Application`_
74-
repository. It can be used as a reference on how to structure out-of-tree, Zephyr-based
75-
applications using the :ref:`T2 star topology <west-t2>`. It also demonstrates the out-of-tree use of features commonly used in applications such as:
162+
A reference :ref:`workspace application <zephyr-workspace-app>` contained in its
163+
own Git repository can be found in the `Example Application`_ repository.
164+
It can be used as a reference on how to structure out-of-tree, Zephyr-based workspace applications
165+
using the :ref:`T2 star topology <west-t2>`. It also demonstrates the out-of-tree
166+
use of features commonly used in applications such as:
76167

77168
- Custom boards
78169
- Custom devicetree bindings

0 commit comments

Comments
 (0)