doc/application/apps_structure.rst

.. _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.