.. _building_zephyr:

Building and Running a Sample Application
#########################################


Building a Sample Application from Source
=========================================

To build an example application follow these steps:

#. Go to the root directory of the Zephyr Project.

#. Set the paths properly in the :file:`$ZEPHYR_BASE` directory,
   type:

    .. code-block:: console

       $ source zephyr-env.sh

#. Build the example project, type:

    .. code-block:: console

       $ cd $ZEPHYR_BASE/samples/microkernel/apps/hello_world

       $ make

The above invocation of make will build the hello_world sample application using
the default settings defined in the application Makefile, for example:

.. code-block:: console

   $ make PLATFORM_CONFIG=basic_atom

You can build for a different platform by defining the variable PLATFORM_CONFIG
with one of the supported platforms.
For a list of supported platforms of a particular architecture, run:

.. code-block:: console

   $ make ARCH=<arch> help

The sample projects for the microkernel and the nanokernel are found
at :file:`$ZEPHYR_BASE/samples/microkernel/apps` and
:file:`$ZEPHYR_BASE/samples/nanokernel/apps` respectively.
After building an application successfully, the results can be found in the
:file:`outdir` sub-directory under the application root directory.

The default ELF binaries generated by the build system are named zephyr.elf. The
build system generates different format for different use cases and depending on
the hardware and platforms used.

Running a Sample Application
============================

To perform rapid testing of an application in the development environment you can
use QEMU with some of the supported platforms and architecture. This can be easily
accomplished by calling a special target when building an application that
invokes Qemu once the build process is completed.

To run an application using the default platform configuration, type:

.. code-block:: console

   $ make qemu

To run an application using the x86 basic_atom platform configuration, type:

.. code-block:: console

   $ make PLATFORM_CONFIG=basic_atom qemu

To run an application using the ARM basic_cortex_m3 platform configuration, type:

.. code-block:: console

   $ make PLATFORM_CONFIG=basic_cortex_m3 ARCH=arm qemu

Qemu is not supported on all platforms and architectures and some samples and
test cases might fail when running in the emulator. When developing for a
specific hardware target you should always test on the actual hardware and should
not rely on testing in the QEMU emulation environment only.