153 lines
5.2 KiB
ReStructuredText
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.
|