zephyrproject-rtos/zephyr
0
0
Fork 0
mirror of https://github.com/zephyrproject-rtos/zephyr synced 2025-09-12 03:31:55 +00:00
Code Issues Packages Projects Releases Wiki Activity
917dd83e8b
zephyr/doc/getting_started/getting_started.rst
Marti Bolivar 0d811b9aee doc: overhaul getting_started 
The getting started documentation has become a bit of a mess over
time:

- The reader needs to jump forward and backward in the documents
  depending on what their system already has installed (e.g. "start by
  cloning Zephyr, oh wait, see below if you don't have Git yet" etc.).

- The operating system setup guides, toolchain setup instructions, and
  application build and run information have each become their own
  balkanized fiefdom, with duplicated, confusing and sometimes
  inconsistent results.

- Linux documentation for all distributions is incomplete in some
  places (the Arch documentation in particular is vestigial)
  and wrong in others (platforms like Ubuntu still nominally require
  tools, like autoconf, that haven't been necessary since we stopped
  using the C Kconfig tools)

- The dependencies needed to build the documentation have
  gotten *huge* since the LaTeX additions and massively overstate the
  footprint of Zephyr's real dependencies. This is particularly a
  problem on Linux, where those dependencies were not clearly
  separated from those needed to build Zephyr.

- The toolchain setup documentation is confusing and scattered across
  the main file and the platform-specific files. There are various
  bits of incomplete and/or incorrect information. For example, the
  docs imply that you can use the Zephyr SDK on non-Linux hosts, which
  isn't true. As another example, some toolchains, such as GNU Arm
  Embedded, are documented several times. As a final example, some
  toolchains, such as Intel's ISSM, are squirrelled away in the
  Windows document when there are Linux builds available.

Overhaul the pages to fix these issues and otherwise clean up the
language. One significant side-effect is that all the
toolchain-related information is rooted in a single toctree. Another
is that it should now be possible to follow the instructions, in
order, on any supported platform.

Signed-off-by: Marti Bolivar <marti@foundries.io>
2018-10-17 19:07:58 -04:00

304 lines
10 KiB
ReStructuredText
Raw Blame History

.. _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 -r --user 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 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
Reference in New Issue View Git Blame Copy Permalink