322 lines
10 KiB
ReStructuredText
322 lines
10 KiB
ReStructuredText
.. _getting_started:
|
|
|
|
Getting Started Guide
|
|
#####################
|
|
|
|
Follow this guide to set up a :ref:`Zephyr <introducing_zephyr>` development
|
|
environment, then build and run a sample application.
|
|
|
|
.. tip::
|
|
|
|
Need help with something? See :ref:`help`.
|
|
|
|
.. _host_setup:
|
|
|
|
Install Host Dependencies
|
|
*************************
|
|
|
|
.. _python-pip:
|
|
|
|
Python and pip
|
|
==============
|
|
|
|
Python 3 and its package manager, pip\ [#pip]_, are used extensively by Zephyr
|
|
to install and run scripts that are required to compile and run Zephyr
|
|
applications.
|
|
|
|
Depending on your operating system, you may or may not need to provide the
|
|
``--user`` flag to the ``pip3`` command when installing new packages. This is
|
|
documented throughout the instructions.
|
|
See `Installing Packages`_ in the Python Packaging User Guide for more
|
|
information about pip\ [#pip]_, including this `information on -\\-user`_.
|
|
|
|
- On Linux, make sure ``~/.local/bin`` is on your :envvar:`PATH`
|
|
:ref:`environment variable <env_vars>`, or programs installed with ``--user``
|
|
won't be found\ [#linux_user]_.
|
|
|
|
- On macOS, `Homebrew disables -\\-user`_.
|
|
|
|
- On Windows, see the Installing Packages information on ``--user`` if you
|
|
require using this option.
|
|
|
|
On all operating systems, the ``-U`` flag installs or updates the package if the
|
|
package is already installed locally but a more recent version is available. It
|
|
is good practice to use this flag if the latest version of a package is
|
|
required.
|
|
|
|
.. _install-required-tools:
|
|
|
|
Install the required tools
|
|
===========================
|
|
|
|
Follow an operating system specific guide, then come back to this page.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
Linux <installation_linux.rst>
|
|
macOS <installation_mac.rst>
|
|
Windows <installation_win.rst>
|
|
|
|
.. _get_the_code:
|
|
|
|
Get the source code
|
|
*******************
|
|
|
|
Zephyr's multi-purpose :ref:`west <west>` tool lets you easily get the Zephyr
|
|
project repositories. (While it's easiest to develop with Zephyr using west,
|
|
we also have :ref:`documentation for doing without it <no-west>`.)
|
|
|
|
Install west
|
|
============
|
|
|
|
First, install ``west`` using ``pip3``:
|
|
|
|
.. code-block:: console
|
|
|
|
# Linux
|
|
pip3 install --user -U west
|
|
|
|
# macOS (Terminal) and Windows (cmd.exe)
|
|
pip3 install -U west
|
|
|
|
See :ref:`west-install` for additional details on installing west.
|
|
|
|
.. _clone-zephyr:
|
|
|
|
Clone the Zephyr Repositories
|
|
=============================
|
|
|
|
Clone all of Zephyr's repositories in a new :file:`zephyrproject` directory:
|
|
|
|
.. code-block:: console
|
|
|
|
west init zephyrproject
|
|
cd zephyrproject
|
|
west update
|
|
|
|
You can replace :file:`zephyrproject` with another directory name. West creates
|
|
the directory if it doesn't exist. See :ref:`west-multi-repo` for more details.
|
|
|
|
.. important::
|
|
|
|
You need to run ``west update`` any time :file:`zephyr/west.yml` changes.
|
|
This command keeps :ref:`modules` in the :file:`zephyrproject` folder in sync
|
|
with the code in the zephyr repository, so they work correctly together.
|
|
|
|
Some examples when ``west update`` is needed are: whenever you
|
|
pull the :file:`zephyr` repository, switch branches in it, or perform a ``git
|
|
bisect`` inside of it.
|
|
|
|
.. warning::
|
|
|
|
Don't clone into a directory with spaces anywhere in the path.
|
|
For example, on Windows, :file:`C:\\Users\\YourName\\zephyrproject` will
|
|
work, but :file:`C:\\Users\\Your Name\\zephyrproject` will cause cryptic
|
|
errors when you try to build an application.
|
|
|
|
.. _gs_python_deps:
|
|
|
|
Install Python Dependencies
|
|
***************************
|
|
|
|
Install Python packages required by Zephyr. From the :file:`zephyrproject`
|
|
folder that you :ref:`cloned Zephyr into <clone-zephyr>`:
|
|
|
|
.. code-block:: console
|
|
|
|
# Linux
|
|
pip3 install --user -r zephyr/scripts/requirements.txt
|
|
|
|
# macOS and Windows
|
|
pip3 install -r zephyr/scripts/requirements.txt
|
|
|
|
.. _gs_toolchain:
|
|
|
|
Set Up a Toolchain
|
|
******************
|
|
|
|
Zephyr binaries are compiled and linked by a *toolchain*\
|
|
[#tools_native_posix]_. You now need to *install* and *configure* a toolchain.
|
|
Toolchains are *installed* in the usual ways you get programs: with installer
|
|
programs or system package managers, by downloading and extracting a zip
|
|
archive, etc.
|
|
|
|
You *configure* the toolchain to use by setting :ref:`environment variables
|
|
<env_vars>`. You need to set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to a supported
|
|
value, along with additional variable(s) specific to the toolchain variant.
|
|
|
|
The following choices are available. If you're not sure what to use, check your
|
|
:ref:`board-level documentation <boards>`. If you're targeting an Arm Cortex-M,
|
|
:ref:`toolchain_gnuarmemb` is a safe bet. On Linux, you can skip this step if
|
|
you set up the :ref:`Zephyr SDK <zephyr_sdk>` toolchains or if you want to
|
|
:ref:`gs_posix`.
|
|
|
|
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
|
|
toolchain_3rd_party_x_compilers.rst
|
|
toolchain_other_x_compilers.rst
|
|
toolchain_host.rst
|
|
toolchain_custom_cmake.rst
|
|
|
|
.. _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.
|
|
Additional information about building applications can be found in the
|
|
:ref:`build_an_application` section.
|
|
|
|
Build Hello World
|
|
=================
|
|
|
|
Let's build the :ref:`hello_world` sample application.
|
|
|
|
Zephyr applications are built to run on specific hardware, which is
|
|
called a "board"\ [#board_misnomer]_. We'll use the :ref:`reel_board
|
|
<reel_board>` here, but you can change ``reel_board`` to another value if you
|
|
have a different board. See :ref:`boards` or run ``west boards`` from anywhere
|
|
inside the ``zephyrproject`` directory for a list of supported boards.
|
|
|
|
#. Go to the zephyr repository:
|
|
|
|
.. code-block:: console
|
|
|
|
cd zephyrproject/zephyr
|
|
|
|
#. Set up your build environment:
|
|
|
|
.. code-block:: console
|
|
|
|
# Linux and macOS
|
|
source zephyr-env.sh
|
|
|
|
# Windows
|
|
zephyr-env.cmd
|
|
|
|
#. Build the Hello World sample for the ``reel_board``:
|
|
|
|
.. zephyr-app-commands::
|
|
:app: samples/hello_world
|
|
:board: reel_board
|
|
:goals: build
|
|
|
|
The main build products will be in :file:`build/zephyr`;
|
|
:file:`build/zephyr/zephyr.elf` is the Hello World application binary in ELF
|
|
format. Other binary formats, disassembly, and map files may be present
|
|
depending on your board.
|
|
|
|
The other sample applications in :zephyr_file:`samples` are documented in
|
|
:ref:`samples-and-demos`. If you want to re-use an existing build directory for
|
|
another board or application, you need to pass ``-p=auto`` to ``west build``.
|
|
|
|
Run the Application by Flashing to a Board
|
|
==========================================
|
|
|
|
Most "real hardware" boards supported by Zephyr can be flashed by running
|
|
``west flash``. However, this may require board-specific tool installation and
|
|
configuration to work properly.
|
|
|
|
See :ref:`application_run` in the Application Development Primer and your
|
|
board's documentation in :ref:`boards` for additional details.
|
|
|
|
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 ``qemu_cortex_m3`` to target an emulated Arm Cortex-M3 instead.
|
|
|
|
.. _gs_posix:
|
|
|
|
Run a Sample Application natively (POSIX OS)
|
|
============================================
|
|
|
|
Finally, it is also possible to compile some samples to run as host processes
|
|
on a POSIX OS. This is currently only tested on Linux hosts. See
|
|
:ref:`native_posix` for more information. On 64 bit host operating systems, you
|
|
need to install a 32 bit C library; see :ref:`native_posix_deps` for details.
|
|
|
|
First, build Hello World for ``native_posix``.
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/hello_world
|
|
:host-os: unix
|
|
:board: native_posix
|
|
:goals: build
|
|
|
|
Next, run the application.
|
|
|
|
.. code-block:: console
|
|
|
|
west build -t run
|
|
# or just run zephyr.exe directly:
|
|
./build/zephyr/zephyr.exe
|
|
|
|
Press :kbd:`Ctrl-C` to exit.
|
|
|
|
You can run ``./build/zephyr/zephyr.exe --help`` to get a list of available
|
|
options.
|
|
|
|
This executable can be instrumented using standard tools, such as gdb or
|
|
valgrind.
|
|
|
|
.. rubric:: Footnotes
|
|
|
|
.. [#pip]
|
|
|
|
pip is Python's package installer. Its ``install`` command first tries to
|
|
re-use packages and package dependencies already installed on your computer.
|
|
If that is not possible, ``pip install`` downloads them from the Python
|
|
Package Index (PyPI) on the Internet.
|
|
|
|
The package versions requested by Zephyr's :file:`requirements.txt` may
|
|
conflict with other requirements on your system, in which case you may
|
|
want to set up a virtualenv for Zephyr development.
|
|
|
|
.. [#linux_user]
|
|
|
|
Installing with ``--user`` avoids conflicts between pip and the system
|
|
package manager, and is the default on Debian-based distributions.
|
|
|
|
.. [#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.
|
|
|
|
.. [#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.
|
|
|
|
.. _information on -\\-user: https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site
|
|
.. _Homebrew disables -\\-user: https://docs.brew.sh/Homebrew-and-Python#note-on-pip-install---user
|
|
.. _CMake: https://cmake.org
|
|
.. _generators: https://cmake.org/cmake/help/v3.8/manual/cmake-generators.7.html
|
|
.. _Installing Packages: https://packaging.python.org/tutorials/installing-packages/
|