2b3d9df1d7
The main change is the elimination of the bootstrapper, a design flaw / misfeature. Update the documentation to be compatible with the 0.6.x releases as well. This has to be done atomically, as there were incompatible changes. Make use of the versionchanged and versionadded directives to begin keeping track of how these APIs are evolving. (Note that west 0.6.0 will remain compatible with the extension commands in Zephyr v1.14 LTS as long as that is still alive. This change is targeted towards Zephyr 2.0 users.) This requires a bump in the shippable container and allows us to simplify the west_commands test procedure. Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
350 lines
11 KiB
ReStructuredText
350 lines
11 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.
|
|
|
|
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 west
|
|
|
|
# macOS (Terminal) and Windows (cmd.exe)
|
|
pip3 install 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.
|
|
|
|
.. 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.
|
|
|
|
You can build applications by either running ``cmake`` directly or using the
|
|
:ref:`west build <west-building>` convenience wrapper.
|
|
|
|
.. _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.
|
|
|
|
You can use any supported generator when running ``cmake`` directly or using
|
|
``west build``.
|
|
|
|
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::
|
|
:tool: all
|
|
:app: samples/hello_world
|
|
:board: reel_board
|
|
:goals: build
|
|
|
|
On Linux and macOS, you can also build with ``make`` instead of ``ninja``.
|
|
|
|
Using west:
|
|
|
|
- to use ``make`` just once, add ``-- -G"Unix Makefiles"`` to the west build
|
|
command line; see the :ref:`west build <west-building-generator>`
|
|
documentation for an example.
|
|
- to use ``make`` by default from now on, run ``west config build.generator
|
|
"Unix Makefiles"``.
|
|
|
|
Using CMake directly:
|
|
|
|
.. zephyr-app-commands::
|
|
:tool: cmake
|
|
:app: samples/hello_world
|
|
:generator: make
|
|
:host-os: unix
|
|
:board: reel_board
|
|
:goals: build
|
|
|
|
Either way, 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 run the ``pristine`` build system
|
|
target or 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``, or 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 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::
|
|
:tool: all
|
|
: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::
|
|
:tool: all
|
|
:zephyr-app: samples/hello_world
|
|
:host-os: unix
|
|
:board: native_posix
|
|
:goals: build
|
|
|
|
Next, run the application.
|
|
|
|
.. code-block:: console
|
|
|
|
# With west:
|
|
west build -t run
|
|
|
|
# With ninja:
|
|
ninja -Cbuild 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/
|