.. _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.

.. _getting_started_run_sample:

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

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

   .. code-block:: console

      $ source zephyr-env.sh

#. Build the :ref:`hello_world` example for the `arduino_101` board, enter:

   .. zephyr-app-commands::
      :zephyr-app: samples/hello_world
      :board: arduino_101
      :build-dir: arduino_101
      :goals: build

You can build for a different board by defining the variable BOARD
with another of the supported boards, for example:

   .. zephyr-app-commands::
      :zephyr-app: samples/hello_world
      :board: arduino_due
      :build-dir: arduino_due
      :goals: build

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 usage

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
directory where cmake was invoked.

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.


.. _sdkless_builds:

Building without the Zephyr SDK
===============================

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.

In addition to cross-compilers, the Zephyr SDK also provides prebuilt
host tools. To use the SDK host tools alongside a custom or 3rd party
cross-compiler, keep the ZEPHYR_SDK_INSTALL_DIR environment variable
set to the Zephyr SDK installation directory.

To build without the Zephyr SDK's prebuilt host tools, the
ZEPHYR_SDK_INSTALL_DIR environment variable must be unset, the host
tools must be built and added to path, and a 3rd party cross-compiler
must be installed.

#. Follow the steps below to build without the Zephyr SDK:

   .. code-block:: console

      $ unset ZEPHYR_GCC_VARIANT
      $ unset ZEPHYR_SDK_INSTALL_DIR
      $ cd <zephyr git clone location>
      $ source zephyr-env.sh

#. Build Kconfig in :file:`$ZEPHYR_BASE/build` and add it to path

   .. code-block:: console

      $ cd $ZEPHYR_BASE
      $ mkdir build && cd build
      $ cmake $ZEPHYR_BASE/scripts
      $ make
      $ echo "export PATH=$PWD/kconfig:\$PATH" >> $HOME/.zephyrrc
      $ source $ZEPHYR_BASE/zephyr-env.sh

   .. note::

      You only need to do this once after cloning the git repository.

Now that the host tools are installed, a 3rd party cross compiler must
be installed. See :ref:`below <third_party_x_compilers>` for
installing a cross compiler.

.. _third_party_x_compilers:

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

To use a 3rd party cross compiler that is not provided by the Zephyr
SDK, follow the steps below. It is possible to use a 3rd party cross
compiler and still use the Zephyr SDK's host tools. See :ref:`the
section above <sdkless_builds>` for details.

#. 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/`.

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

   .. code-block:: console

      $ export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
      $ export ZEPHYR_GCC_VARIANT=gccarmemb

   .. zephyr-app-commands::
      :zephyr-app: samples/hello_world
      :board: arduino_due
      :goals: build

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

   $ cd $ZEPHYR_BASE/samples/hello_world
   $ mkdir qemu_build && cd qemu_build
   $ cmake -DBOARD=qemu_x86 ..
   $ make run

To exit the qemu emulator, press ``Ctrl-a``, followed by ``x``.

Use the ``qemu_cortex_m3`` board configuration to test the ARM build.

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