doc/getting_started/index.rst

.. _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 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.

.. 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/