doc/application/apps_code_dev.rst

.. _apps_code_dev:

Application Code Development
############################

.. contents::
   :local:
   :depth: 1

.. _develop_services:

Services
********

The Zephyr kernel services architecture has services that are
specific to the microkernel, services that are specific to the
nanokernel, and services that are common, or shared, between the
two.

Microkernel Services
====================

For a complete list of microkernel services, including a description
of each with code examples, see :ref:`microkernel`.

.. note::

   There are more microkernel services than those defined in
   the MDEF.

Nanokernel Services
===================

For a complete list of nanokernel services, including a description
of each with code examples, see :ref:`nanokernel`.

Common Services
===============

For a complete list of services common to both the nanokernel and
microkernel, including a description of each with code examples,
see :ref:`common`.


Procedures and Conventions
**************************

Understanding Naming Conventions
================================

The kernel limits the use of some prefixes to internal use only. For
more information, see `naming conventions`_.

.. _naming conventions: https://wiki.zephyrproject.org/view/Coding_conventions#Naming_Conventions

.. _src_makefiles_reqs:

Understanding src Directory Makefile Requirements
=================================================

The src directory needs a Makefile to specify how to build the application
source code. Likewise, any sub-directory within src must also have its own
Makefile. The following requirements apply to all Makefiles in the src
directory:

* A Makefile must reference only its own files and sub-directories.

* Code that references a file outside the directory cannot be included in the
  Makefile; the referenced file is included only in its own directory's
  Makefile.

* A Makefile cannot directly reference source code; it can only
  reference object files (.o files) produced by source code.

 .. note::

   The src directory Makefiles discussed here are distinct from
   the top-level application Makefile.

.. _src_files_directories:

Adding Source Files and Makefiles to src Directories
====================================================

Source code and associated Makefiles specify the how the
application image is built. In a Makefile, multiple files may be
referenced from a single-line entry. However, a separate line must
be used to reference each directory. During the build process, Kbuild
finds the source files to generate the object files by matching the
file names identified in the Makefile.

.. note::

   Source code without an associated Makefile is not included
   when the application is built.

Before You Begin
-----------------

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

Steps
-----

1. Create a directory structure for your source code in :file:`src`
   and add your source code files to it.

  For many useful code examples, see :ref:`common`,
  :ref:`microkernel`, and :ref:`nanokernel`.

2. Create a :file:`Makefile` for each :file:`src` directory.

   a) Use the following syntax to add file references:

      .. code-block:: make

         obj-y += file.o file.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:`rootDir/samples/philosophers/microkernel/src`.

.. code-block:: make

   obj-y = phil_fiber.o phil_task.o


.. _`enhancing_kernel`:

Enhancing the Zephyr Kernel
===========================

When enhancing the Zephyr kernel, follow the subsystem naming
conventions and the :literal:`include path` usage guidelines.

Subsystem Naming Conventions
----------------------------

In general, any sub-system 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 sub-system
should continue to follow prefix conventions identified above; this
keeps consistent interface for all users.

Include Paths Usage Guidelines
------------------------------

The current build system uses a series of defs.objs to define
common pieces for a specific subsystem. For example, there
are common defines for all architectures under :file:`\$ROOT/arch/x86`,
and more specific defines for each supported board within
the architecture, such as, :file:`\$ROOT/arch/x86/generic_pc`.

Do not add every possible :literal:`include paths` in the defs.obj files.
Too many default paths will cause problems when more than one file with
the same name exists. The only :literal:`include path` into
:file:`\${vBASE}/include` should be :file:`\${vBASE}/include` itself.

Files should define includes to specific files with the complete path
:file:`#include subdirectory/header.h`. For example, when there
are two files, :file:`include/pci.h` and :file:`include/drvers/pci.h`,
and both have been set to :file:`-Iinclude/drivers` and
:file:`-Iinclude` for the compile, any code using
:file:`#include pci.h` becomes ambiguous; using the complete path
:file:`#include drivers/pci.h` is not. Not having :file:`-Iinclude/drivers`
forces users to use the second form, which is more explicit.