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