.. _getting_started:

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

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

Checking Out the Source Code Anonymously
****************************************

The Zephyr source code is hosted in a GitHub repo that supports
anonymous cloning via git. There are scripts and such in this repo that
you'll need to set up your development environment, and we'll be using
Git to get this repo.  (If you don't have Git installed, see the
beginning of the OS-specific instructions below for help.)

We'll begin by
using Git to clone the repository anonymously. Enter:

.. code-block:: console

   # On Linux/macOS
   cd ~
   # On Windows
   cd %userprofile%

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

You have successfully checked out a copy of the source code to your local
machine in the ~/zephyr folder.

.. _getting_started_cmake:

A brief note on the Zephyr build system
***************************************

The Zephyr project uses `CMake`_ as a tool for managing the building of the
project. CMake is able to generate build files in different formats (also
known as "generators"), and the following ones are currently supported
by Zephyr:

 * ``make``: Supported on UNIX-like platforms (Linux, macOS).
 * ``ninja``: Supported on all platforms.

Most of the examples in the Zephyr documentation use `ninja` as a build tool
but you should be able to use any generator on any of the examples listed.

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

The Zephyr project supports these operating systems:

* Linux
* macOS
* Microsoft Windows

Use the following procedures to create a new development environment.

.. toctree::
   :maxdepth: 1

   installation_linux.rst
   installation_mac.rst
   installation_win.rst


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


      # On Linux/macOS
      export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
      export ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>
      # On Windows
      set ZEPHYR_TOOLCHAIN_VARIANT=zephyr
      set ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>

   .. note:: In previous releases of Zephyr, the ``ZEPHYR_TOOLCHAIN_VARIANT``
             variable was called ``ZEPHYR_GCC_VARIANT``.

#. Navigate to the main project directory:

   .. code-block:: console

      cd zephyr

#. Set the project environment variables:

   .. code-block:: console

      # On Linux/macOS
      source zephyr-env.sh
      # On Windows
      zephyr-env.cmd

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

   On Linux/macOS you can also build with ``make`` instead of ``ninja``:

   .. zephyr-app-commands::
      :zephyr-app: samples/hello_world
      :generator: make
      :host-os: unix
      :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

   ninja 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

      # On Linux/macOS
      unset ZEPHYR_TOOLCHAIN_VARIANT
      unset ZEPHYR_SDK_INSTALL_DIR
      cd <zephyr git clone location>
      source zephyr-env.sh
      # On Windows
      set ZEPHYR_TOOLCHAIN_VARIANT=
      set ZEPHYR_SDK_INSTALL_DIR=
      cd <zephyr git clone location>
      zephyr-env.cmd


#. On UNIX platforms, 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 `Using Custom and 3rd Party Cross Compilers`_ for
details.

.. _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 `Building
without the Zephyr SDK`_ 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:`<user folder>/gcc-arm-none-eabi-5_3-2016q1/`.

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

   .. code-block:: console

      # On Linux/macOS
      export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
      export ZEPHYR_TOOLCHAIN_VARIANT=gccarmemb
      # On Windows
      set GCCARMEMB_TOOLCHAIN_PATH="%userprofile%\gcc-arm-none-eabi-5_3-2016q1\"
      set ZEPHYR_TOOLCHAIN_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:

.. zephyr-app-commands::
   :zephyr-app: samples/hello_world
   :host-os: unix
   :board: qemu_x86
   :goals: build 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.

Running a Sample Application natively (POSIX OS)
================================================

It is also possible to compile some of the sample and test applications to run
as native process on a POSIX OS (e.g. Linux).
To be able to do this, remember to have installed the 32 bit libC if your OS is
natively 64bit.

To compile and run an application in this way, type:

.. zephyr-app-commands::
   :zephyr-app: samples/hello_world
   :host-os: unix
   :board: native_posix
   :goals: build

and then:

.. code-block:: console

   ninja run
   # or just:
   zephyr/zephyr.exe
   # Press Ctrl+C to exit

This executable can be instrumented like any other Linux process. For ex. with gdb
or valgrind.
Note that the native port is currently only tested in Linux.

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