doc/getting_started/getting_started.rst

.. _getting_started:

Getting Started Guide
#####################

Use this guide to get started with your :ref:`Zephyr <introducing_zephyr>`
development.

Set Up the Development Environment
**********************************

The Zephyr project supports these operating systems:

* Linux
* macOS
* Windows 8.1

Use the following procedures to create a new development environment.

.. toctree::
   :maxdepth: 1

   installation_linux.rst
   installation_mac.rst
   installation_win.rst


Checking Out the Source Code Anonymously
========================================

The code is hosted in a GitHub repo that supports
anonymous cloning via git.

To clone the repository anonymously, enter:

.. code-block:: console

   $ git clone https://github.com/zephyrproject-rtos/zephyr.git

You have successfully checked out a copy of the source code to your local
machine.

Building and Running an Application
***********************************

Using the 'Hello World' sample application as a base model, the following
section will describe the pieces necessary for creating a Zephyr 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 macOS please use the appropriate
commands for your OS.

Building a Sample Application
=============================

To build an example application follow these steps:


#. Make sure your environment is setup by exporting the following environment
   variables. When using the Zephyr SDK on Linux for example, type:

   .. code-block:: console

      $ export ZEPHYR_GCC_VARIANT=zephyr
      $ export ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>

#. Navigate to the main project directory:

   .. code-block:: console

      $ cd zephyr-project

#. Source the project environment file to set the project environment
   variables:

   .. code-block:: console

      $ source zephyr-env.sh

#. Build the :ref:`hello_world` example project, enter:

   .. code-block:: console

      $ cd $ZEPHYR_BASE/samples/hello_world
      $ make

The above invocation of make will build the :ref:`hello_world` sample application
using the default settings defined in the application's Makefile. You can
build for a different board by defining the variable BOARD with one of the
supported boards, for example:

.. code-block:: console

   $ make BOARD=arduino_101

For further information on the supported boards go see
:ref:`here <boards>`. Alternatively, run the following command to obtain a list
of the supported boards:

.. code-block:: console

   $ make help

Sample projects for different features of the project are available at
at :file:`$ZEPHYR_BASE/samples`.
After building an application successfully, the results can be found in the
:file:`outdir` sub-directory under the application root directory, in a
subdirectory that matches the BOARD string.

The ELF binaries generated by the build system are named by default
:file:`zephyr.elf`. This value can be overridden in the application
configuration The build system generates different names for different use cases
depending on the hardware and boards used.

.. _third_party_x_compilers:

Using Custom and 3rd Party Cross Compilers
==========================================

The Zephyr SDK is provided for convenience and ease of use. It provides
cross-compilers for all ports supported by the Zephyr OS and does not require
any extra flags when building applications or running tests.

If you have a custom cross-compiler or if you wish to use a vendor provided SDK,
follow the steps below to build with any custom or 3rd party cross-compilers:

#. To avoid any conflicts with the Zephyr SDK, enter the following commands.

   .. code-block:: console

      $ unset ZEPHYR_GCC_VARIANT
      $ unset ZEPHYR_SDK_INSTALL_DIR

#. We will use the `GCC ARM Embedded`_ compiler for this example, download the
   package suitable for your operating system from the `GCC ARM Embedded`_ website
   and extract it on your file system. This example assumes the compiler was
   extracted to: :file:`~/gcc-arm-none-eabi-5_3-2016q1/`.

#. Navigate to the main project directory:

   .. code-block:: console

      $ cd zephyr-project

#. Source the project environment file to set the project environment
   variables:

   .. code-block:: console

      $ source zephyr-env.sh

#. Build the example :ref:`hello_world` project and make sure you supply the
   CROSS_COMPILE on the command line, enter:

   .. code-block:: console

      $ export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
      $ export ZEPHYR_GCC_VARIANT=gccarmemb
      $ cd $ZEPHYR_BASE/samples/hello_world
      $ make CROSS_COMPILE=~/gcc-arm-none-eabi-5_3-2016q1/bin/arm-none-eabi- BOARD=arduino_due

The above will build the sample using the toolchain downloaded from
`GCC ARM Embedded`_.

Alternatively, you can use the existing support for GCC ARM Embedded:

   .. code-block:: console

      $ export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
      $ export ZEPHYR_GCC_VARIANT=gccarmemb
      $ cd zephyr-project
      $ source zephyr-env.sh
      $ cd $ZEPHYR_BASE/samples/hello_world
      $ make BOARD=arduino_due

Running a Sample Application in QEMU
====================================

To perform rapid testing of an application in the development environment you
can use the QEMU emulation board configuration available for both X86 and ARM
Cortex-M3 architectures. 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 x86 emulation board configuration (qemu_x86),
type:

.. code-block:: console

   $ make BOARD=qemu_x86 run

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

.. code-block:: console

   $ make BOARD=qemu_cortex_m3 run

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


.. _GCC ARM Embedded: https://launchpad.net/gcc-arm-embedded