| .. _apps_build: |
| |
| Build an Application |
| #################### |
| |
| The Zephyr build system compiles and links all components of an application |
| into a single application image that can be run on simulated hardware or real |
| hardware. |
| |
| .. contents:: Procedures |
| :local: |
| :depth: 1 |
| |
| Building an Application |
| ======================= |
| |
| The build system allows you to easily build an application using the |
| application's existing configuration. However, you can also build it |
| using different configuration settings, if desired. |
| |
| Before you begin |
| ---------------- |
| |
| * Ensure you have added all application-specific code to the application |
| directory, as described in :ref:`apps_code_dev`. Ensure each source code |
| directory and sub-directory has its own :file:`Makefile`. |
| |
| * Ensure you have configured the application's kernel, as described |
| in :ref:`apps_kernel_conf`. |
| |
| * Ensure the Zephyr environment variables are set for each console terminal; |
| see :ref:`apps_common_procedures`. |
| |
| Steps |
| ----- |
| |
| #. Navigate to the application directory :file:`~/appDir`. |
| |
| #. Enter the following command to build the application's :file:`zephyr.elf` |
| image using the configuration settings for the board type specified |
| in the application's :file:`Makefile`. |
| |
| .. code-block:: console |
| |
| $ make |
| |
| If desired, you can build the application using the configuration settings |
| specified in an alternate :file:`.conf` file using the :code:`CONF_FILE` |
| parameter. These settings will override the settings in the application's |
| :file:`.config` file or its default :file:`.conf` file. For example: |
| |
| .. code-block:: console |
| |
| $ make CONF_FILE=prj.alternate.conf |
| |
| If desired, you can build the application for a different board type |
| than the one specified in the application's :file:`Makefile` |
| using the :code:`BOARD` parameter. For example: |
| |
| .. code-block:: console |
| |
| $ make BOARD=arduino_101 |
| |
| Both the :code:`CONF_FILE` and :code:`BOARD` parameters can be specified |
| when building the application. |
| |
| Rebuilding an Application |
| ========================= |
| |
| Application development is usually fastest when changes are continually tested. |
| Frequently rebuilding your application makes debugging less painful |
| as the application becomes more complex. It's usually a good idea to |
| rebuild and test after any major changes to the application's source files, |
| Makefiles, or configuration settings. |
| |
| .. important:: |
| |
| The Zephyr build system rebuilds only the parts of the application image |
| potentially affected by the changes. Consequently, rebuilding an application |
| is often significantly faster than building it the first time. |
| |
| Steps |
| ----- |
| |
| #. Follow the steps specified in `Building an Application`_ above. |
| |
| Recovering from a Build Failure |
| =============================== |
| |
| Sometimes the build system doesn't rebuild the application correctly |
| because it fails to recompile one or more necessary files. You can force |
| the build system to rebuild the entire application from scratch with the |
| following procedure: |
| |
| Steps |
| ----- |
| |
| #. Navigate to the application directory :file:`~/appDir`. |
| |
| #. Enter the following command to delete the application's generated files |
| for the specified board type, except for the :file:`.config` file that |
| contains the application's current configuration information. |
| |
| .. code-block:: console |
| |
| $ make [BOARD=<type>] clean |
| |
| Alternatively, enter the following command to delete *all* generated files |
| for *all* board types, including the :file:`.config` files that contain |
| the application's current configuration information for those board types. |
| |
| .. code-block:: console |
| |
| $ make pristine |
| |
| #. Rebuild the application normally following the steps specified |
| in `Building an Application`_ above. |