.. _getting_started:

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

Use this guide to get started with your Zephyr development.

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

The Zephyr project supports these operating systems:

* Linux
* Mac OS
* 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 at the Linux Foundation with a Gerrit backend that supports
anonymous cloning via git.

To clone the repository anonymously, enter:

.. code-block:: console

   $ git clone https://gerrit.zephyrproject.org/r/zephyr zephyr-project

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

Once you're ready to start contributing, follow the steps to make yourself
a Linux Foundation account at :ref:`gerrit_accounts`.

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 Mac OS 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=/opt/zephyr-sdk

#. Navigate to the main project directory:

   .. code-block:: console

      $ cd zephyr-project

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

   .. code-block:: console

      $ source zephyr-env.sh

#. Build the example project, enter:

   .. code-block:: console

      $ cd $ZEPHYR_BASE/samples/hello_world/microkernel

      $ 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 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 <board>`. Alternatively, run the following command to obtain a list
of the supported boards:

.. code-block:: console

   $ make help

The sample projects for the microkernel and the nanokernel are available
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.

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 platforms used.

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


.. _Linux Foundation ID website: https://identity.linuxfoundation.org

.. _Gerrit: https://gerrit.zephyrproject.org/