206 lines
6.1 KiB
ReStructuredText
206 lines
6.1 KiB
ReStructuredText
.. _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 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 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 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
|