blob: 8fb619cf4fd43b51fdf1d0adba391fb058a9a807 [file] [log] [blame]
.. _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
* 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 `Gerrit Accounts`_.
.. _Gerrit Accounts: https://wiki.zephyrproject.org/view/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=<sdk installation directory>
#. 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
$ 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
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 project and make sure you supply the CROSS_COMPILE on the
command line, enter:
.. code-block:: console
$ 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 qemu
To run an application using the ARM qemu_cortex_m3 board configuration, type:
.. code-block:: console
$ make BOARD=qemu_cortex_m3 qemu
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.
.. _Linux Foundation ID website: https://identity.linuxfoundation.org
.. _Gerrit: https://gerrit.zephyrproject.org/
.. _GCC ARM Embedded: https://launchpad.net/gcc-arm-embedded