328 lines
11 KiB
ReStructuredText
328 lines
11 KiB
ReStructuredText
.. _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 a ``zephyr`` folder in your home directory.
|
|
|
|
.. _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
|
|
***********************************
|
|
|
|
Next, build a sample Zephyr application. You can then run it either in
|
|
emulation or using POSIX APIs available on your host.
|
|
|
|
If your board is supported by Zephyr (see :ref:`boards` for a list),
|
|
consult its documentation for flashing and running instructions.
|
|
|
|
Building a Sample Application
|
|
=============================
|
|
|
|
Follow these steps to build the :ref:`hello_world` sample application
|
|
provided with Zephyr.
|
|
|
|
#. Navigate to the main project directory:
|
|
|
|
.. code-block:: console
|
|
|
|
cd zephyr
|
|
|
|
#. Set up your build environment:
|
|
|
|
.. 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.
|
|
|
|
It is, however, possible to build without the SDK. If you are using 3rd party
|
|
cross compilers, jump forward to `Using 3rd Party Cross Compilers`_ for
|
|
details. A "3rd party cross compiler" is a toolchain that the Zephyr build
|
|
system already knows about, such as `GNU ARM Embedded`_ that we use in this
|
|
document.
|
|
|
|
If you are going to use custom compilers, check `Using Custom Cross Compilers`_
|
|
for more detail. A "custom compiler" would be the one your Linux distribution
|
|
packaged, the one you compiled on your own, or the one you downloaded from the
|
|
net. The Zephyr build system doesn't know about them and doesn't officially
|
|
support them.
|
|
|
|
As already noted above, the SDK also includes prebuilt host tools. To use the
|
|
SDK's prebuilt host tools alongside a 3rd party or custom 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
|
|
|
|
Follow the steps below to build without the Zephyr SDK:
|
|
|
|
.. code-block:: console
|
|
|
|
# On Linux/macOS
|
|
unset ZEPHYR_SDK_INSTALL_DIR
|
|
cd <zephyr git clone location>
|
|
source zephyr-env.sh
|
|
# On Windows
|
|
set ZEPHYR_SDK_INSTALL_DIR=
|
|
cd <zephyr git clone location>
|
|
zephyr-env.cmd
|
|
|
|
.. _third_party_x_compilers:
|
|
|
|
Using 3rd Party Cross Compilers
|
|
===============================
|
|
|
|
To use a 3rd party cross compiler that is not provided by the Zephyr
|
|
SDK, follow the steps below.
|
|
|
|
#. We will use the `GNU ARM Embedded`_ compiler for this example, download the
|
|
package suitable for your operating system from the `GNU 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-7-2018-q2-update/`.
|
|
|
|
#. Build the example :ref:`hello_world` project, enter:
|
|
|
|
.. code-block:: console
|
|
|
|
# On Linux/macOS
|
|
export GNUARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-7-2018-q2-update/"
|
|
export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
|
|
# On Windows
|
|
set GNUARMEMB_TOOLCHAIN_PATH="%userprofile%\gcc-arm-none-eabi-7-2018-q2-update\"
|
|
set ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/hello_world
|
|
:board: arduino_due
|
|
:goals: build
|
|
|
|
Make sure to unset the ZEPHYR_SDK_INSTALL_DIR if you don't use the
|
|
SDK's host tools. See `Building without the Zephyr SDK`_ for details.
|
|
|
|
It is possible to use the Zephyr SDK's host tools along with a 3rd
|
|
party cross compiler. To do that, keep the ZEPHYR_SDK_INSTALL_DIR
|
|
environment variable set to the Zephyr SDK installation directory.
|
|
See `Set Up the Development Environment`_ for more details on the
|
|
ZEPHYR_SDK_INSTALL_DIR environment variable.
|
|
|
|
Using Custom Cross Compilers
|
|
============================
|
|
|
|
To use a custom cross compiler, follow the steps below.
|
|
|
|
#. Install a cross compiler suitable for your system. We will use the
|
|
gcc-arm-none-eabi compiler on Debian system for this example.
|
|
|
|
.. code-block:: console
|
|
|
|
# On Debian or Ubuntu
|
|
sudo apt-get install gcc-arm-none-eabi
|
|
# On Fedora or Red hat
|
|
sudo dnf install arm-none-eabi-newlib
|
|
|
|
#. Build the example :ref:`hello_world` project, enter:
|
|
|
|
.. code-block:: console
|
|
|
|
# On Linux
|
|
unset GNUARMEMB_TOOLCHAIN_PATH
|
|
export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
|
|
export CROSS_COMPILE=/usr/bin/arm-none-eabi-
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/hello_world
|
|
:board: arduino_zero
|
|
:goals: build
|
|
|
|
Note that the Zephyr build system assumes that all the tools within your
|
|
toolchain used to compile and link your code, reside in the same directory and
|
|
have a common prefix. Set the ``CROSS_COMPILE`` environment variable to the
|
|
path of your toolchain's location and that common prefix. In the example above,
|
|
gcc-arm-none-eabi is installed in ``/usr/bin/`` with the common prefix of
|
|
``arm-none-eabi-``. If your toolchain is at ``/opt/mytoolchain/bin`` with the
|
|
prefix of ``myarch-none-elf-``, it would be
|
|
``CROSS_COMPILE=/opt/mytoolchain/bin/arch-none-elf-``.
|
|
|
|
Make sure to unset the ZEPHYR_SDK_INSTALL_DIR if you don't use the SDK's host
|
|
tools. See `Building without the Zephyr SDK`_ and `Set Up the Development
|
|
Environment`_ for more details.
|
|
|
|
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. See the :ref:`native_posix` section on host dependencies
|
|
for more information.
|
|
|
|
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
|
|
|
|
You can run ``zephyr/zephyr.exe --help`` to get a list of available
|
|
options. See the :ref:`native_posix` document for more information.
|
|
|
|
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.
|
|
|
|
.. _GNU ARM Embedded: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm
|
|
.. _CMake: https://cmake.org
|