zephyr/doc/application/apps_code_dev.rst

153 lines
5.2 KiB
ReStructuredText

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