doc: build and configuration systems
Move the build and configuration systems under one chapter and reorg the application developer guide to reflect that. Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif
parent
20aa90d26c
commit
5342bc64dd
15 changed files with 442 additions and 431 deletions
|
|
@ -428,6 +428,229 @@ should know about.
|
|||
additional directories with source code, Kconfig, etc. that should be used in
|
||||
the application build. See :ref:`modules` for details.
|
||||
|
||||
|
||||
Application CMakeLists.txt
|
||||
**************************
|
||||
|
||||
Every application must have a :file:`CMakeLists.txt` file. This file is the
|
||||
entry point, or top level, of the build system. The final :file:`zephyr.elf`
|
||||
image contains both the application and the kernel libraries.
|
||||
|
||||
This section describes some of what you can do in your :file:`CMakeLists.txt`.
|
||||
Make sure to follow these steps in order.
|
||||
|
||||
#. If you only want to build for one board, add the name of the board
|
||||
configuration for your application on a new line. For example:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set(BOARD qemu_x86)
|
||||
|
||||
Refer to :ref:`boards` for more information on available boards.
|
||||
|
||||
The Zephyr build system determines a value for :makevar:`BOARD` by checking
|
||||
the following, in order (when a BOARD value is found, CMake stops looking
|
||||
further down the list):
|
||||
|
||||
- Any previously used value as determined by the CMake cache takes highest
|
||||
precedence. This ensures you don't try to run a build with a different
|
||||
:makevar:`BOARD` value than you set during the build configuration step.
|
||||
|
||||
- Any value given on the CMake command line (directly or indirectly via
|
||||
``west build``) using ``-DBOARD=YOUR_BOARD`` will be checked for and
|
||||
used next.
|
||||
|
||||
- If an :ref:`environment variable <env_vars>` ``BOARD`` is set, its value
|
||||
will then be used.
|
||||
|
||||
- Finally, if you set ``BOARD`` in your application :file:`CMakeLists.txt`
|
||||
as described in this step, this value will be used.
|
||||
|
||||
#. If your application uses a configuration file or files other than
|
||||
the usual :file:`prj.conf` (or :file:`prj_YOUR_BOARD.conf`, where
|
||||
``YOUR_BOARD`` is a board name), add lines setting the
|
||||
:makevar:`CONF_FILE` variable to these files appropriately.
|
||||
If multiple filenames are given, separate them by a single space or
|
||||
semicolon. CMake lists can be used to build up configuration fragment
|
||||
files in a modular way when you want to avoid setting :makevar:`CONF_FILE`
|
||||
in a single place. For example:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set(CONF_FILE "fragment_file1.conf")
|
||||
list(APPEND CONF_FILE "fragment_file2.conf")
|
||||
|
||||
See :ref:`initial-conf` for more information.
|
||||
|
||||
#. If your application uses devicetree overlays, you may need to set
|
||||
:ref:`DTC_OVERLAY_FILE <important-build-vars>`.
|
||||
See :ref:`set-devicetree-overlays`.
|
||||
|
||||
#. If your application has its own kernel configuration options,
|
||||
create a :file:`Kconfig` file in the same directory as your
|
||||
application's :file:`CMakeLists.txt`.
|
||||
|
||||
See :ref:`the Kconfig section of the manual <kconfig>` for detailed
|
||||
Kconfig documentation.
|
||||
|
||||
An (unlikely) advanced use case would be if your application has its own
|
||||
unique configuration **options** that are set differently depending on the
|
||||
build configuration.
|
||||
|
||||
If you just want to set application specific **values** for existing Zephyr
|
||||
configuration options, refer to the :makevar:`CONF_FILE` description above.
|
||||
|
||||
Structure your :file:`Kconfig` file like this:
|
||||
|
||||
.. literalinclude:: application-kconfig.include
|
||||
|
||||
.. note::
|
||||
|
||||
Environment variables in ``source`` statements are expanded directly, so
|
||||
you do not need to define an ``option env="ZEPHYR_BASE"`` Kconfig
|
||||
"bounce" symbol. If you use such a symbol, it must have the same name as
|
||||
the environment variable.
|
||||
|
||||
See :ref:`kconfig_extensions` for more information.
|
||||
|
||||
The :file:`Kconfig` file is automatically detected when placed in
|
||||
the application directory, but it is also possible for it to be
|
||||
found elsewhere if the CMake variable :makevar:`KCONFIG_ROOT` is
|
||||
set with an absolute path.
|
||||
|
||||
#. Specify that the application requires Zephyr on a new line, **after any
|
||||
lines added from the steps above**:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
find_package(Zephyr)
|
||||
project(my_zephyr_app)
|
||||
|
||||
.. note:: ``find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})`` can be used if
|
||||
enforcing a specific Zephyr installation by explicitly
|
||||
setting the ``ZEPHYR_BASE`` environment variable should be
|
||||
supported. All samples in Zephyr supports the ``ZEPHYR_BASE``
|
||||
environment variable.
|
||||
|
||||
#. Now add any application source files to the 'app' target
|
||||
library, each on their own line, like so:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
target_sources(app PRIVATE src/main.c)
|
||||
|
||||
Below is a simple example :file:`CMakeList.txt`:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set(BOARD qemu_x86)
|
||||
|
||||
find_package(Zephyr)
|
||||
project(my_zephyr_app)
|
||||
|
||||
target_sources(app PRIVATE src/main.c)
|
||||
|
||||
The Cmake property ``HEX_FILES_TO_MERGE``
|
||||
leverages the application configuration provided by
|
||||
Kconfig and CMake to let you merge externally built hex files
|
||||
with the hex file generated when building the Zephyr application.
|
||||
For example:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set_property(GLOBAL APPEND PROPERTY HEX_FILES_TO_MERGE
|
||||
${app_bootloader_hex}
|
||||
${PROJECT_BINARY_DIR}/${KERNEL_HEX_NAME}
|
||||
${app_provision_hex})
|
||||
|
||||
CMakeCache.txt
|
||||
**************
|
||||
|
||||
CMake uses a CMakeCache.txt file as persistent key/value string
|
||||
storage used to cache values between runs, including compile and build
|
||||
options and paths to library dependencies. This cache file is created
|
||||
when CMake is run in an empty build folder.
|
||||
|
||||
For more details about the CMakeCache.txt file see the official CMake
|
||||
documentation `runningcmake`_ .
|
||||
|
||||
.. _runningcmake: http://cmake.org/runningcmake/
|
||||
|
||||
Application Configuration
|
||||
*************************
|
||||
|
||||
.. _application-kconfig:
|
||||
|
||||
Kconfig Configuration
|
||||
=====================
|
||||
|
||||
Application configuration options are usually set in :file:`prj.conf` in the
|
||||
application directory. For example, C++ support could be enabled with this
|
||||
assignment:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
CONFIG_CPLUSPLUS=y
|
||||
|
||||
Looking at :ref:`existing samples <samples-and-demos>` is a good way to get
|
||||
started.
|
||||
|
||||
See :ref:`setting_configuration_values` for detailed documentation on setting
|
||||
Kconfig configuration values. The :ref:`initial-conf` section on the same page
|
||||
explains how the initial configuration is derived. See
|
||||
:ref:`configuration_options` for a complete list of configuration options.
|
||||
See :ref:`hardening` for security information related with Kconfig options.
|
||||
|
||||
The other pages in the :ref:`Kconfig section of the manual <kconfig>` are also
|
||||
worth going through, especially if you planning to add new configuration
|
||||
options.
|
||||
|
||||
Devicetree Overlays
|
||||
===================
|
||||
|
||||
See :ref:`set-devicetree-overlays`.
|
||||
|
||||
Application-Specific Code
|
||||
*************************
|
||||
|
||||
Application-specific source code files are normally added to the
|
||||
application's :file:`src` directory. If the application adds a large
|
||||
number of files the developer can group them into sub-directories
|
||||
under :file:`src`, to whatever depth is needed.
|
||||
|
||||
Application-specific source code should not use symbol name prefixes that have
|
||||
been reserved by the kernel for its own use. For more information, see `Naming
|
||||
Conventions
|
||||
<https://github.com/zephyrproject-rtos/zephyr/wiki/Naming-Conventions>`_.
|
||||
|
||||
Third-party Library Code
|
||||
========================
|
||||
|
||||
It is possible to build library code outside the application's :file:`src`
|
||||
directory but it is important that both application and library code targets
|
||||
the same Application Binary Interface (ABI). On most architectures there are
|
||||
compiler flags that control the ABI targeted, making it important that both
|
||||
libraries and applications have certain compiler flags in common. It may also
|
||||
be useful for glue code to have access to Zephyr kernel header files.
|
||||
|
||||
To make it easier to integrate third-party components, the Zephyr
|
||||
build system has defined CMake functions that give application build
|
||||
scripts access to the zephyr compiler options. The functions are
|
||||
documented and defined in :zephyr_file:`cmake/extensions.cmake`
|
||||
and follow the naming convention ``zephyr_get_<type>_<format>``.
|
||||
|
||||
The following variables will often need to be exported to the
|
||||
third-party build system.
|
||||
|
||||
* ``CMAKE_C_COMPILER``, ``CMAKE_AR``.
|
||||
|
||||
* ``ARCH`` and ``BOARD``, together with several variables that identify the
|
||||
Zephyr kernel version.
|
||||
|
||||
:zephyr_file:`samples/application_development/external_lib` is a sample
|
||||
project that demonstrates some of these features.
|
||||
|
||||
|
||||
.. _build_an_application:
|
||||
|
||||
Building an Application
|
||||
|
|
@ -761,6 +984,120 @@ again.
|
|||
to the path of the QEMU binary you want to use instead.
|
||||
|
||||
.. _application_debugging:
|
||||
|
||||
Application Debugging
|
||||
*********************
|
||||
|
||||
This section is a quick hands-on reference to start debugging your
|
||||
application with QEMU. Most content in this section is already covered in
|
||||
`QEMU`_ and `GNU_Debugger`_ reference manuals.
|
||||
|
||||
.. _QEMU: http://wiki.qemu.org/Main_Page
|
||||
|
||||
.. _GNU_Debugger: http://www.gnu.org/software/gdb
|
||||
|
||||
In this quick reference, you'll find shortcuts, specific environmental
|
||||
variables, and parameters that can help you to quickly set up your debugging
|
||||
environment.
|
||||
|
||||
The simplest way to debug an application running in QEMU is using the GNU
|
||||
Debugger and setting a local GDB server in your development system through QEMU.
|
||||
|
||||
You will need an Executable and Linkable Format (ELF) binary image for
|
||||
debugging purposes. The build system generates the image in the build
|
||||
directory. By default, the kernel binary name is
|
||||
:file:`zephyr.elf`. The name can be changed using a Kconfig option.
|
||||
|
||||
We will use the standard 1234 TCP port to open a :abbr:`GDB (GNU Debugger)`
|
||||
server instance. This port number can be changed for a port that best suits the
|
||||
development environment.
|
||||
|
||||
You can run QEMU to listen for a "gdb connection" before it starts executing any
|
||||
code to debug it.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
qemu -s -S <image>
|
||||
|
||||
will setup Qemu to listen on port 1234 and wait for a GDB connection to it.
|
||||
|
||||
The options used above have the following meaning:
|
||||
|
||||
* ``-S`` Do not start CPU at startup; rather, you must type 'c' in the
|
||||
monitor.
|
||||
* ``-s`` Shorthand for :literal:`-gdb tcp::1234`: open a GDB server on
|
||||
TCP port 1234.
|
||||
|
||||
To debug with QEMU and to start a GDB server and wait for a remote connect, run
|
||||
either of the following inside the build directory of an application:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ninja debugserver
|
||||
|
||||
The build system will start a QEMU instance with the CPU halted at startup
|
||||
and with a GDB server instance listening at the TCP port 1234.
|
||||
|
||||
Using a local GDB configuration :file:`.gdbinit` can help initialize your GDB
|
||||
instance on every run.
|
||||
In this example, the initialization file points to the GDB server instance.
|
||||
It configures a connection to a remote target at the local host on the TCP
|
||||
port 1234. The initialization sets the kernel's root directory as a
|
||||
reference.
|
||||
|
||||
The :file:`.gdbinit` file contains the following lines:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
target remote localhost:1234
|
||||
dir ZEPHYR_BASE
|
||||
|
||||
.. note::
|
||||
|
||||
Substitute the correct :ref:`ZEPHYR_BASE <important-build-vars>` for your
|
||||
system.
|
||||
|
||||
Execute the application to debug from the same directory that you chose for
|
||||
the :file:`gdbinit` file. The command can include the ``--tui`` option
|
||||
to enable the use of a terminal user interface. The following commands
|
||||
connects to the GDB server using :file:`gdb`. The command loads the symbol
|
||||
table from the elf binary file. In this example, the elf binary file name
|
||||
corresponds to :file:`zephyr.elf` file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
..../path/to/gdb --tui zephyr.elf
|
||||
|
||||
.. note::
|
||||
|
||||
The GDB version on the development system might not support the --tui
|
||||
option. Please make sure you use the GDB binary from the SDK which
|
||||
corresponds to the toolchain that has been used to build the binary.
|
||||
|
||||
If you are not using a .gdbinit file, issue the following command inside GDB to
|
||||
connect to the remote GDB server on port 1234:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
(gdb) target remote localhost:1234
|
||||
|
||||
Finally, the command below connects to the GDB server using the Data
|
||||
Displayer Debugger (:file:`ddd`). The command loads the symbol table from the
|
||||
elf binary file, in this instance, the :file:`zephyr.elf` file.
|
||||
|
||||
The :abbr:`DDD (Data Displayer Debugger)` may not be installed in your
|
||||
development system by default. Follow your system instructions to install
|
||||
it. For example, use ``sudo apt-get install ddd`` on an Ubuntu system.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ddd --gdb --debugger "gdb zephyr.elf"
|
||||
|
||||
|
||||
Both commands execute the :abbr:`gdb (GNU Debugger)`. The command name might
|
||||
change depending on the toolchain you are using and your cross-development
|
||||
tools.
|
||||
|
||||
.. _custom_board_definition:
|
||||
|
||||
Custom Board, Devicetree and SOC Definitions
|
||||
|
|
@ -994,121 +1331,10 @@ Cache variable:
|
|||
:goals: build
|
||||
:compact:
|
||||
|
||||
Application Debugging
|
||||
*********************
|
||||
|
||||
This section is a quick hands-on reference to start debugging your
|
||||
application with QEMU. Most content in this section is already covered in
|
||||
`QEMU`_ and `GNU_Debugger`_ reference manuals.
|
||||
|
||||
.. _QEMU: http://wiki.qemu.org/Main_Page
|
||||
|
||||
.. _GNU_Debugger: http://www.gnu.org/software/gdb
|
||||
|
||||
In this quick reference, you'll find shortcuts, specific environmental
|
||||
variables, and parameters that can help you to quickly set up your debugging
|
||||
environment.
|
||||
|
||||
The simplest way to debug an application running in QEMU is using the GNU
|
||||
Debugger and setting a local GDB server in your development system through QEMU.
|
||||
|
||||
You will need an Executable and Linkable Format (ELF) binary image for
|
||||
debugging purposes. The build system generates the image in the build
|
||||
directory. By default, the kernel binary name is
|
||||
:file:`zephyr.elf`. The name can be changed using a Kconfig option.
|
||||
|
||||
We will use the standard 1234 TCP port to open a :abbr:`GDB (GNU Debugger)`
|
||||
server instance. This port number can be changed for a port that best suits the
|
||||
development environment.
|
||||
|
||||
You can run QEMU to listen for a "gdb connection" before it starts executing any
|
||||
code to debug it.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
qemu -s -S <image>
|
||||
|
||||
will setup Qemu to listen on port 1234 and wait for a GDB connection to it.
|
||||
|
||||
The options used above have the following meaning:
|
||||
|
||||
* ``-S`` Do not start CPU at startup; rather, you must type 'c' in the
|
||||
monitor.
|
||||
* ``-s`` Shorthand for :literal:`-gdb tcp::1234`: open a GDB server on
|
||||
TCP port 1234.
|
||||
|
||||
To debug with QEMU and to start a GDB server and wait for a remote connect, run
|
||||
either of the following inside the build directory of an application:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ninja debugserver
|
||||
|
||||
The build system will start a QEMU instance with the CPU halted at startup
|
||||
and with a GDB server instance listening at the TCP port 1234.
|
||||
|
||||
Using a local GDB configuration :file:`.gdbinit` can help initialize your GDB
|
||||
instance on every run.
|
||||
In this example, the initialization file points to the GDB server instance.
|
||||
It configures a connection to a remote target at the local host on the TCP
|
||||
port 1234. The initialization sets the kernel's root directory as a
|
||||
reference.
|
||||
|
||||
The :file:`.gdbinit` file contains the following lines:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
target remote localhost:1234
|
||||
dir ZEPHYR_BASE
|
||||
|
||||
.. note::
|
||||
|
||||
Substitute the correct :ref:`ZEPHYR_BASE <important-build-vars>` for your
|
||||
system.
|
||||
|
||||
Execute the application to debug from the same directory that you chose for
|
||||
the :file:`gdbinit` file. The command can include the ``--tui`` option
|
||||
to enable the use of a terminal user interface. The following commands
|
||||
connects to the GDB server using :file:`gdb`. The command loads the symbol
|
||||
table from the elf binary file. In this example, the elf binary file name
|
||||
corresponds to :file:`zephyr.elf` file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
..../path/to/gdb --tui zephyr.elf
|
||||
|
||||
.. note::
|
||||
|
||||
The GDB version on the development system might not support the --tui
|
||||
option. Please make sure you use the GDB binary from the SDK which
|
||||
corresponds to the toolchain that has been used to build the binary.
|
||||
|
||||
If you are not using a .gdbinit file, issue the following command inside GDB to
|
||||
connect to the remote GDB server on port 1234:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
(gdb) target remote localhost:1234
|
||||
|
||||
Finally, the command below connects to the GDB server using the Data
|
||||
Displayer Debugger (:file:`ddd`). The command loads the symbol table from the
|
||||
elf binary file, in this instance, the :file:`zephyr.elf` file.
|
||||
|
||||
The :abbr:`DDD (Data Displayer Debugger)` may not be installed in your
|
||||
development system by default. Follow your system instructions to install
|
||||
it. For example, use ``sudo apt-get install ddd`` on an Ubuntu system.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ddd --gdb --debugger "gdb zephyr.elf"
|
||||
|
||||
|
||||
Both commands execute the :abbr:`gdb (GNU Debugger)`. The command name might
|
||||
change depending on the toolchain you are using and your cross-development
|
||||
tools.
|
||||
|
||||
Eclipse Debugging
|
||||
*****************
|
||||
Debug with Eclipse
|
||||
******************
|
||||
|
||||
Overview
|
||||
========
|
||||
|
|
@ -1227,273 +1453,7 @@ Support for Zephyr RTOS awareness is implemented in `pyOCD v0.11.0`_ and later.
|
|||
It is compatible with GDB PyOCD Debugging in Eclipse, but you must enable
|
||||
CONFIG_DEBUG_THREAD_INFO=y in your application.
|
||||
|
||||
.. _cmake-details:
|
||||
|
||||
CMake Details
|
||||
*************
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
CMake is used to build your application together with the Zephyr kernel. A
|
||||
CMake build is done in two stages. The first stage is called
|
||||
**configuration**. During configuration, the CMakeLists.txt build scripts are
|
||||
executed. After configuration is finished, CMake has an internal model of the
|
||||
Zephyr build, and can generate build scripts that are native to the host
|
||||
platform.
|
||||
|
||||
CMake supports generating scripts for several build systems, but only Ninja and
|
||||
Make are tested and supported by Zephyr. After configuration, you begin the
|
||||
**build** stage by executing the generated build scripts. These build scripts
|
||||
can recompile the application without involving CMake following
|
||||
most code changes. However, after certain changes, the configuration step must
|
||||
be executed again before building. The build scripts can detect some of these
|
||||
situations and reconfigure automatically, but there are cases when this must be
|
||||
done manually.
|
||||
|
||||
Zephyr uses CMake's concept of a 'target' to organize the build. A
|
||||
target can be an executable, a library, or a generated file. For
|
||||
application developers, the library target is the most important to
|
||||
understand. All source code that goes into a Zephyr build does so by
|
||||
being included in a library target, even application code.
|
||||
|
||||
Library targets have source code, that is added through CMakeLists.txt
|
||||
build scripts like this:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
target_sources(app PRIVATE src/main.c)
|
||||
|
||||
In the above :file:`CMakeLists.txt`, an existing library target named ``app``
|
||||
is configured to include the source file :file:`src/main.c`. The ``PRIVATE``
|
||||
keyword indicates that we are modifying the internals of how the library is
|
||||
being built. Using the keyword ``PUBLIC`` would modify how other
|
||||
libraries that link with app are built. In this case, using ``PUBLIC``
|
||||
would cause libraries that link with ``app`` to also include the
|
||||
source file :file:`src/main.c`, behavior that we surely do not want. The
|
||||
``PUBLIC`` keyword could however be useful when modifying the include
|
||||
paths of a target library.
|
||||
|
||||
Application CMakeLists.txt
|
||||
==========================
|
||||
|
||||
Every application must have a :file:`CMakeLists.txt` file. This file is the
|
||||
entry point, or top level, of the build system. The final :file:`zephyr.elf`
|
||||
image contains both the application and the kernel libraries.
|
||||
|
||||
This section describes some of what you can do in your :file:`CMakeLists.txt`.
|
||||
Make sure to follow these steps in order.
|
||||
|
||||
#. If you only want to build for one board, add the name of the board
|
||||
configuration for your application on a new line. For example:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set(BOARD qemu_x86)
|
||||
|
||||
Refer to :ref:`boards` for more information on available boards.
|
||||
|
||||
The Zephyr build system determines a value for :makevar:`BOARD` by checking
|
||||
the following, in order (when a BOARD value is found, CMake stops looking
|
||||
further down the list):
|
||||
|
||||
- Any previously used value as determined by the CMake cache takes highest
|
||||
precedence. This ensures you don't try to run a build with a different
|
||||
:makevar:`BOARD` value than you set during the build configuration step.
|
||||
|
||||
- Any value given on the CMake command line (directly or indirectly via
|
||||
``west build``) using ``-DBOARD=YOUR_BOARD`` will be checked for and
|
||||
used next.
|
||||
|
||||
- If an :ref:`environment variable <env_vars>` ``BOARD`` is set, its value
|
||||
will then be used.
|
||||
|
||||
- Finally, if you set ``BOARD`` in your application :file:`CMakeLists.txt`
|
||||
as described in this step, this value will be used.
|
||||
|
||||
#. If your application uses a configuration file or files other than
|
||||
the usual :file:`prj.conf` (or :file:`prj_YOUR_BOARD.conf`, where
|
||||
``YOUR_BOARD`` is a board name), add lines setting the
|
||||
:makevar:`CONF_FILE` variable to these files appropriately.
|
||||
If multiple filenames are given, separate them by a single space or
|
||||
semicolon. CMake lists can be used to build up configuration fragment
|
||||
files in a modular way when you want to avoid setting :makevar:`CONF_FILE`
|
||||
in a single place. For example:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set(CONF_FILE "fragment_file1.conf")
|
||||
list(APPEND CONF_FILE "fragment_file2.conf")
|
||||
|
||||
See :ref:`initial-conf` for more information.
|
||||
|
||||
#. If your application uses devicetree overlays, you may need to set
|
||||
:ref:`DTC_OVERLAY_FILE <important-build-vars>`.
|
||||
See :ref:`set-devicetree-overlays`.
|
||||
|
||||
#. If your application has its own kernel configuration options,
|
||||
create a :file:`Kconfig` file in the same directory as your
|
||||
application's :file:`CMakeLists.txt`.
|
||||
|
||||
See :ref:`the Kconfig section of the manual <kconfig>` for detailed
|
||||
Kconfig documentation.
|
||||
|
||||
An (unlikely) advanced use case would be if your application has its own
|
||||
unique configuration **options** that are set differently depending on the
|
||||
build configuration.
|
||||
|
||||
If you just want to set application specific **values** for existing Zephyr
|
||||
configuration options, refer to the :makevar:`CONF_FILE` description above.
|
||||
|
||||
Structure your :file:`Kconfig` file like this:
|
||||
|
||||
.. literalinclude:: application-kconfig.include
|
||||
|
||||
.. note::
|
||||
|
||||
Environment variables in ``source`` statements are expanded directly, so
|
||||
you do not need to define an ``option env="ZEPHYR_BASE"`` Kconfig
|
||||
"bounce" symbol. If you use such a symbol, it must have the same name as
|
||||
the environment variable.
|
||||
|
||||
See :ref:`kconfig_extensions` for more information.
|
||||
|
||||
The :file:`Kconfig` file is automatically detected when placed in
|
||||
the application directory, but it is also possible for it to be
|
||||
found elsewhere if the CMake variable :makevar:`KCONFIG_ROOT` is
|
||||
set with an absolute path.
|
||||
|
||||
#. Specify that the application requires Zephyr on a new line, **after any
|
||||
lines added from the steps above**:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
find_package(Zephyr)
|
||||
project(my_zephyr_app)
|
||||
|
||||
.. note:: ``find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})`` can be used if
|
||||
enforcing a specific Zephyr installation by explicitly
|
||||
setting the ``ZEPHYR_BASE`` environment variable should be
|
||||
supported. All samples in Zephyr supports the ``ZEPHYR_BASE``
|
||||
environment variable.
|
||||
|
||||
#. Now add any application source files to the 'app' target
|
||||
library, each on their own line, like so:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
target_sources(app PRIVATE src/main.c)
|
||||
|
||||
Below is a simple example :file:`CMakeList.txt`:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set(BOARD qemu_x86)
|
||||
|
||||
find_package(Zephyr)
|
||||
project(my_zephyr_app)
|
||||
|
||||
target_sources(app PRIVATE src/main.c)
|
||||
|
||||
The Cmake property ``HEX_FILES_TO_MERGE``
|
||||
leverages the application configuration provided by
|
||||
Kconfig and CMake to let you merge externally built hex files
|
||||
with the hex file generated when building the Zephyr application.
|
||||
For example:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set_property(GLOBAL APPEND PROPERTY HEX_FILES_TO_MERGE
|
||||
${app_bootloader_hex}
|
||||
${PROJECT_BINARY_DIR}/${KERNEL_HEX_NAME}
|
||||
${app_provision_hex})
|
||||
|
||||
CMakeCache.txt
|
||||
==============
|
||||
|
||||
CMake uses a CMakeCache.txt file as persistent key/value string
|
||||
storage used to cache values between runs, including compile and build
|
||||
options and paths to library dependencies. This cache file is created
|
||||
when CMake is run in an empty build folder.
|
||||
|
||||
For more details about the CMakeCache.txt file see the official CMake
|
||||
documentation `runningcmake`_ .
|
||||
|
||||
.. _runningcmake: http://cmake.org/runningcmake/
|
||||
|
||||
Application Configuration
|
||||
*************************
|
||||
|
||||
.. _application-kconfig:
|
||||
|
||||
Kconfig Configuration
|
||||
=====================
|
||||
|
||||
Application configuration options are usually set in :file:`prj.conf` in the
|
||||
application directory. For example, C++ support could be enabled with this
|
||||
assignment:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
CONFIG_CPLUSPLUS=y
|
||||
|
||||
Looking at :ref:`existing samples <samples-and-demos>` is a good way to get
|
||||
started.
|
||||
|
||||
See :ref:`setting_configuration_values` for detailed documentation on setting
|
||||
Kconfig configuration values. The :ref:`initial-conf` section on the same page
|
||||
explains how the initial configuration is derived. See
|
||||
:ref:`configuration_options` for a complete list of configuration options.
|
||||
See :ref:`hardening` for security information related with Kconfig options.
|
||||
|
||||
The other pages in the :ref:`Kconfig section of the manual <kconfig>` are also
|
||||
worth going through, especially if you planning to add new configuration
|
||||
options.
|
||||
|
||||
Devicetree Overlays
|
||||
===================
|
||||
|
||||
See :ref:`set-devicetree-overlays`.
|
||||
|
||||
Application-Specific Code
|
||||
*************************
|
||||
|
||||
Application-specific source code files are normally added to the
|
||||
application's :file:`src` directory. If the application adds a large
|
||||
number of files the developer can group them into sub-directories
|
||||
under :file:`src`, to whatever depth is needed.
|
||||
|
||||
Application-specific source code should not use symbol name prefixes that have
|
||||
been reserved by the kernel for its own use. For more information, see `Naming
|
||||
Conventions
|
||||
<https://github.com/zephyrproject-rtos/zephyr/wiki/Naming-Conventions>`_.
|
||||
|
||||
Support for building third-party library code
|
||||
=============================================
|
||||
|
||||
It is possible to build library code outside the application's :file:`src`
|
||||
directory but it is important that both application and library code targets
|
||||
the same Application Binary Interface (ABI). On most architectures there are
|
||||
compiler flags that control the ABI targeted, making it important that both
|
||||
libraries and applications have certain compiler flags in common. It may also
|
||||
be useful for glue code to have access to Zephyr kernel header files.
|
||||
|
||||
To make it easier to integrate third-party components, the Zephyr
|
||||
build system has defined CMake functions that give application build
|
||||
scripts access to the zephyr compiler options. The functions are
|
||||
documented and defined in :zephyr_file:`cmake/extensions.cmake`
|
||||
and follow the naming convention ``zephyr_get_<type>_<format>``.
|
||||
|
||||
The following variables will often need to be exported to the
|
||||
third-party build system.
|
||||
|
||||
* ``CMAKE_C_COMPILER``, ``CMAKE_AR``.
|
||||
|
||||
* ``ARCH`` and ``BOARD``, together with several variables that identify the
|
||||
Zephyr kernel version.
|
||||
|
||||
:zephyr_file:`samples/application_development/external_lib` is a sample
|
||||
project that demonstrates some of these features.
|
||||
|
||||
.. _CMake: https://www.cmake.org
|
||||
.. _CMake introduction: https://cmake.org/cmake/help/latest/manual/cmake.1.html#description
|
||||
|
|
|
|||
|
|
@ -1,7 +1,57 @@
|
|||
.. _build_overview:
|
||||
|
||||
Build Overview
|
||||
##############
|
||||
Build and Configuration Systems
|
||||
###############################
|
||||
|
||||
|
||||
.. _cmake-details:
|
||||
|
||||
Build System (CMake)
|
||||
********************
|
||||
|
||||
|
||||
CMake is used to build your application together with the Zephyr kernel. A
|
||||
CMake build is done in two stages. The first stage is called
|
||||
**configuration**. During configuration, the CMakeLists.txt build scripts are
|
||||
executed. After configuration is finished, CMake has an internal model of the
|
||||
Zephyr build, and can generate build scripts that are native to the host
|
||||
platform.
|
||||
|
||||
CMake supports generating scripts for several build systems, but only Ninja and
|
||||
Make are tested and supported by Zephyr. After configuration, you begin the
|
||||
**build** stage by executing the generated build scripts. These build scripts
|
||||
can recompile the application without involving CMake following
|
||||
most code changes. However, after certain changes, the configuration step must
|
||||
be executed again before building. The build scripts can detect some of these
|
||||
situations and reconfigure automatically, but there are cases when this must be
|
||||
done manually.
|
||||
|
||||
Zephyr uses CMake's concept of a 'target' to organize the build. A
|
||||
target can be an executable, a library, or a generated file. For
|
||||
application developers, the library target is the most important to
|
||||
understand. All source code that goes into a Zephyr build does so by
|
||||
being included in a library target, even application code.
|
||||
|
||||
Library targets have source code, that is added through CMakeLists.txt
|
||||
build scripts like this:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
target_sources(app PRIVATE src/main.c)
|
||||
|
||||
In the above :file:`CMakeLists.txt`, an existing library target named ``app``
|
||||
is configured to include the source file :file:`src/main.c`. The ``PRIVATE``
|
||||
keyword indicates that we are modifying the internals of how the library is
|
||||
being built. Using the keyword ``PUBLIC`` would modify how other
|
||||
libraries that link with app are built. In this case, using ``PUBLIC``
|
||||
would cause libraries that link with ``app`` to also include the
|
||||
source file :file:`src/main.c`, behavior that we surely do not want. The
|
||||
``PUBLIC`` keyword could however be useful when modifying the include
|
||||
paths of a target library.
|
||||
|
||||
|
||||
Build and Configuration Phases
|
||||
==============================
|
||||
|
||||
The Zephyr build process can be divided into two main phases: a configuration
|
||||
phase (driven by CMake) and a build phase (driven by Make or Ninja).
|
||||
|
|
@ -9,7 +59,7 @@ phase (driven by CMake) and a build phase (driven by Make or Ninja).
|
|||
.. _build_configuration_phase:
|
||||
|
||||
Configuration Phase
|
||||
*******************
|
||||
-------------------
|
||||
|
||||
The configuration phase begins when the user invokes *CMake*,
|
||||
specifying a source application directory and a board target.
|
||||
|
|
@ -83,7 +133,7 @@ Kconfig
|
|||
See :ref:`the Kconfig section of the manual <kconfig>` for more information.
|
||||
|
||||
Build Phase
|
||||
***********
|
||||
-----------
|
||||
|
||||
The build phase begins when the user invokes ``make`` or ``ninja``. Its
|
||||
ultimate output is a complete Zephyr application in a format suitable for
|
||||
|
|
@ -93,7 +143,7 @@ into four stages: the pre-build, first-pass binary, final binary, and
|
|||
post-processing.
|
||||
|
||||
Pre-build
|
||||
=========
|
||||
+++++++++
|
||||
|
||||
Pre-build occurs before any source files are compiled, because during
|
||||
this phase header files used by the source files are generated.
|
||||
|
|
@ -116,7 +166,7 @@ System call boilerplate
|
|||
:width: 80%
|
||||
|
||||
First-pass binary
|
||||
=================
|
||||
+++++++++++++++++
|
||||
|
||||
Compilation proper begins with the first-pass binary. Source files (C
|
||||
and assembly) are collected from various subsystems (which ones is
|
||||
|
|
@ -149,7 +199,7 @@ is skipped.
|
|||
:width: 80%
|
||||
|
||||
Final binary
|
||||
============
|
||||
++++++++++++
|
||||
|
||||
The binary from the previous stage is incomplete, with empty and/or
|
||||
placeholder sections that must be filled in by, essentially, reflection.
|
||||
|
|
@ -180,7 +230,7 @@ missing pieces populated.
|
|||
|
||||
|
||||
Post processing
|
||||
===============
|
||||
+++++++++++++++
|
||||
|
||||
Finally, if necessary, the completed kernel is converted from *ELF* to
|
||||
the format expected by the loader and/or flash tool required by the
|
||||
|
|
@ -196,14 +246,14 @@ target. This is accomplished in a straightforward manner with *objdump*.
|
|||
.. _build_system_scripts:
|
||||
|
||||
Supporting Scripts and Tools
|
||||
****************************
|
||||
============================
|
||||
|
||||
The following is a detailed description of the scripts used during the build process.
|
||||
|
||||
.. _gen_syscalls.py:
|
||||
|
||||
:zephyr_file:`scripts/gen_syscalls.py`
|
||||
========================================
|
||||
--------------------------------------
|
||||
|
||||
.. include:: ../../../scripts/gen_syscalls.py
|
||||
:start-after: """
|
||||
|
|
@ -212,7 +262,7 @@ The following is a detailed description of the scripts used during the build pro
|
|||
.. _gen_handles.py:
|
||||
|
||||
:zephyr_file:`scripts/gen_handles.py`
|
||||
==========================================
|
||||
--------------------------------------
|
||||
|
||||
.. include:: ../../../scripts/gen_handles.py
|
||||
:start-after: """
|
||||
|
|
@ -221,7 +271,7 @@ The following is a detailed description of the scripts used during the build pro
|
|||
.. _gen_kobject_list.py:
|
||||
|
||||
:zephyr_file:`scripts/gen_kobject_list.py`
|
||||
==========================================
|
||||
------------------------------------------
|
||||
|
||||
.. include:: ../../../scripts/gen_kobject_list.py
|
||||
:start-after: """
|
||||
|
|
@ -230,7 +280,7 @@ The following is a detailed description of the scripts used during the build pro
|
|||
.. _gen_offset_header.py:
|
||||
|
||||
:zephyr_file:`scripts/gen_offset_header.py`
|
||||
===========================================
|
||||
-------------------------------------------
|
||||
|
||||
.. include:: ../../../scripts/gen_offset_header.py
|
||||
:start-after: """
|
||||
|
|
@ -239,7 +289,7 @@ The following is a detailed description of the scripts used during the build pro
|
|||
.. _parse_syscalls.py:
|
||||
|
||||
:zephyr_file:`scripts/parse_syscalls.py`
|
||||
========================================
|
||||
----------------------------------------
|
||||
|
||||
|
||||
.. include:: ../../../scripts/parse_syscalls.py
|
||||
|
|
@ -249,7 +299,7 @@ The following is a detailed description of the scripts used during the build pro
|
|||
.. _gen_idt.py:
|
||||
|
||||
:zephyr_file:`arch/x86/gen_idt.py`
|
||||
==================================
|
||||
----------------------------------
|
||||
|
||||
.. include:: ../../../arch/x86/gen_idt.py
|
||||
:start-after: """
|
||||
|
|
@ -258,7 +308,7 @@ The following is a detailed description of the scripts used during the build pro
|
|||
.. _gen_gdt.py:
|
||||
|
||||
:zephyr_file:`arch/x86/gen_gdt.py`
|
||||
===================================
|
||||
----------------------------------
|
||||
|
||||
.. include:: ../../../arch/x86/gen_gdt.py
|
||||
:start-after: """
|
||||
|
|
@ -267,7 +317,7 @@ The following is a detailed description of the scripts used during the build pro
|
|||
.. _gen_relocate_app.py:
|
||||
|
||||
:zephyr_file:`scripts/gen_relocate_app.py`
|
||||
===========================================
|
||||
-------------------------------------------
|
||||
|
||||
.. include:: ../../../scripts/gen_relocate_app.py
|
||||
:start-after: """
|
||||
|
|
@ -276,15 +326,47 @@ The following is a detailed description of the scripts used during the build pro
|
|||
.. _process_gperf.py:
|
||||
|
||||
:zephyr_file:`scripts/process_gperf.py`
|
||||
========================================
|
||||
---------------------------------------
|
||||
|
||||
.. include:: ../../../scripts/process_gperf.py
|
||||
:start-after: """
|
||||
:end-before: """
|
||||
|
||||
:zephyr_file:`scripts/gen_app_partitions.py`
|
||||
============================================
|
||||
--------------------------------------------
|
||||
|
||||
.. include:: ../../../scripts/gen_app_partitions.py
|
||||
:start-after: """
|
||||
:end-before: """
|
||||
|
||||
.. _kconfig:
|
||||
|
||||
Configuration System (Kconfig)
|
||||
*******************************
|
||||
|
||||
The Zephyr kernel and subsystems can be configured at build time to adapt them
|
||||
for specific application and platform needs. Configuration is handled through
|
||||
Kconfig, which is the same configuration system used by the Linux kernel. The
|
||||
goal is to support configuration without having to change any source code.
|
||||
|
||||
Configuration options (often called *symbols*) are defined in :file:`Kconfig`
|
||||
files, which also specify dependencies between symbols that determine what
|
||||
configurations are valid. Symbols can be grouped into menus and sub-menus to
|
||||
keep the interactive configuration interfaces organized.
|
||||
|
||||
The output from Kconfig is a header file :file:`autoconf.h` with macros that
|
||||
can be tested at build time. Code for unused features can be compiled out to
|
||||
save space.
|
||||
|
||||
The following sections explain how to set Kconfig configuration options, go
|
||||
into detail on how Kconfig is used within the Zephyr project, and have some
|
||||
tips and best practices for writing :file:`Kconfig` files.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
kconfig/menuconfig.rst
|
||||
kconfig/setting.rst
|
||||
kconfig/tips.rst
|
||||
kconfig/preprocessor-functions.rst
|
||||
kconfig/extensions.rst
|
||||
|
|
|
|||
|
Before Width: | Height: | Size: 137 KiB After Width: | Height: | Size: 137 KiB |
|
Before Width: | Height: | Size: 68 KiB After Width: | Height: | Size: 68 KiB |
|
Before Width: | Height: | Size: 102 KiB After Width: | Height: | Size: 102 KiB |
|
Before Width: | Height: | Size: 52 KiB After Width: | Height: | Size: 52 KiB |
|
Before Width: | Height: | Size: 80 KiB After Width: | Height: | Size: 80 KiB |
|
|
@ -9,7 +9,6 @@ User and Developer Guides
|
|||
beyond-GSG.rst
|
||||
arch/index.rst
|
||||
bluetooth/index.rst
|
||||
build/index
|
||||
../README.rst
|
||||
coccinelle.rst
|
||||
code-relocation.rst
|
||||
|
|
@ -19,7 +18,7 @@ User and Developer Guides
|
|||
device_mgmt/dfu
|
||||
dts/index
|
||||
emulator/index.rst
|
||||
kconfig/index
|
||||
|
||||
modules.rst
|
||||
networking/index
|
||||
platformio/index.rst
|
||||
|
|
|
|||
|
|
@ -1,31 +0,0 @@
|
|||
.. _kconfig:
|
||||
|
||||
Kconfig
|
||||
#######
|
||||
|
||||
The Zephyr kernel and subsystems can be configured at build time to adapt them
|
||||
for specific application and platform needs. Configuration is handled through
|
||||
Kconfig, which is the same configuration system used by the Linux kernel. The
|
||||
goal is to support configuration without having to change any source code.
|
||||
|
||||
Configuration options (often called *symbols*) are defined in :file:`Kconfig`
|
||||
files, which also specify dependencies between symbols that determine what
|
||||
configurations are valid. Symbols can be grouped into menus and sub-menus to
|
||||
keep the interactive configuration interfaces organized.
|
||||
|
||||
The output from Kconfig is a header file :file:`autoconf.h` with macros that
|
||||
can be tested at build time. Code for unused features can be compiled out to
|
||||
save space.
|
||||
|
||||
The following sections explain how to set Kconfig configuration options, go
|
||||
into detail on how Kconfig is used within the Zephyr project, and have some
|
||||
tips and best practices for writing :file:`Kconfig` files.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
menuconfig.rst
|
||||
setting.rst
|
||||
tips.rst
|
||||
preprocessor-functions.rst
|
||||
extensions.rst
|
||||
|
|
@ -112,6 +112,7 @@ licensing, as described in :ref:`Zephyr_Licensing`.
|
|||
getting_started/index.rst
|
||||
contribute/index.rst
|
||||
development_process/index.rst
|
||||
guides/build/index.rst
|
||||
application/index.rst
|
||||
reference/index.rst
|
||||
guides/index.rst
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue