doc: restructure application primer

Merge build system and application primer into one and put
all in one file to make it easier to follow.

Jira: ZEP-686
Change-Id: I64ec7ef7a6aa2ad80496ca0ee3ddc3d7fe09a5d7
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2016-12-22 10:47:01 -05:00 committed by Anas Nashif
commit 7cb8a16c86
14 changed files with 758 additions and 1277 deletions

View file

@ -3,39 +3,769 @@
Application Development Primer
##############################
This section outlines how to create, build, and run a Zephyr application.
Audience
Overview
========
The Zephyr Kernel's build system is based on the Kbuild system used in the
Linux kernel.
The build system is an application-centric system and requires an application
build to initiate building the kernel source tree. The application build drives
the configuration and build process of both the application and kernel,
compiling them into a single binary.
The Zephyr Kernel's base directory hosts the kernel source code, the
configuration options, and the kernel build definitions.
The files in the application directory links the kernel with the
application. It hosts the definitions of the application, for example,
application-specific configuration options and the application's source code.
An application in the simplest form has the following structure:
* **Application source code files**: An application typically provides one
or more application-specific files, written in C or assembly language. These
files are usually located in a sub-directory called :file:`src`.
* **Kernel configuration files**: An application typically provides
a configuration file (:file:`.conf`) that specifies values for one or more
kernel configuration options. If omitted, the application's existing kernel
configuration option values are used; if no existing values are provided,
the kernel's default configuration values are used.
* **Makefile**: This file tells the build system where to find the files
mentioned above, as well as the desired target board configuration.
Once the application has been defined, it can be built with a single ``make``
call.
The results of the build process are located in a sub-directory called
:file:`outdir/BOARD`. This directory contains the files generated by the build
process, the most notable of which are listed below.
* The :file:`.config` file that contains the configuration settings
used to build the application.
* The various object files (:file:`.o` files and :file:`.a` files) containing
custom-built kernel and application-specific code.
* The :file:`zephyr.elf` file that contains the final combined application and
kernel binary.
Application Structure
=====================
Create one directory for your application and a sub-directory for the
application's source code; this makes it easier to organize directories and
files in the structure that the kernel expects.
#. Create an application directory structure outside of the kernel's
installation directory tree. Often this is your workspace directory.
#. In a console terminal, navigate to a location where you want your
application to reside.
#. Create the application's directory, enter:
.. code-block:: console
$ mkdir app
.. note::
This directory and the path to it, are referred to in the documentation
as :file:`~/app`.
#. Create a source code directory in your :file:`~/app`, enter:
.. code-block:: console
$ cd app
$ mkdir src
The source code directory :file:`~/app/src` is created.
.. code-block:: console
-- app
|-- src
Application Definition
======================
An application is integrated into the build system by including the Makefile.inc
file provided.
.. code-block:: make
include $(ZEPHYR_BASE)/Makefile.inc
The following predefined variables configure the development project:
* :makevar:`ZEPHYR_BASE`: Sets the path to the kernel's base directory.
This variable is usually set by the :file:`zephyr_env.sh` script.
It can be used to get the kernel's base directory, as used in the
Makefile.inc inclusion above, or it can be overridden to select an
specific instance of the kernel.
* :makevar:`PROJECT_BASE`: Provides the developer's application project
directory path. It is set by the :file:`Makefile.inc` file.
* :makevar:`SOURCE_DIR`: Overrides the default value for the application's
source code directory. The developer source code directory is set to
:file:`$(PROJECT_BASE/)src/` by default. This directory name should end
with slash **'/'**.
* :makevar:`BOARD`: Selects the board that the application's
build will use for the default configuration.
* :makevar:`CONF_FILE`: Indicates the name of a configuration fragment file.
This file includes the kconfig configuration values that override the
default configuration values.
* :makevar:`O`: Optional. Indicates the output directory that Kconfig uses.
The output directory stores all the files generated during the build
process. The default output directory is the :file:`$(PROJECT_BASE)/outdir`
directory.
Makefiles
=========
Overview
--------
Although anybody may use this primer, the primary audience for this guide is:
The build system defines a set of conventions for the correct use of Makefiles
in the kernel source directories. The correct use of Makefiles is driven by the
concept of recursion.
* Application developers coding an application.
In the recursion model, each Makefile within a directory includes the source
code and any subdirectories to the build process. Each subdirectory follows
the same principle. Developers can focus exclusively in their own work. They
integrate their module with the build system by adding a very simple Makefile
following the recursive model.
* System architects learning key functionality and usage.
.. _makefile_conventions:
Before You Start
----------------
Makefile Conventions
--------------------
* Check that your Linux host meets the minimum requirements specified in the
:ref:`getting_started`.
The following conventions restrict how to add modules and Makefiles to the
build system. These conventions ensure the correct implementation of the
recursive model.
* Check that environment variables have been configured correctly as outlined
in :ref:`apps_common_procedures`.
* Each source code directory must contain a single Makefile. Directories
without a Makefile are not considered source code directories.
Workflow
--------
* The scope of every Makefile is restricted to the contents of that directory.
A Makefile can only make a direct reference to files and subdirectories on the
same level or below.
The following sections explain the application development process
from start to finish.
* Makefiles list the object files that are included in the link process. The
build system finds the source file that generates the object file by matching
the object file name to the source file.
.. toctree::
:maxdepth: 1
* Parent directories add their child directories into the recursion model.
apps_overview
apps_structure
apps_kernel_conf
apps_code_dev
apps_build
apps_run
apps_common_procedures
* The root Makefile adds the directories in the kernel base directory into the
recursion model.
Adding Source Files
-------------------
The Makefile must refer the source build indirectly, specifying the object file
that results from the source file using the :literal:`obj-y` variable. For
example, if the file that we want to add is a C file named :file:`<file>.c` the
following line should be added in the Makefile:
.. code-block:: make
obj-y += <file>.o
.. note::
The same method applies for assembly files with the .S extension.
Source files can be added conditionally using configuration options. For
example, if the option ``CONFIG_VAR`` is set and it implies that a source
file must be added in the compilation process, then the following line adds the
source code conditionally:
.. code-block:: none
obj-$(CONFIG_VAR) += <file>.o
Adding Directories
------------------
Add a subdirectory to the build system by editing the Makefile in its
directory. The subdirectory is added using the :literal:`obj-y` variable. The
correct syntax to add a subdirectory into the build queue is:
.. code-block:: make
obj-y += <directory_name>/
The backslash at the end of the directory name signals the build system that a
directory, and not a file, is being added to the build queue.
The conventions require us to add only one directory per line and never to mix
source code with directory recursion in a single :literal:`obj-y` line. This
helps keep the readability of the Makefile by making it clear when an item adds
an additional lever of recursion.
Directories can also be conditionally added:
.. code-block:: none
obj-y-$(CONFIG_VAR) += <directory_name>/
The subdirectory must contain its own Makefile following the rules described in
:ref:`makefile_conventions`.
Application Makefile
====================
Create an application Makefile to define basic information, such as the board
configuration used by the application. The build system uses the Makefile to
build a :file:`zephyr.elf` image that contains both the application and the
kernel libraries.
#. Open the :file:`Makefile` and add the following mandatory
entries using any standard text editor.
.. note::
Ensure that there is a space before and after each ``=``.
#. Add the name of the default board configuration for your application on a
new line:
.. code-block:: make
BOARD = board_configuration_name
The supported boards can be found in :ref:`board`.
#. Add the name of the default kernel configuration file for your
application on a new line:
.. code-block:: make
CONF_FILE ?= kernel_configuration_name
#. Include the mandatory :file:`Makefile` on a new line:
.. code-block:: make
include ${ZEPHYR_BASE}/Makefile.inc
#. Save and close the :file:`Makefile`.
Below is an example Makefile:
.. code-block:: make
BOARD = qemu_x86
CONF_FILE = prj.conf
include ${ZEPHYR_BASE}/Makefile.inc
Application Configuration
=========================
The application's kernel is configured using a set of configuration options
that can be customized for application-specific purposes.
The Zephyr build system takes a configuration option's value from the first
source in which it is specified.
The available sources are (in order):
#. The application's current configuration. (i.e. The :file:`.config` file.)
#. The application's default configuration. (i.e. The :file:`.conf` file.)
#. The board configuration used by the application.
(i.e. The board's :file:`.defconfig` file.)
#. The kernel's default configuration.
(i.e. One of the kernel's :file:`Kconfig` files.)
For information on available kernel configuration options, including
inter-dependencies between options, see the :ref:`configuration`.
Default Board Configuration
---------------------------
An application's :file:`.conf` file defines its default kernel configuration.
The settings in this file override or augment the board configuration settings.
The board configuration settings can be viewed
in :file:`\$ZEPHYR_BASE/boards/ARCHITECTURE/BOARD/BOARD_defconfig`.
.. note::
When the default board configuration settings are sufficient for your
application, a :file:`.conf` file is not needed. Skip ahead to
:ref:`override_kernel_conf`.
#. Navigate to the :file:`app`, and create the :file:`prj.conf` file. Enter:
.. code-block:: bash
$ vim prj.conf
The default name is :file:`prj.conf`. The filename must match the
``CONF_FILE`` entry in the application :file:`Makefile`.
#. Edit the file and add the appropriate configuration entries.
a) Add each configuration entry on a new line.
b) Begin each entry with ``CONFIG_``.
c) Ensure that each entry contains no spaces
(including on either side of the = sign).
d) Use a # followed by a space to comment a line.
The example below shows a comment line and a board
configuration override in the :file:`prj.conf`.
.. code-block:: c
# Enable printk for debugging
CONFIG_PRINTK=y
#. Save and close the file.
.. _override_kernel_conf:
Overriding Default Configuration
--------------------------------
Override the default board and kernel configuration to temporarily alter the
application's configuration, perhaps to test the effect of a change.
.. note::
If you want to permanently alter the configuration you
should revise the :file:`.conf` file.
Configure the kernel options using a menu-driven interface. While you can add
entries manually, using the configuration menu is a preferred method.
#. Run the :command:`make menuconfig` rule to launch the menu-driven interface.
a) In a terminal session, navigate to the application directory
(:file:`~/app`).
b) Enter the following command:
.. code-block:: bash
$ make [BOARD=<type>] menuconfig
A question-based menu opens that allows you to set individual configuration
options.
.. image:: figures/app_kernel_conf_1.png
:width: 400px
:align: center
:height: 375px
:alt: Main Configuration Menu
#. Set kernel configuration values using the following
key commands:
* Use the arrow keys to navigate within any menu or list.
* Press :kbd:`Enter` to select a menu item.
* Type an upper case :kbd:`Y` or :kbd:`N` in the
square brackets :guilabel:`[ ]` to
enable or disable a kernel configuration option.
* Type a numerical value in the round brackets :guilabel:`( )`.
* Press :kbd:`Tab` to navigate the command menu at the bottom of the display.
.. note::
When a non-default entry is selected for options that are nonnumerical,
an asterisk :kbd:`*` appears between the square brackets in the display.
There is nothing added added the display when you select the option's
default.
#. For information about any option, select the option and tab to
:guilabel:`<Help >` and press :kbd:`Enter`.
Press :kbd:`Enter` to return to the menu.
#. After configuring the kernel options for your application, tab to
:guilabel:`< Save >` and press :kbd:`Enter`.
The following dialog opens with the :guilabel:`< Ok >` command selected:
.. image:: figures/app_kernel_conf_2.png
:width: 400px
:align: center
:height: 100px
:alt: Save Configuration Dialog
#. Press :kbd:`Enter` to save the kernel configuration options to the default
file name; alternatively, type a file name and press :kbd:`Enter`.
Typically, you will save to the default file name unless you are
experimenting with various configuration scenarios.
An :file:`outdir` directory is created in the application directory. The
outdir directory contains symbolic links to files under
:file:`\$ZEPHYR_BASE`.
.. note::
At present, only a :file:`.config` file can be built. If you have saved
files with different file names and want to build with one of these,
change the file name to :file:`.config`. To keep your original
:file:`.config`, rename it to something other than :file:`.config`.
Kernel configuration files, such as the :file:`.config` file, are saved
as hidden files in :file:`outdir`. To list all your kernel configuration
files, enter :command:`ls -a` at the terminal prompt.
The following dialog opens, displaying the file name the configuration
was saved to.
.. image:: figures/app_kernel_conf_3.png
:width: 400px
:align: center
:height: 150px
:alt: Saved Configuration Name Dialog
#. Press :kbd:`Enter` to return to the options menu.
#. To load any saved kernel configuration file, tab to :guilabel:`< Load >` and
press :kbd:`Enter`.
The following dialog opens with the :guilabel:`< Ok >` command selected:
.. image:: figures/app_kernel_conf_4.png
:width: 400px
:align: center
:height: 175px
:alt: Configuration File Load Dialog
#. To load the last saved kernel configuration file, press :guilabel:`< Ok >`,
or to load another saved configuration file, type the file name, then select
:guilabel:`< Ok >`.
#. Press :kbd:`Enter` to load the file and return to the main menu.
#. To exit the menu configuration, tab to :guilabel:`< Exit >` and press
:kbd:`Enter`.
The following confirmation dialog opens with the :guilabel:`< Yes >`
command selected.
.. image:: figures/app_kernel_conf_5.png
:width: 400px
:align: center
:height: 100px
:alt: Exit Dialog
#. Press :kbd:`Enter` to retire the menu display and return to the console
command line.
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. The developer must supply a :file:`Makefile` for the
:file:`src` directory, as well as for each sub-directory under :file:`src`.
.. note::
These Makefiles are distinct from the top-level application Makefile
that appears in :file:`~/app`.
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://wiki.zephyrproject.org/view/Coding_conventions#Naming_Conventions>`_.
The following requirements apply to all Makefiles in the :file:`src`
directory, including any sub-directories it may have.
* During the build process, Kbuild identifies the source files to compile
into object files by matching the file names identified in
the application's Makefile(s).
.. important::
A source file that is not referenced by any Makefile is not included
when the application is built.
* A Makefile cannot directly reference source code. It can only
reference object files (:file:`.o` files) produced from source code files.
* A Makefile can only reference files in its own directory or in the
sub-directories of that directory.
* A Makefile may reference multiple files from a single-line entry.
However, a separate line must be used to reference each directory.
#. Create a directory structure for your source code in :file:`src`
and add your source code files to it.
#. Create a :file:`Makefile` in the :file:`src` directory. Then create
an additional :file:`Makefile` in each of the sub-directories under
the :file:`src` directory, if any.
a) Use the following syntax to add file references:
.. code-block:: make
obj-y += file1.o file2.o
b) Use the following syntax to add directory references:
.. code-block:: make
obj-y += directory_name/**
This example is taken from the Philosopher's Sample. To examine this file in
context, navigate to: :file:`\$ZEPHYR_BASE/samples/philosophers/src`.
.. code-block:: make
obj-y = main.o
Build an Application
====================
The Zephyr build system compiles and links all components of an application
into a single application image that can be run on simulated hardware or real
hardware.
#. Navigate to the application directory :file:`~/app`.
#. Enter the following command to build the application's :file:`zephyr.elf`
image using the configuration settings for the board type specified
in the application's :file:`Makefile`.
.. code-block:: console
$ make
If desired, you can build the application using the configuration settings
specified in an alternate :file:`.conf` file using the :code:`CONF_FILE`
parameter. These settings will override the settings in the application's
:file:`.config` file or its default :file:`.conf` file. For example:
.. code-block:: console
$ make CONF_FILE=prj.alternate.conf
If desired, you can build the application for a different board type than the
one specified in the application's :file:`Makefile` using the :code:`BOARD`
parameter. For example:
.. code-block:: console
$ make BOARD=arduino_101
Both the :code:`CONF_FILE` and :code:`BOARD` parameters can be specified
when building the application.
Rebuilding an Application
=========================
Application development is usually fastest when changes are continually tested.
Frequently rebuilding your application makes debugging less painful
as the application becomes more complex. It's usually a good idea to
rebuild and test after any major changes to the application's source files,
Makefiles, or configuration settings.
.. important::
The Zephyr build system rebuilds only the parts of the application image
potentially affected by the changes. Consequently, rebuilding an application
is often significantly faster than building it the first time.
Sometimes the build system doesn't rebuild the application correctly
because it fails to recompile one or more necessary files. You can force
the build system to rebuild the entire application from scratch with the
following procedure:
#. Navigate to the application directory :file:`~/app`.
#. Enter the following command to delete the application's generated files
for the specified board type, except for the :file:`.config` file that
contains the application's current configuration information.
.. code-block:: console
$ make [BOARD=<type>] clean
Alternatively, enter the following command to delete *all* generated files
for *all* board types, including the :file:`.config` files that contain
the application's current configuration information for those board types.
.. code-block:: console
$ make pristine
#. Rebuild the application normally following the steps specified
in `Build an Application`_ above.
Run an Application
==================
An application image can be run on real or emulated hardware. The kernel has
built-in emulator support for QEMU. It allows you to run and test an application
virtually, before (or in lieu of) loading and running it on actual target
hardware.
#. Open a terminal console and navigate to the application directory
:file:`~/app`.
#. Enter the following command to build and run the application
using a QEMU-supported board configuration, such as qemu_cortex_m3 or
qemu_x86.
.. code-block:: console
$ make [BOARD=<type> ...] qemu
The Zephyr build system generates a :file:`zephyr.elf` image file
and then begins running it in the terminal console.
#. Press :kbd:`Ctrl A, X` to stop the application from running
in QEMU.
The application stops running and the terminal console prompt
redisplays.
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 on
`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 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 ELF binary image for debugging purposes.
The build system generates the image in the output 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 system.
QEMU is the supported emulation system of the kernel. QEMU must be invoked
with the -s and -S options.
* ``-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.
The build system can build the elf binary and call the QEMU process with
the :makevar:`qemu` target. The QEMU debug options can be set using the
environment variable :envvar:`QEMU_EXTRA_FLAGS`. To set the ``-s`` and
``-S`` options:
.. code-block:: bash
export QEMU_EXTRA_FLAGS="-s -S"
The build and emulation processes are called with the Makefile ``qemu``
target:
.. code-block:: bash
make qemu
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.
The :file:`.gdbinit` will 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 ZEPHYR_BASE for the current kernel's root directory.
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
gdb --tui zephyr.elf
.. note::
The GDB version on the development system might not support the --tui
option.
Finally, this command 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.
.. 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.

View file

@ -1,117 +0,0 @@
.. _apps_build:
Build an Application
####################
The Zephyr build system compiles and links all components of an application
into a single application image that can be run on simulated hardware or real
hardware.
.. contents:: Procedures
:local:
:depth: 1
Building an Application
=======================
The build system allows you to easily build an application using the
application's existing configuration. However, you can also build it
using different configuration settings, if desired.
Before you begin
----------------
* Ensure you have added all application-specific code to the application
directory, as described in :ref:`apps_code_dev`. Ensure each source code
directory and sub-directory has its own :file:`Makefile`.
* Ensure you have configured the application's kernel, as described
in :ref:`apps_kernel_conf`.
* Ensure the Zephyr environment variables are set for each console terminal;
see :ref:`apps_common_procedures`.
Steps
-----
#. Navigate to the application directory :file:`~/appDir`.
#. Enter the following command to build the application's :file:`zephyr.elf`
image using the configuration settings for the board type specified
in the application's :file:`Makefile`.
.. code-block:: console
$ make
If desired, you can build the application using the configuration settings
specified in an alternate :file:`.conf` file using the :code:`CONF_FILE`
parameter. These settings will override the settings in the application's
:file:`.config` file or its default :file:`.conf` file. For example:
.. code-block:: console
$ make CONF_FILE=prj.alternate.conf
If desired, you can build the application for a different board type
than the one specified in the application's :file:`Makefile`
using the :code:`BOARD` parameter. For example:
.. code-block:: console
$ make BOARD=arduino_101
Both the :code:`CONF_FILE` and :code:`BOARD` parameters can be specified
when building the application.
Rebuilding an Application
=========================
Application development is usually fastest when changes are continually tested.
Frequently rebuilding your application makes debugging less painful
as the application becomes more complex. It's usually a good idea to
rebuild and test after any major changes to the application's source files,
Makefiles, or configuration settings.
.. important::
The Zephyr build system rebuilds only the parts of the application image
potentially affected by the changes. Consequently, rebuilding an application
is often significantly faster than building it the first time.
Steps
-----
#. Follow the steps specified in `Building an Application`_ above.
Recovering from a Build Failure
===============================
Sometimes the build system doesn't rebuild the application correctly
because it fails to recompile one or more necessary files. You can force
the build system to rebuild the entire application from scratch with the
following procedure:
Steps
-----
#. Navigate to the application directory :file:`~/appDir`.
#. Enter the following command to delete the application's generated files
for the specified board type, except for the :file:`.config` file that
contains the application's current configuration information.
.. code-block:: console
$ make [BOARD=<type>] clean
Alternatively, enter the following command to delete *all* generated files
for *all* board types, including the :file:`.config` files that contain
the application's current configuration information for those board types.
.. code-block:: console
$ make pristine
#. Rebuild the application normally following the steps specified
in `Building an Application`_ above.

View file

@ -1,152 +0,0 @@
.. _apps_code_dev:
Add Application-Specific Code
#############################
Application-specific source code is typically added to an application
by placing it in the application directory itself (:file:`~/appDir`).
However, in some cases an application may also need to modify
or enhance the kernel itself.
.. contents:: Procedures
:local:
:depth: 1
Adding Source Code to an Application Directory
**********************************************
Understanding Source Code Requirements
======================================
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. The developer must supply a :file:`Makefile`
for the :file:`src` directory, as well as for each sub-directory under
:file:`src`.
.. note::
These Makefiles are distinct from the top-level application Makefile
that appears in :file:`~/appDir`.
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://wiki.zephyrproject.org/view/Coding_conventions#Naming_Conventions>`_.
Understanding Makefile Requirements
===================================
The following requirements apply to all Makefiles in the :file:`src`
directory, including any sub-directories it may have.
* During the build process, Kbuild identifies the source files to compile
into object files by matching the file names identified in
the application's Makefile(s).
.. important::
A source file that is not referenced by any Makefile is not included
when the application is built.
* A Makefile cannot directly reference source code. It can only
reference object files (:file:`.o` files) produced from source code files.
* A Makefile can only reference files in its own directory or in the
sub-directories of that directory.
* A Makefile may reference multiple files from a single-line entry.
However, a separate line must be used to reference each directory.
Before You Begin
-----------------
* Ensure you have created an application directory, as described
in :ref:`apps_structure`.
* The Zephyr environment variable must be set for each console
terminal using :ref:`apps_common_procedures`.
* Many useful code examples cam be found at :file:`\$ZEPHYR_BASE/samples`.
Steps
-----
#. Create a directory structure for your source code in :file:`src`
and add your source code files to it.
#. Create a :file:`Makefile` in the :file:`src` directory. Then create
an additional :file:`Makefile` in each of the sub-directories under
the :file:`src` directory, if any.
a) Use the following syntax to add file references:
.. code-block:: make
obj-y += file1.o file2.o
b) Use the following syntax to add directory references:
.. code-block:: make
obj-y += directory_name/**
Example src Makefile
--------------------
This example is taken from the Philosopher's Sample. To
examine this file in context, navigate to:
:file:`\$ZEPHYR_BASE/samples/philosophers/src`.
.. code-block:: make
obj-y = main.o
Modifying and Enhancing the Kernel
**********************************
Subsystem Naming Conventions
============================
When enhancing an existing kernel subsystem be sure to follow
any existing naming conventions.
For more information, see
`Naming Conventions <https://wiki.zephyrproject.org/view/Coding_conventions#Naming_Conventions>`_.
When creating a new subsystem, the subsystem can define its own naming
conventions for symbols. However, naming conventions should be implemented
with a unique namespace prefix (e.g. bt\_ for BlueTooth, or net\_ for IP) to
limit possible clashes with applications. Naming within a subsystem
should continue to follow prefix conventions identified above; this
keeps consistent interface for all users.
Include Paths Usage Guidelines
==============================
Do not add unnecessary include paths to system or default include paths,
as this can lead to ambiguous references when two or more directories
contain a file with the same name.
The only include path into :file:`\$ZEPHYR_BASE/include` should be
:file:`\$ZEPHYR_BASE/include` itself.
Source files should use :code:`#include` directives that specify the full path
from a common include directory. For example, you should always use
directives of the form :code:`#include <path/to/[header].h>`, and not
use directives of the form :code:`#include <[header].h>`.
The following example illustrates the kind of problems that can arise when
unnecessary default include paths are specified.
* Observe that the kernel contains both :file:`include/pci.h` and
:file:`include/drivers/pci.h`.
* If both the :file:`include` and :file:`include/drivers` directories
are added to the default include paths (e.g.
:code:`gcc -Iinclude/drivers -Iinclude [...]`), then the directive
:code:`#include <pci.h>` becomes ambiguous.
The solution is to avoid adding :file:`include/drivers` to the default
include paths. Source files can then reference either :code:`#include <pci.h>`
or :code:`#include <drivers/pci.h>`, as needed.

View file

@ -1,38 +0,0 @@
.. _apps_common_procedures:
Common Procedures
#################
Instructions that are common to many procedures are provided here
and referred to from the procedures that require them.
Procedures
**********
.. _set_environment_variables:
Setting Environment Variables
=============================
Set environment variables every time you open a terminal console to work on
applications.
Steps
-----
1. In a shell terminal console, enter an :command:`export` command that is
consistent with your toolchain.
For the Zephyr SDK:
.. code-block:: console
$ export ZEPHYR_GCC_VARIANT=zephyr
$ export ZEPHYR_SDK_INSTALL_DIR=<yocto-installation-path>
2. To set the environment variable :envvar:`\$ZEPHYR_BASE`, navigate to the
kernel's installation directory and enter:
.. code-block:: console
$ source zephyr-env.sh

View file

@ -1,256 +0,0 @@
.. _apps_kernel_conf:
Configure an Application's Kernel
#################################
The application's kernel is configured using a set of configuration options
that can be customized for application-specific purposes.
The Zephyr build system takes a configuration option's value
from the first source in which it is specified.
The available sources are (in order):
#. The application's current configuration.
(i.e. The :file:`.config` file.)
#. The application's default configuration.
(i.e. The :file:`.conf` file.)
#. The board configuration used by the application.
(i.e. The board's :file:`.defconfig` file.)
#. The kernel's default configuration.
(i.e. One of the kernel's :file:`Kconfig` files.)
For information on available kernel configuration options, including
inter-dependencies between options, see the :ref:`configuration`.
Be careful to note if an option is an experimental option
that is not yet fully supported.
.. contents:: Procedures
:local:
:depth: 1
Defining the Application's Default Kernel Configuration
=======================================================
An application's :file:`.conf` file defines its default kernel configuration.
The settings in this file override or augment the board configuration settings.
The board configuration settings can be viewed
in :file:`\$ZEPHYR_BASE/boards/ARCHITECTURE/BOARD/BOARD_defconfig`.
.. note::
When the default board configuration settings are sufficient for your
application, a :file:`.conf` file is not needed. Skip ahead to
:ref:`override_kernel_conf`.
Before you begin
----------------
* Ensure you have created an application directory, as described
in :ref:`apps_structure`.
* Review the kernel configuration options available and know
which ones you want to set for your application.
Be aware of any dependencies involving these options.
See the :ref:`configuration` for a brief description of each option.
Steps
-----
1. Navigate to the :file:`appDir`, and create the :file:`prj.conf` file. Enter:
.. code-block:: bash
$ touch prj.conf
The default name is :file:`prj.conf`. The filename must match
the ``CONF_FILE`` entry in the application :file:`Makefile`.
2. Edit the file and add the appropriate configuration entries.
a) Add each configuration entry on a new line.
b) Begin each entry with ``CONFIG_``.
c) Ensure that each entry contains no spaces
(including on either side of the = sign).
d) Use a # followed by a space to comment a line.
The example below shows a comment line and a board
configuration override in the :file:`prj.conf`.
.. code-block:: c
# Change the number of IRQs supported by the application
CONFIG_NUM_IRQS=43
3. Save and close the file.
.. _override_kernel_conf:
Overriding the Application's Default Kernel Configuration
=========================================================
Override the application's default kernel configuration to
temporarily alter the application's configuration, perhaps
to test the effect of a change.
.. note::
If you want to permanently alter the configuration you
should revise the :file:`.conf` file.
Configure the kernel options using a menu-driven interface.
While you can add entries manually, using the configuration menu
is a preferred method.
Before you begin
----------------
* Ensure you have created an application directory, as described
in :ref:`apps_structure`.
* Review the kernel configuration options available and know
which ones you want to set for your application.
Be aware of any dependencies involving these options.
* Ensure the Zephyr environment variables are set for each console terminal;
see :ref:`apps_common_procedures`.
Steps
-----
1. Run the :command:`make menuconfig` rule to launch the
menu-driven interface.
a) In a terminal session, navigate to the application directory
(:file:`~/appDir`).
b) Enter the following command:
.. code-block:: bash
$ make [BOARD=<type>] menuconfig
A question-based menu opens that allows you to set individual
configuration options.
.. image:: figures/app_kernel_conf_1.png
:width: 400px
:align: center
:height: 375px
:alt: Main Configuration Menu
2. Set kernel configuration values using the following
key commands:
* Use the arrow keys to navigate within any menu or list.
* Press :kbd:`Enter` to select a menu item.
* Type an upper case :kbd:`Y` or :kbd:`N` in the
square brackets :guilabel:`[ ]` to
enable or disable a kernel configuration option.
* Type a numerical value in the round brackets :guilabel:`( )`.
* Press :kbd:`Tab` to navigate the command menu at the
bottom of the display.
.. note::
When a non-default entry is selected for options that
are nonnumerical, an asterisk :kbd:`*` appears between the
square brackets in the display. There is nothing added added
the display when you select the option's default.
3. For information about any option, select the option and
tab to :guilabel:`< Help >` and press :kbd:`Enter`.
Press :kbd:`Enter` to return to the menu.
4. After configuring the kernel options for your application,
tab to :guilabel:`< Save >` and press :kbd:`Enter`.
The following dialog opens with the :guilabel:`< Ok >`
command selected:
.. image:: figures/app_kernel_conf_2.png
:width: 400px
:align: center
:height: 100px
:alt: Save Configuration Dialog
5. Press :kbd:`Enter` to save the kernel configuration options
to the default file name; alternatively, type a file
name and press :kbd:`Enter`.
Typically, you will save to the default file name unless
you are experimenting with various configuration scenarios.
An :file:`outdir` directory is created in the application
directory. The outdir directory contains symbolic links
to files under :file:`\$ZEPHYR_BASE`.
.. note::
At present, only a :file:`.config` file can be built. If
you have saved files with different file names and want to build
with one of these, change the file name to :file:`.config`.
To keep your original :file:`.config`, rename it to something
other than :file:`.config`.
Kernel configuration files, such as the :file:`.config`
file, are saved as hidden files in :file:`outdir`. To list
all your kernel configuration files, enter :command:`ls -a`
at the terminal prompt.
The following dialog opens, displaying the file name the
configuration was saved to.
.. image:: figures/app_kernel_conf_3.png
:width: 400px
:align: center
:height: 150px
:alt: Saved Configuration Name Dialog
6. Press :kbd:`Enter` to return to the options menu.
7. To load any saved kernel configuration file,
tab to :guilabel:`< Load >` and press :kbd:`Enter`.
The following dialog opens with the :guilabel:`< Ok >`
command selected:
.. image:: figures/app_kernel_conf_4.png
:width: 400px
:align: center
:height: 175px
:alt: Configuration File Load Dialog
8. To load the last saved kernel configuration file, press
:guilabel:`< Ok >`, or to load another saved configuration
file, type the file name, then select :guilabel:`< Ok >`.
9. Press :kbd:`Enter` to load the file and return to the main
menu.
10. To exit the menu configuration, tab to :guilabel:`< Exit >`
and press :kbd:`Enter`.
The following confirmation dialog opens with the
:guilabel:`< Yes >` command selected.
.. image:: figures/app_kernel_conf_5.png
:width: 400px
:align: center
:height: 100px
:alt: Exit Dialog
11. Press :kbd:`Enter` to retire the menu display and
return to the console command line.

View file

@ -1,37 +0,0 @@
.. _apps_overview:
Application Overview
####################
A Zephyr application is a collection of user-supplied files that can be built
into an application image that executes on a board.
Each application resides in a distinct directory created by the developer.
The directory has the following structure.
* **Application source code files**: An application typically provides one
or more application-specific files, written in C or assembly language. These
files are usually located in a sub-directory called :file:`src`.
* **Kernel configuration files**: An application typically provides
a configuration file (:file:`.conf`) that specifies values for one or more
kernel configuration options. If omitted, the application's existing kernel
configuration option values are used; if no existing values are provided,
the kernel's default configuration values are used.
* **Makefile**: This file typically contains a handful of lines that tell
the build system where to find the files mentioned above, as well as
the desired target board configuration.
Once the application has been defined, it can be built with a single command.
The results of the build process are located in a sub-directory
called :file:`outdir/BOARD`. This directory contains the files generated
by the build process, the most notable of which are listed below.
* The :file:`.config` file that contains the configuration settings
used to build the application.
* The various object files (:file:`.o` files and :file:`.a` files) containing
custom-built kernel and application-specific code.
* The :file:`zephyr.elf` file that contains the final application image.

View file

@ -1,58 +0,0 @@
.. _apps_run:
Run an Application
##################
An appliction image can be run on real or simulated hardware.
The kernel's built-in simulator is QEMU. It allows you to run and test
an application virtually, before (or in lieu of)
loading and running it on actual target hardware.
.. contents:: Procedures
:local:
:depth: 1
Running an Application using QEMU
=================================
Prerequisites
-------------
* Ensure the application can be built successfully using a QEMU-supported
board configuration, such as qemu_cortex_m3 or qemu_x86, as described
in :ref:`apps_build`.
* Ensure the Zephyr environment variables are set for each console terminal;
see :ref:`apps_common_procedures`.
Steps
-----
#. Open a terminal console and navigate to the application directory
:file:`~/appDir`.
#. Enter the following command to build and run the application
using a QEMU-supported board configuration,
such as qemu_cortex_m3 or qemu_x86.
.. code-block:: console
$ make [BOARD=<type> ...] qemu
The Zephyr build system generates a :file:`zephyr.elf` image file
and then begins running it in the terminal console.
#. Press :kbd:`Ctrl A, X` to stop the application from running
in QEMU.
The application stops running and the terminal console prompt
redisplays.
Loading and Running an Application on Target Hardware
=====================================================
The procedure required to load an application image (:file:`zephyr.elf`)
on a target depends on the functionality available on its hardware,
and is often unique to that target board.
For this reason, loading instructions reside with the board-specific
documentation; see :ref:`board`.

View file

@ -1,166 +0,0 @@
.. _apps_structure:
Create an Application Directory
###############################
Each application resides in a uniquely-named application
directory created by the developer, typically in the developer's
workspace directory. The application developer also creates a
:file:`src` directory for the application's source code.
.. contents:: Procedures
:local:
:depth: 1
Creating an Application and Source Code Directory
=================================================
Create one directory for your application and a sub-directory for the
application's source code; this makes it easier to organize directories
and files in the structure that the kernel expects.
Before You Begin
----------------
* Ensure the Zephyr environment variables are set for each console terminal;
see :ref:`apps_common_procedures`.
Steps
-----
1. Create an application directory structure outside of the kernel's
installation directory tree. Often this is your workspace directory.
a) In a console terminal, navigate to a location where you want your
application to reside.
b) Create the application's directory, enter:
.. code-block:: console
$ mkdir application_name
.. note::
This directory and the path to it, are referred to in the documentation
as :file:`~/appDir`.
2. Create a source code directory in your :file:`~/appDir`, enter:
.. code-block:: console
$ mkdir src
The source code directory :file:`~/appDir/src` is created.
.. code-block:: console
-- appDir
|-- src
Creating an Application Makefile
================================
Create an application Makefile to define basic information,
such as the board configuration used by the application.
The build system uses the Makefile to build a :file:`zephyr.elf` image
that contains both the application and the kernel libraries.
Before You Begin
----------------
* Be familiar with the standard GNU Make language.
* Be familiar with the board configuration used for your application
and, if it is a custom board configuration, where it is located.
* Ensure the Zephyr environment variables are set for each console terminal;
see :ref:`apps_common_procedures`.
Steps
-----
1. In the :file:`appDir` directory, create a Makefile. Enter:
.. code-block:: bash
$ touch Makefile
2. Open the :file:`Makefile` and add the following mandatory
entries using any standard text editor.
.. note::
Ensure that there is a space after each ``=``.
a) Add the name of the default board configuration for your application on a
new line:
.. code-block:: make
BOARD ?= board_configuration_name
The supported boards can be found in :ref:`board`.
b) Add the name of the default kernel configuration file for your
application on a new line:
.. code-block:: make
CONF_FILE ?= kernel_configuration_name
The default kernel configuration file entry may be omitted if the file
is called :file:`prj.conf`. It may also be omitted if the default board
configuration's kernel settings are sufficient for your application.
c) Include the mandatory :file:`Makefile` fragments on a new line:
.. code-block:: make
include ${ZEPHYR_BASE}/Makefile.inc
3. Save and close the :file:`Makefile`.
Example Makefile
----------------
.. code-block:: make
BOARD ?= qemu_x86
CONF_FILE ?= prj.conf
include ${ZEPHYR_BASE}/Makefile.inc
Support for building third-party library code
=============================================
When building library code 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 project
build system includes a special build target, ``outputexports``, that takes a
number of critical variables from the Zephyr project build system and copies
them into :file:`Makefile.export`. This allows the critical variables to be
included by wrapper code for use in a third-party build system.
The following variables are recommended for use within the third-party build (see
:file:`Makefile.export` for the complete list of exported variables):
* ``CROSS_COMPILE``, together with related convenience variables to call the
cross-tools directly (including ``AR``, ``AS``, ``CC``, ``CXX``, ``CPP``
and ``LD``).
* ``ARCH`` and ``BOARD``, together with several variables that identify the
Zephyr kernel version.
* ``KBUILD_CFLAGS``, ``NOSTDINC_FLAGS`` and ``ZEPHYRINCLUDE`` all of which
should normally be added, in that order, to ``CFLAGS`` (or
``CXXFLAGS``).
* All kconfig variables, allowing features of the library code to be
enabled/disabled automatically based on the Zephyr kernel configuration.
:file:`samples/static_lib` is a sample project that demonstrates
some of these features.

View file

@ -32,13 +32,13 @@ Sections
getting_started/getting_started.rst
board/board.rst
kernel/kernel.rst
application/application.rst
porting/porting.rst
drivers/drivers.rst
subsystems/subsystems.rst
api/api.rst
application/application.rst
reference/kconfig/index.rst
contribute/code.rst
porting/porting.rst
reference/kbuild/kbuild.rst
LICENSING.rst
You can find further information on the `Zephyr Project Wiki`_.

View file

@ -5,7 +5,7 @@ Zephyr Kernel Primer (version 2)
This document provides a general introduction of the Zephyr kernel's
key capabilties and services. Additional details can be found by consulting
the :ref:`api` and :ref:`apps_kernel_conf` documentation, and by examining
the :ref:`api` and :ref:`application` documentation, and by examining
the code in the Zephyr source tree.
.. toctree::

View file

@ -1,21 +0,0 @@
.. _kbuild:
Build System User Guide
#######################
The Zephyr Kernel's build system is based on the Kbuild system used in the
Linux kernel. This way the kernel embraces the recursive model used in Linux
and the configuration model implemented using Kconfig.
The build process is driven by applications, unlike the Linux Kbuild
system. Therefore, the build system requires an application to initiate building
the kernel source code. The build system compiles the kernel and the application
into a single image.
.. toctree::
:maxdepth: 1
kbuild_kconfig
../kconfig/index.rst
kbuild_makefiles
kbuild_project

View file

@ -1,114 +0,0 @@
.. _kconfig:
The Kconfig File Structure
**************************
Introduction
============
The Kconfig files describe: the configuration symbols supported in the build
system, the logical organization and structure to group the symbols in menus
and sub-menus, and the relationships between the different configuration
symbols that govern the valid configuration combinations.
The Kconfig files are distributed across the build directory tree. The files
are organized based on their common characteristics and on what new symbols
they add to the configuration menus. For example:
* The Kconfig file at the root directory contains the general
configuration options like :option:`CONFIG_ARCH` and
``CONFIG_KERNEL VERSION``. These symbols are defined for and
apply to the entire build system.
* The Kconfig file at the :file:`kernel` directory contains the general
configuration related to the core kernel.
* The Kconfig file at the :file:`drivers` directory organizes the inclusion of
the various Kconfig files needed for each supported driver in the system.
* The Kconfig file at the :file:`misc` directory contains the
configuration symbols that affect different aspects of the build
system. For example, the *Custom Compiler Options* and the
``Minimal Libc`` are general build options that apply to the build
system. *Debugging Options* and *System Monitoring Options* are
also examples of build options that apply to the entire system.
* The Kconfig file at the :file:`net` directory contains the different symbols
that define the configuration options for the communications stack code.
* The Kconfig file at the :file:`crypto` directory contains the different
symbols that define the configuration options for the cryptography algorithms
supported.
Dependencies
============
Dependencies allow you to define the valid and invalid configuration
combinations in the system. Each dependency is a rule that a particular symbol
must follow to be either selected or allowed to have a specific value. For
example, the configuration symbol *B* states a dependency on another one, *A*.
.. code-block:: kconfig
config B bool
config A depends on B
The symbol A does not exist as a configuration option in the system unless B is
set to true.
The complete set of dependency rules defines the valid configuration
combinations that the system can use.
Default Configurations
======================
The default configuration files define the default configuration for a specific
kernel on a specific SoC. For example:
* :file:`arch/arm/configs`,
* :file:`arch/x86/configs` and
* :file:`arch/arc/configs`.
All the default configuration files must end with the suffix _defconfig. For
example, the :file:`galileo_defconfig` file contains the configuration
information for the galileo board.
The :file:`Makefile.inc` file uses defconfig files to provide a clean interface
to developers using environment variables to define the kernel type and the
board of new projects. Developers can provide the build system with a
target's defconfig. The build system takes the specified defconfig file and
sets it as the current :file:`.config` file for the current project. For
example:
.. code-block:: console
$ make galileo_defconfig
The command takes the default configuration for the architecture
and the galileo board configuration to compile the kernel.
.. _configuration_snippets:
Merging Configuration Fragments
===============================
Configuration file fragment can be merged with the current project
configuration during the build.
Developers can provide a configuration file that defines a small subset of
configuration options. The subset must contain the specific configuration
options that differ from the default configuration.
The **initconfig** target pulls the default configuration file and merges it
with the local configuration fragments. For example, the sample application **hello
world** overrides the base configuration with the configuration fragment in
:file:`prj.conf`.
.. caution::
Invalid configurations, or configurations that do not comply with
the dependencies stated in the Kconfig files, are ignored by the merge process.
When adding configuration options through a configuration fragment, ensure that
the complete sequence complies with the dependency rules defined in the
Kconfig files.

View file

@ -1,96 +0,0 @@
.. _kbuild_makefiles:
The Makefiles
*************
Overview
========
The build system defines a set of conventions for the correct use of Makefiles
in the kernel source directories. The correct use of Makefiles is driven by the
concept of recursion.
In the recursion model, each Makefile within a directory includes the source
code and any subdirectories to the build process. Each subdirectory follows
the same principle. Developers can focus exclusively in their own work. They
integrate their module with the build system by adding a very simple Makefile
following the recursive model.
.. _makefile_conventions:
Makefile Conventions
====================
The following conventions restrict how to add modules and Makefiles to the
build system. These conventions guard the correct implementation of the
recursive model.
* Each source code directory must contain a single Makefile. Directories
without a Makefile are not considered source code directories.
* The scope of every Makefile is restricted to the contents of that directory.
A Makefile can only make a direct reference to its own files and subdirectories.
Any file outside the directory has to be referenced in its home directory Makefile.
* Makefiles list the object files that are included in the link process. The
build system finds the source file that generates the object file by matching
the file name.
* Parent directories add their child directories into the recursion model.
* The root Makefile adds the directories in the kernel base directory into the
recursion model.
Adding Source Files
===================
A source file is added to the build system through its home directory Makefile.
The Makefile must refer the source build indirectly, specifying the object file
that results from the source file using the :literal:`obj-y` variable. For
example, if the file that we want to add is a C file named :file:`<file>.c` the
following line should be added in the Makefile:
.. code-block:: make
obj-y += <file>.o
.. note::
The same method applies for assembly files with .s extension.
Source files can be added conditionally using configuration options. For
example, if the option ``CONFIG_VAR`` is set and it implies that a source
file must be added in the compilation process, then the following line adds the
source code conditionally:
.. code-block:: none
obj-$(CONFIG_VAR) += <file>.o
Adding Directories
==================
Add a subdirectory to the build system by editing the Makefile in its
directory. The subdirectory is added using the :literal:`obj-y` variable. The
correct syntax to add a subdirectory into the recursion is:
.. code-block:: make
obj-y += <directory_name>/
The backslash at the end of the directory name signals the build system that a
directory, and not a file, is being added to the recursion.
The conventions require us to add only one directory per line and never to mix
source code with directory recursion in a single :literal:`obj-y` line. This
helps keep the readability of the Makefile by making it clear when an item adds
an additional lever of recursion.
Directories can also be conditionally added:
.. code-block:: none
obj-y-$(CONFIG_VAR) += <directory_name>/
The subdirectory must contain its own Makefile following the rules described in
:ref:`makefile_conventions`.

View file

@ -1,194 +0,0 @@
.. _kbuild_project:
Developing an Application and the Build System
**********************************************
The build system is an application centric system. The application drives the
configuration and build process of the kernel binary.
Application development can be organized in three independent directories:
the kernel base directory, the project directory, and the project source code
directory.
The Zephyr Kernel's base directory hosts the kernel source code, the
configuration options, and the kernel build definitions.
The application directory is the directory that puts together the kernel with
the developer's application. It hosts the definitions of the developers'
applications. For example, application-specific configuration options and the
application's
source code.
The Application Project
=======================
A common application project is composed of the following files:
* **Makefile**: Defines the application's build process and integrates the
developer's application with the kernel's build system.
* **Configuration file**: Allows the developer to override the board's
default configuration.
* **The :file:`src/` directory**: By default, this directory hosts the
application's source code. This location can be overridden and defined in a
different directory.
* **Makefile**: Adds the developer's source code into the build system's
recursion model.
The application's source code can be organized in subdirectories.
Each directory must follow the Kbuild Makefile conventions; see
:ref:`kbuild_makefiles`.
Application Definition
======================
The developer defines the relationship of application to build system through
the Makefiles. The application is integrated into the build system by
including the Makefile.inc file provided.
.. code-block:: make
include $(ZEPHYR_BASE)/Makefile.inc
The following predefined variables configure the development project:
* :makevar:`ARCH`: Specifies the build architecture for the kernel. The
architectures currently supported are x86, arm and arc. The build system
sets C flags, selects the default configuration and uses the appropriate
toolchain tools. The default value is x86.
* :makevar:`ZEPHYR_BASE`: Sets the path to the kernel's base directory.
This variable is usually set by the :file:`zephyr_env.sh` script.
It can be used to get the kernel's base directory, as used in the
Makefile.inc inclusion above, or it can be overridden to select an
specific instance of the kernel.
* :makevar:`PROJECT_BASE`: Provides the developer's application project
directory path. It is set by the :file:`Makefile.inc` file.
* :makevar:`SOURCE_DIR`: Overrides the default value for the application's
source code directory. The developer source code directory is set to
:file:`$(PROJECT_BASE/)src/` by default. This directory name should end
with slash **'/'**.
* :makevar:`BOARD`: Selects the board that the application's
build will use for the default configuration.
* :makevar:`CONF_FILE`: Indicates the name of a configuration fragment file.
This file includes the kconfig configuration values that override the
default configuration values.
* :makevar:`O`: Optional. Indicates the output directory that Kconfig uses.
The output directory stores all the files generated during the build
process. The default output directory is the :file:`$(PROJECT_BASE)/outdir`
directory.
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 on
`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 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 ELF binary image for debugging purposes.
The build system generates the image in the output directory.
By default, the kernel binary name is :file:`zephyr.elf`. The name can be
changed using Kconfig.
.. note::
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 system.
QEMU is the supported emulation system of the kernel. QEMU must be invoked
with the -s and -S options.
* ``-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.
The build system can build the elf binary and call the QEMU process with
the :makevar:`qemu` target. The QEMU debug options can be set using the
environment variable :envvar:`QEMU_EXTRA_FLAGS`. To set the ``-s`` and
``-S`` options:
.. code-block:: bash
export QEMU_EXTRA_FLAGS="-s -S"
The build and emulation processes are called with the Makefile ``qemu``
target:
.. code-block:: bash
make qemu
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.
The :file:`.gdbinit` will 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 ZEPHYR_BASE for the current kernel's root directory.
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
gdb --tui zephyr.elf
.. note::
The GDB version on the development system might not support the --tui
option.
Finally, this command 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.
.. note::
The :abbr:`DDD (Data Displayer Debugger)` may not be installed in your
development system by default. Follow your system instructions to install
it.
.. code-block:: bash
ddd --gdb --debugger "gdb zephyr.elf"
.. note::
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.