doc: application: fix up "running an application"

Run an Application

******************

An application image can be run on real or emulated hardware.

An application image can be run on a real board or emulated hardware.

Running on a Board

==================

Most boards supported by Zephyr let you flash a compiled binary using

the Make ``flash`` target to copy the binary to the board and run it.

the CMake ``flash`` target to copy the binary to the board and run it.

Follow these instructions to flash and run an application on real

hardware:

#. Open a terminal console on your host computer, and navigate to the

   application directory, :file:`~/app`.

#. Build your application, as described in :ref:`build_an_application`.

#. Make sure your board is attached to your host computer. Usually, you'll do

   this via USB.

#. Enter the following command to build and run the application on

   your board, which you will usually attach via USB.

#. Run this console command from the build directory, :file:`~/app/build`, to

   flash the compiled Zephyr binary and run it on your board:

   .. code-block:: console

       $ make [BOARD=<type> ...] flash

      $ ninja flash

The Zephyr build system integrates with the board support files to

use hardware-specific tools to flash the Zephyr binary to your

hardware, then run it.

   In cases where board support is incomplete, ``make flash`` may not

   be supported. If you receive an error message about flash support

   being unavailable when running this command, consult :ref:`your

   board's documentation <boards>` for additional information on how

   to flash your board.

Each time you run the flash command, your application is rebuilt and flashed

again.

In cases where board support is incomplete, flashing via the Zephyr build

system may not be supported. If you receive an error message about flash

support being unavailable, consult :ref:`your board's documentation <boards>`

for additional information on how to flash your board.

.. note:: When developing on Linux, it's common to need to install

          board-specific udev rules to enable USB device access to

          your board as a non-root user. If ``make flash`` fails,

          your board as a non-root user. If flashing fails,

          consult your board's documentation to see if this is

          necessary.

Running in an Emulator

======================

The kernel has built-in emulator support for QEMU. It allows you to

run and test an application virtually, before (or in lieu of) loading

and running it on actual target hardware. Follow these instructions to

run an application via QEMU:

#. Open a terminal console on your host computer, and navigate to the

   application directory :file:`~/app`.

#. Build your application for one of the QEMU boards, as described in

   :ref:`build_an_application`.

   For example, you could set ``BOARD`` to:

#. After generating project files for a QEMU-supported board

   configuration, such as qemu_cortex_m3 or qemu_x86, enter the

   following command to build and run the application.

   - ``qemu_x86`` to emulate running on an x86-based board

   - ``qemu_cortex_m3`` to emulate running on an ARM Cortex M3-based board

#. Run this console command from the build directory, :file:`~/app/build`, to

   flash the compiled Zephyr binary and run it in QEMU:

   .. code-block:: console

      $ ninja run

   The Zephyr build system generates a :file:`zephyr.elf` image file

   and then begins running it in the terminal console.

#. Press :kbd:`Ctrl A, X` to stop the application from running

   in QEMU.

   The application stops running and the terminal console prompt

   redisplays.

Each time you execute the run command, your application is rebuilt and run

again.

.. _application_debugging: