doc/application/apps_structure.rst

.. _apps_structure:

Application Development Directory Structure
###########################################

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.

.. note::

   The Zephyr Kernel either supplies or generates all other application
   directories.

Procedures
**********

* `create_directory_structure`_

* `create_src_makefile`_

.. _create_directory_structure:

Creating an Application and Source Code Directory using the CLI
===============================================================

Create one directory for your application and another 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
----------------

* The environment variable must be set for each console terminal using
  :ref:`set_environment_variables`.

Steps
-----

1. Create an application directory structure outside of the kernel's
   installation directory tree. Often this is your workspace directory.

 a) In a Linux console, navigate to a location where you want your
    applications 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

.. _create_src_makefile:

Creating an Application Makefile
================================

Create an application Makefile to define basic information such as the kernel
type, microkernel or nanokernel, and the board configuration used by the
application. The build system uses the Makefile to build an image with both
the application and the kernel libraries called either
:file:`microkernel.elf` or :file:`nanokernel.elf`.

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.

* Set the environment variable for each console terminal using
  :ref:`set_environment_variables`.

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 kernel type on a new line:

      .. code-block:: make

         KERNEL_TYPE = micro|nano

      Either micro or nano, short for microkernel or
      nanokernel respectively.

   b) Add the name of the 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`.

   c) Add the name of the default kernel configuration file for your
      application on a new line:

      .. code-block:: make

         CONF_FILE = prj.conf

      The default name is :file:`prj.conf`. If you are not using the default
      name, this entry must match the filename of the :file:`.conf` file you
      are using.

   d) For microkernel applications, add the name of the MDEF for your
      application:

      .. code-block:: make

         MDEF_FILE = prj.mdef

      The default name is :file:`prj.mdef`. If you are not using the default
      name, this entry must match the filename of the :file:`.mdef` file you
      are using.

   e) 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

   KERNEL_TYPE = micro
   BOARD ?= qemu_x86
   CONF_FILE = prj.conf
   MDEF_FILE = prj.mdef
   include ${ZEPHYR_BASE}/Makefile.inc