doc/getting_started/building_zephyr.rst

.. _building_zephyr:

Building and Running an Application
###################################

Congratulations! You have successfully set up your development environment
and created a Zephyr application. This section provides all the steps to
build a Zephyr kernel containing your application and run it. We use the
`Hello World` sample application as an example. However, the steps needed are
the same for your own application.

The processes to build and run a Zephyr application are the same across
operating systems. Nevertheless, the commands needed do differ from one OS to
the next. The following sections contain the commands used in a Linux
development environment. If you are using Mac OS please use the appropriate
commands for your OS.

Building a Sample Application
*****************************

To build an example application follow these steps:

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

#. Set the environment variables on each console, see
   :ref:`environment_variables`

#. Build the example project, enter:

    .. 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's Makefile. You can
build for a different platform by defining the variable BOARD with one of the
supported platforms, for example:

.. code-block:: console

   $ make BOARD=minnowboard

For further information on the supported platforms go see
:ref:`here <board>`. Alternatively, run the following command on the code
root to obtain a list of the supported platforms of a particular
architecture:

.. code-block:: console

   $ make 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 ELF binaries generated by the build system are named by default
:file:`zephyr.elf`. This value can be overridden in the Makefile. The build
system generates different names for different use cases 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.

1. Run an application using the default board configuration, type:

   .. code-block:: console

      $ make qemu

To run an application using the x86 emulation board configuration (qemu_x86), type:

.. code-block:: console

   $ make BOARD=qemu_x86 qemu

To run an application using the ARM qemu_cortex_m3 board configuration, type:

.. code-block:: console

   $ make BOARD=qemu_cortex_m3 ARCH=arm qemu

QEMU is not supported on all boards and platforms. 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.