309 lines
10 KiB
ReStructuredText
309 lines
10 KiB
ReStructuredText
.. _getting_started:
|
|
|
|
Getting Started Guide
|
|
#####################
|
|
|
|
Follow this guide to set up a :ref:`Zephyr <introducing_zephyr>` development
|
|
environment on your system, and then build and run a sample application.
|
|
|
|
.. _host_setup:
|
|
|
|
Set Up a Development System
|
|
***************************
|
|
|
|
Follow one of the following guides for your host operating system.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
Linux <installation_linux.rst>
|
|
macOS <installation_mac.rst>
|
|
Windows <installation_win.rst>
|
|
|
|
Clone the Zephyr Repository
|
|
***************************
|
|
|
|
To clone the Zephyr source code repository from GitHub:
|
|
|
|
.. code-block:: console
|
|
|
|
git clone https://github.com/zephyrproject-rtos/zephyr
|
|
|
|
.. warning::
|
|
|
|
Don't clone Zephyr to a directory with spaces anywhere in the path.
|
|
For example, on Windows, :file:`C:\\Users\\YourName\\zephyr` will
|
|
work, but :file:`C:\\Users\\Your Name\\zephyr` will cause cryptic
|
|
errors when you try to build an application.
|
|
|
|
Install Python Dependencies
|
|
***************************
|
|
|
|
Next, install additional Python packages required by Zephyr in a shell or
|
|
``cmd.exe`` prompt:
|
|
|
|
.. code-block:: console
|
|
|
|
# Linux
|
|
pip3 install --user -r zephyr/scripts/requirements.txt
|
|
|
|
# macOS and Windows
|
|
pip3 install -r zephyr/scripts/requirements.txt
|
|
|
|
Some notes on pip's ``--user`` option:
|
|
|
|
- Installing with ``--user`` is the default behavior on Debian-based
|
|
distributions and is generally recommended on Linux to avoid conflicts with
|
|
Python packages installed using the system package manager.
|
|
|
|
- On Linux, verify the Python user install directory ``~/.local/bin`` is at the front of
|
|
your PATH environment variable, otherwise installed packages won't be
|
|
found.
|
|
|
|
- On macOS, Homebrew disables the ``--user`` flag\ [#homebrew_user]_.
|
|
|
|
- On Windows using ``cmd.exe``, although it's possible to use the ``--user``
|
|
flag, it makes it harder for the command prompt to find executables installed
|
|
by pip.
|
|
|
|
|
|
Set Up a Toolchain
|
|
******************
|
|
|
|
.. note::
|
|
|
|
On Linux, you can skip this step if you installed the :ref:`Zephyr SDK
|
|
<zephyr_sdk>`, which includes toolchains for all supported Zephyr
|
|
architectures.
|
|
|
|
If you want, you can use the SDK host tools (such as OpenOCD) with a
|
|
different toolchain by keeping the :envvar:`ZEPHYR_SDK_INSTALL_DIR`
|
|
environment variable set to the Zephyr SDK installation directory, while
|
|
setting :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` appropriately for a non-SDK
|
|
toolchain.
|
|
|
|
Zephyr binaries are compiled using software called a *toolchain*. You need to
|
|
*install* and *configure* a toolchain to develop Zephyr applications\
|
|
[#tools_native_posix]_.
|
|
|
|
Toolchains can be *installed* in different ways, including using installer
|
|
programs, system package managers, or simply downloading a zip file or other
|
|
archive and extracting the files somewhere on your computer. You *configure*
|
|
the toolchain by setting the environment variable
|
|
:envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to a recognized value, along with some
|
|
additional variable(s) specific to that toolchain (usually, this is just one
|
|
more variable which contains the path where you installed the toolchain on your
|
|
file system).
|
|
|
|
.. note::
|
|
|
|
In previous releases of Zephyr, the ``ZEPHYR_TOOLCHAIN_VARIANT`` variable
|
|
was called ``ZEPHYR_GCC_VARIANT``.
|
|
|
|
The following toolchain installation options are available. The right choice
|
|
for you depends on where you want to run Zephyr and any other requirements you
|
|
may have. Check your :ref:`board-level documentation <boards>` if you are
|
|
unsure about what choice to use.
|
|
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
|
|
toolchain_3rd_party_x_compilers.rst
|
|
toolchain_other_x_compilers.rst
|
|
toolchain_custom_cmake.rst
|
|
|
|
|
|
To use the same toolchain in new sessions in the future you can make
|
|
sure the variables are set persistently.
|
|
|
|
On macOS and Linux, you can set the variables by putting the ``export`` lines
|
|
setting environment variables in a file :file:`~/.zephyrrc`. On Windows, you
|
|
can put the ``set`` lines in :file:`%userprofile%\\zephyrrc.cmd`. These files
|
|
are used to modify your environment when you run ``zephyr-env.sh`` (Linux,
|
|
macOS) and ``zephyr-env.cmd`` (Windows), which you will learn about in the next
|
|
step.
|
|
|
|
.. _getting_started_run_sample:
|
|
|
|
Build and Run an Application
|
|
****************************
|
|
|
|
Next, build a sample Zephyr application. You can then flash and run it on real
|
|
hardware using any supported host system. Depending on your operating system,
|
|
you can also run it in emulation with QEMU or as a native POSIX application.
|
|
|
|
.. _getting_started_cmake:
|
|
|
|
A Brief Note on the Zephyr Build System
|
|
=======================================
|
|
|
|
The Zephyr build system uses `CMake`_. CMake creates build systems in different
|
|
formats, called `generators`_. Zephyr supports the following generators:
|
|
|
|
* ``Unix Makefiles``: Supported on UNIX-like platforms (Linux, macOS).
|
|
* ``Ninja``: Supported on all platforms.
|
|
|
|
This documentation and Zephyr's continuous integration system mainly use
|
|
``Ninja``, but you should be able to use any supported generator to build
|
|
Zephyr applications.
|
|
|
|
Build the Application
|
|
=====================
|
|
|
|
Follow these steps to build the :ref:`hello_world` sample application provided
|
|
with Zephyr.
|
|
|
|
Zephyr applications have to be configured and built to run on some hardware
|
|
configuration, which is called a "board"\ [#board_misnomer]_. These steps show
|
|
how to build the Hello World application for the :ref:`arduino_101` board. You
|
|
can build for a different board by changing ``arduino_101`` to another
|
|
supported value. See :ref:`boards` for more information, or run ``ninja usage``
|
|
from the build directory (once you've run ``cmake``) to get a list.
|
|
|
|
.. note::
|
|
|
|
If you want to re-use your existing build directory to build for another
|
|
board, you must delete that directory's contents first by running ``ninja
|
|
pristine``.
|
|
|
|
#. 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 Hello World sample for the ``arduino_101``:
|
|
|
|
.. Note: we don't use :zephyr-app: here because we just told the user to cd
|
|
to ZEPHYR_BASE, so it's not necessary for clarity and would clutter the
|
|
instructions a bit.
|
|
|
|
.. zephyr-app-commands::
|
|
:app: samples/hello_world
|
|
:board: arduino_101
|
|
:goals: build
|
|
|
|
On Linux/macOS you can also build with ``make`` instead of ``ninja``:
|
|
|
|
.. zephyr-app-commands::
|
|
:app: samples/hello_world
|
|
:generator: make
|
|
:host-os: unix
|
|
:board: arduino_101
|
|
:goals: build
|
|
|
|
The main build products are in :file:`zephyr/samples/hello_world/build/zephyr`.
|
|
The final application binary in ELF format is named :file:`zephyr.elf` by
|
|
default. Other binary formats and byproducts such as disassembly and map files
|
|
will be present depending on the target and build system configuration.
|
|
|
|
Other sample projects demonstrating Zephyr's features are located in
|
|
:file:`zephyr/samples` and are documented in :ref:`samples-and-demos`.
|
|
|
|
Run the Application by Flashing to Another Board
|
|
================================================
|
|
|
|
Most "real hardware" boards supported by Zephyr can be flashed by running
|
|
``ninja flash`` from the build directory. However, this may require
|
|
board-specific tool installation and configuration to work properly.
|
|
|
|
See :ref:`application_run` in the Application Development Primer and the
|
|
documentation provided with your board at :ref:`boards` for additional details
|
|
if you get an error.
|
|
|
|
Run the Application in QEMU
|
|
===========================
|
|
|
|
On Linux and macOS, you can run Zephyr applications in emulation on your host
|
|
system using QEMU when targeting either the X86 or ARM Cortex-M3 architectures.
|
|
|
|
To build and run Hello World 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, type :kbd:`Ctrl-a`, then :kbd:`x`.
|
|
|
|
Use the ``qemu_cortex_m3`` board configuration to run on an emulated Arm
|
|
Cortex-M3.
|
|
|
|
Running a Sample Application natively (POSIX OS)
|
|
================================================
|
|
|
|
Finally, it is also possible to compile some samples to run as native processes
|
|
on a POSIX OS. This is currently only tested on Linux hosts.
|
|
|
|
On 64 bit host operating systems, you will also need a 32 bit C library
|
|
installed. See the :ref:`native_posix` section on host dependencies for more
|
|
information.
|
|
|
|
To compile and run Hello World 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 using standard tools, such as gdb or
|
|
valgrind.
|
|
|
|
.. rubric:: Footnotes
|
|
|
|
.. [#homebrew_user]
|
|
|
|
For details, see
|
|
https://docs.brew.sh/Homebrew-and-Python#note-on-pip-install---user.
|
|
|
|
.. [#tools_native_posix]
|
|
|
|
Usually, the toolchain is a cross-compiler and related tools which are
|
|
different than the host compilers and other programs available for
|
|
developing software to run natively on your operating system.
|
|
|
|
One exception is when building Zephyr as a host binary to run on a POSIX
|
|
operating system. In this case, you still need to set up a toolchain, but it
|
|
will provide host compilers instead of cross compilers. For details on this
|
|
option, see :ref:`native_posix`.
|
|
|
|
.. [#board_misnomer]
|
|
|
|
This has become something of a misnomer over time. While the target can be,
|
|
and often is, a microprocessor running on its own dedicated hardware
|
|
board, Zephyr also supports using QEMU to run targets built for other
|
|
architectures in emulation, targets which produce native host system
|
|
binaries that implement Zephyr's driver interfaces with POSIX APIs, and even
|
|
running different Zephyr-based binaries on CPU cores of differing
|
|
architectures on the same physical chip. Each of these hardware
|
|
configurations is called a "board," even though that doesn't always make
|
|
perfect sense in context.
|
|
|
|
.. _CMake: https://cmake.org
|
|
.. _generators: https://cmake.org/cmake/help/v3.8/manual/cmake-generators.7.html
|