michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: New developer getting started guide

Browse source 
As presented to the TSC, Zephyr's out-of-box experience for new
developers is, well, complicated.  A number of suggestions were
presented including simplifying the getting started material to present
a straight-forward path through the setup and installation steps through
to getting a sample application built, flashed, and running.

This PR is a work-in-progress towards addressing this OOB experience
with a minimal-distractions version of the GSG. Alternatives, warnings,
and material that could lead the developer astray were moved to
alternative/advanced instruction documents (based on the previous
separate Linux/macOS/Windows setup guides) and a new "Beyond the GSG"
document.

We do take advantage of a sphinx-tabs extension for synchronized tabs to
present OS-specific instructions: clicking on one tab will display all
same-named tabs throughout the doc.

We hope (and will continue evaluating) that this new GSG gets developers
set up quickly and then we can send them along to other documents to
continue learning about Zephyr and trying other sample apps.

Thanks for all your previous feedback that I've worked
into this new version.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder 2019-09-12 14:32:29 -07:00 • committed by Maureen Helm
commit 331214704c
11 changed files with 811 additions and 290 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README.rst
View file

@ -41,6 +41,8 @@ Community Support
Community support is provided via mailing lists and Slack; see the Resources
below for details.
.. _project-resources:
Resources
*********

3
doc/conf.py
View file

@ -51,7 +51,8 @@ extensions = [
'zephyr.application',
'zephyr.html_redirects',
'only.eager_only',
'zephyr.link-roles'
'zephyr.link-roles',
'sphinx_tabs.tabs'
]
# Only use SVG converter when it is really needed, e.g. LaTeX.

BIN
doc/getting_started/img/ReelBoard-Blinky.gif Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 178 KiB

581
doc/getting_started/index.rst
View file

@ -3,319 +3,452 @@
Getting Started Guide
#####################
Follow this guide to set up a :ref:`Zephyr <introducing_zephyr>` development
environment, then build and run a sample application.
Follow this guide to get a quick start with Zephyr development where
you'll:
.. tip::
- **Set up a command-line development environment** for Linux* (Ubuntu),
macOS, or Windows, with required package manager, compiler, and
build-system tools,
- **Get the sources**,
- **Build, flash, and run** a sample application on your target board.
Need help with something? See :ref:`help`.
\*Instructions for other Linux distributions are discussed in the
:ref:`advanced Linux setup document <installation_linux>`.
.. _host_setup:
Install Host Dependencies
*************************
.. rst-class:: numbered-step
.. _python-pip:
Select and Update OS
********************
Python and pip
==============
Zephyr development depends on an up-to-date host system and common build system
tools. First, make sure your development system OS is updated:
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.
.. tabs::
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`_.
.. group-tab:: Ubuntu
- 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]_.
Use these commands to bring your Linux (Ubuntu) system up to date.
If you're using a different Linux distribution, use the appropriate
package manager for your OS. (See :ref:`installation_linux` for
more information about other Linux distributions.)
- On macOS, `Homebrew disables -\\-user`_.
.. code-block:: bash
- On Windows, see the Installing Packages information on ``--user`` if you
require using this option.
sudo apt update
sudo apt upgrade
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.
.. group-tab:: macOS
On macOS Mojave, you can manually check for updates by choosing
System Preferences from the Apple menu, then clicking Software Update (and
click Update Now if there are). For other macOS versions, see the
`Update macOS topic in Apple support
<https://support.apple.com/en-us/HT201541>`_.
.. group-tab:: Windows
On Windows, you can manually check for updates by selecting Start > Settings >
Update & Security > Windows Update, and then select Check for updates.
If updates are available, install them.
.. _install-required-tools:
Install the required tools
===========================
.. rst-class:: numbered-step
Follow an operating system specific guide, then come back to this page.
Install dependencies
********************
.. toctree::
:maxdepth: 1
Next, use a package manager to install required support tools. Python 3
and its package manager, pip, are used extensively by Zephyr for
installing and running scripts used to compile, build, and run Zephyr
applications.
Linux <installation_linux.rst>
macOS <installation_mac.rst>
Windows <installation_win.rst>
We'll also install Zephyr's multi-purpose west tool.
.. tabs::
.. group-tab:: Ubuntu
#. Use the ``apt`` package manager to install these tools:
.. code-block:: bash
sudo apt install --no-install-recommends git cmake ninja-build gperf \
ccache dfu-util device-tree-compiler wget \
python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \
make gcc gcc-multilib
#. Verify the version of cmake installed on your system using::
cmake --version
If it's not version 3.13.1 or higher, follow these steps to
add the `kitware third-party apt repository <https://apt.kitware.com/>`__
to get an updated version of cmake.
a) Add the kitware signing key to apt:
.. code-block:: bash
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | sudo apt-key add -
b) Add the kitware repo corresponding to your Ubuntu LTS release (use
``cat /etc/os-release`` to check):
For Ubuntu Bionic Beaver (18.04) use::
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main'
For Ubuntu Xenial Xerus (16.04) use::
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ xenial main'
c) Then install the updated cmake using the usual apt commands:
.. code-block:: bash
sudo apt update
sudo apt install cmake
#. Install west:
.. code-block:: bash
pip3 install --user -U west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
The pip3 ``--user`` option puts installed Python packages into your
``~/.local/bin folder`` so we'll need to add this to the PATH
so these packages will be found. Adding the PATH specification to your
``.bashrc`` file ensures this setting is permanent.
.. group-tab:: macOS
#. On macOS, install :program:`Homebrew` by following instructions on the `Homebrew
site`_, and as shown here. Homebrew is a free and open-source package management system that
simplifies installing software on macOS. While installing Homebrew,
you may be prompted to install additional missing dependencies; please follow
any such instructions as well.
.. code-block:: bash
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
#. Then, install these host dependencies with the ``brew`` command:
.. code-block:: bash
brew install cmake ninja gperf ccache dfu-util qemu dtc python3
#. Install west:
.. code-block:: bash
pip3 install west
.. _Homebrew site: https://brew.sh/
.. group-tab:: Windows
.. note:: Currently, the built-in `Windows Subsystem for Linux (WSL)
<https://msdn.microsoft.com/en-us/commandline/wsl/install_guide>`__
doesn't support flashing your application to the board. As such,
we don't recommend using WSL yet.
These instructions assume you are using the Windows ``cmd.exe``
command prompt. Some of the details, such as setting environment
variables, may differ if you are using PowerShell.
An easy way to install native Windows dependencies is to first install
`Chocolatey`_, a package manager for Windows. If you prefer to install
dependencies manually, you can also download the required programs from their
respective websites and verify they can be found on your PATH.
|p|
#. Install :program:`Chocolatey` by following the instructions on the
`Chocolatey install`_ page.
#. Open a command prompt (``cmd.exe``) as an **Administrator** (press the
Windows key, type "cmd.exe" in the prompt, then right-click the result and
choose "Run as Administrator").
#. Disable global confirmation to avoid having to confirm
installation of individual programs:
.. code-block:: console
choco feature enable -n allowGlobalConfirmation
#. Install CMake:
.. code-block:: console
choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
#. Install the rest of the tools:
.. code-block:: console
choco install git python ninja dtc-msys2 gperf
#. Close the Administrator command prompt window and open a
regular command prompt window to continue..
#. Install west:
.. code-block:: bash
pip3 install west
.. _Chocolatey: https://chocolatey.org/
.. _Chocolatey install: https://chocolatey.org/install
.. _get_the_code:
.. _clone-zephyr:
.. rst-class:: numbered-step
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>`.)
Zephyr's multi-purpose west tool simplifies getting the Zephyr
project git repositories and external modules used by Zephyr.
Clone all of Zephyr's git repositories in a new :file:`zephyrproject`
directory using west:
Install west
============
.. tabs::
First, install ``west`` using ``pip3``:
.. group-tab:: Ubuntu
.. code-block:: console
.. code-block:: bash
# Linux
pip3 install --user -U west
cd ~
west init zephyrproject
cd zephyrproject
west update
# macOS (Terminal) and Windows (cmd.exe)
pip3 install -U west
.. group-tab:: macOS
See :ref:`west-install` for additional details on installing west.
.. code-block:: bash
.. _clone-zephyr:
cd ~
west init zephyrproject
cd zephyrproject
west update
Clone the Zephyr Repositories
=============================
.. group-tab:: Windows
Clone all of Zephyr's repositories in a new :file:`zephyrproject` directory:
.. code-block:: bat
.. code-block:: console
cd %HOMEPATH%
west init zephyrproject
cd zephyrproject
west update
west init zephyrproject
cd zephyrproject
west update
.. rst-class:: numbered-step
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.
Install needed Python packages
******************************
.. important::
The Zephyr source folders we downloaded contain a ``requirements.txt`` file
that we'll use to install additional Python tools used by the Zephyr
project:
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.
.. tabs::
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.
.. group-tab:: Ubuntu
.. warning::
.. code-block:: bash
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.
pip3 install --user -r ~/zephyrproject/zephyr/scripts/requirements.txt
.. group-tab:: macOS
.. code-block:: bash
pip3 install -r ~/zephyrproject/zephyr/scripts/requirements.txt
.. group-tab:: Windows
.. code-block:: bat
pip3 install -r %HOMEPATH%\zephyrproject\zephyr\scripts\requirements.txt
.. _gs_python_deps:
Install Python Dependencies
***************************
.. rst-class:: numbered-step
Install Python packages required by Zephyr. From the :file:`zephyrproject`
folder that you :ref:`cloned Zephyr into <clone-zephyr>`:
Install Software Development Toolchain
**************************************
.. 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`.
A toolchain includes necessary tools used to build Zephyr applications
including: compiler, assembler, linker, and their dependencies.
.. toctree::
:maxdepth: 2
.. _Zephyr Downloads: https://www.zephyrproject.org/developers/#downloads
toolchain_3rd_party_x_compilers.rst
toolchain_other_x_compilers.rst
toolchain_host.rst
toolchain_custom_cmake.rst
.. tabs::
.. group-tab:: Ubuntu
Zephyr's Software Development Kit (SDK) contains necessary Linux
development tools to build Zephyr on all supported architectures.
Additionally, it includes host tools such as custom QEMU binaries and a
host compiler.
|p|
#. Download the latest SDK as a self-extracting installation binary:
.. code-block:: bash
cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.10.3/zephyr-sdk-0.10.3-setup.run
#. Run the installation binary, installing the SDK in your home
folder :file:`~/zephyr-sdk-0.10.3`:
.. code-block:: bash
chmod +x zephyr-sdk-0.10.3-setup.run
./zephyr-sdk-0.10.3-setup.run -- -d ~/zephyr-sdk-0.10.3
#. Set environment variables to let the build system know where to
find the toolchain programs:
.. code-block:: bash
export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.10.3
The SDK contains a udev rules file that provides information
needed to identify boards and grant hardware access permission to flash
tools. Install these udev rules with these commands:
.. code-block:: bash
sudo cp ${ZEPHYR_SDK_INSTALL_DIR}/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
sudo udevadm control --reload
.. group-tab:: macOS
The Zephyr SDK is not supported on macOS. See instructions for
:ref:`installing 3rd-party toolchains<gs_toolchain>`.
.. group-tab:: Windows
The Zephyr SDK is not supported on Windows. See instructions for
:ref:`installing 3rd-party toolchains<gs_toolchain>`.
.. _getting_started_run_sample:
Build and Run an Application
.. rst-class:: numbered-step
Build the Blinky 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.
The sample :ref:`blinky-sample` blinks an LED on the target board. By
building and running it, we can verify that the environment and tools
are properly set up for Zephyr development.
Build Hello World
=================
#. Set build environment variables:
Let's build the :ref:`hello_world` sample application.
.. tabs::
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.
.. group-tab:: Ubuntu
#. Go to the zephyr repository:
.. code-block:: bash
.. code-block:: console
cd ~/zephyrproject/zephyr
source zephyr-env.sh
cd zephyrproject/zephyr
.. group-tab:: macOS
#. Set up your build environment:
.. code-block:: bash
.. code-block:: console
cd ~/zephyrproject/zephyr
source zephyr-env.sh
# Linux and macOS
source zephyr-env.sh
.. group-tab:: Windows
# Windows
zephyr-env.cmd
.. code-block:: bat
#. Build the Hello World sample for the ``reel_board``:
cd %HOMEPATH%/zephyrproject/zephyr
zephyr-env.cmd
.. zephyr-app-commands::
:app: samples/hello_world
:board: reel_board
:goals: build
#. Build the blinky sample. Specify **your board name**
(see :ref:`boards`) in the command below:
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.
.. code-block:: bash
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``.
west build -p auto -b <your-board-name> samples/basic/blinky
Run the Application by Flashing to a Board
==========================================
This west command uses the ``-p auto`` parameter to automatically
clean out any byproducts from a previous build if needed, useful if
you try building another sample.
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.
.. rst-class:: numbered-step
See :ref:`application_run` in the Application Development Primer and your
board's documentation in :ref:`boards` for additional details.
Flash and Run the Application
*****************************
Run the Application in QEMU
===========================
#. Connect a USB cable between the board and your development computer.
(Refer to the specific :ref:`boards` documentation if you're not sure
which connector to use on the board.)
#. If there's a switch, turn the board on.
#. Flash the blinky application you just built using the command:
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.
.. tabs::
To build and run Hello World using the x86 emulation board configuration
(``qemu_x86``), type:
.. group-tab:: Ubuntu
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:host-os: unix
:board: qemu_x86
:goals: build run
.. code-block:: bash
To exit, type :kbd:`Ctrl-a`, then :kbd:`x`.
west flash
Use ``qemu_cortex_m3`` to target an emulated Arm Cortex-M3 instead.
If the flash command fails, and you've checked your
board is powered on and connected to the right on-board USB connector,
verify you've granted needed access permission by
:ref:`setting-udev-rules`.
.. _gs_posix:
.. group-tab:: macOS
Run a Sample Application natively (POSIX OS)
============================================
.. code-block:: bash
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.
west flash
First, build Hello World for ``native_posix``.
.. group-tab:: Windows
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:host-os: unix
:board: native_posix
:goals: build
.. code-block:: bat
Next, run the application.
west flash
.. code-block:: console
west build -t run
# or just run zephyr.exe directly:
./build/zephyr/zephyr.exe
The application will start running and you'll see blinky in action. The
actual blinking LED location is board specific.
Press :kbd:`Ctrl-C` to exit.
.. figure:: img/ReelBoard-Blinky.gif
:width: 400px
:name: reelboard-blinky
You can run ``./build/zephyr/zephyr.exe --help`` to get a list of available
options.
Phytec reel_board running blinky
This executable can be instrumented using standard tools, such as gdb or
valgrind.
.. rubric:: Footnotes
Next Steps
**********
.. [#pip]
Now that you've got the blinky sample running, here are some next steps
for exploring Zephyr:
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/
* Try some other :ref:`samples-and-demos` that demonstrate Zephyr
capabilities.
* Learn about :ref:`application` and more details about :ref:`west`.
* Check out :ref:`beyond-GSG` for information about advanced setup
alternatives and issues.
* Discover :ref:`project-resources` for getting help from the Zephyr
community.

148
doc/getting_started/installation_linux.rst
View file

@ -3,10 +3,6 @@
Install Linux Host Dependencies
###############################
.. important::
Go back to the main :ref:`getting_started` when you're done here.
Documentation is available for these Linux distributions:
* Ubuntu
@ -19,35 +15,44 @@ requirements and dependencies may not be met by your package manager. In that
case please follow the additional instructions that are provided to find
software from sources other than the package manager.
.. note:: If you're working behind a corporate firewall, you'll likely
need to configure a proxy for accessing the internet, if you haven't
done so already. While some tools use the environment variables
``http_proxy`` and ``https_proxy`` to get their proxy settings, some
use their own configuration files, most notably ``apt`` and
``git``.
Update Your Operating System
****************************
Ensure your host system is up to date.
Ubuntu:
.. tabs::
.. code-block:: console
.. group-tab:: Ubuntu
sudo apt-get update
sudo apt-get upgrade
.. code-block:: console
Fedora:
sudo apt-get update
sudo apt-get upgrade
.. code-block:: console
.. group-tab:: Fedora
sudo dnf upgrade
.. code-block:: console
Clear Linux:
sudo dnf upgrade
.. code-block:: console
.. group-tab:: Clear Linux
sudo swupd update
.. code-block:: console
Arch Linux:
sudo swupd update
.. code-block:: console
.. group-tab:: Arch Linux
sudo pacman -Syu
.. code-block:: console
sudo pacman -Syu
.. _linux_requirements:
@ -65,65 +70,81 @@ Install Requirements and Dependencies
Note that both Ninja and Make are installed with these instructions; you only
need one.
Ubuntu:
.. tabs::
.. code-block:: console
.. group-tab:: Ubuntu
sudo apt-get install --no-install-recommends git cmake ninja-build gperf \
ccache dfu-util device-tree-compiler wget \
python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \
make gcc gcc-multilib
.. code-block:: console
Fedora:
sudo apt-get install --no-install-recommends git cmake ninja-build gperf \
ccache dfu-util device-tree-compiler wget \
python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \
make gcc gcc-multilib
.. code-block:: console
.. group-tab:: Fedora
.. code-block:: console
sudo dnf group install "Development Tools" "C Development Tools and Libraries"
dnf install git cmake ninja-build gperf ccache dfu-util dtc wget \
python3-pip python3-tkinter xz file glibc-devel.i686 libstdc++-devel.i686
sudo dnf group install "Development Tools" "C Development Tools and Libraries"
dnf install git cmake ninja-build gperf ccache dfu-util dtc wget \
python3-pip python3-tkinter xz file glibc-devel.i686 libstdc++-devel.i686
Clear Linux:
.. group-tab:: Clear Linux
.. code-block:: console
.. code-block:: console
sudo swupd bundle-add c-basic dev-utils dfu-util dtc \
os-core-dev python-basic python3-basic python3-tcl
sudo swupd bundle-add c-basic dev-utils dfu-util dtc \
os-core-dev python-basic python3-basic python3-tcl
The Clear Linux focus is on *native* performance and security and not
cross-compilation. For that reason it uniquely exports by default to the
:ref:`environment <env_vars>` of all users a list of compiler and linker
flags. Zephyr's CMake build system will either warn or fail because of
these. To clear the C/C++ flags among these and fix the Zephyr build, run
the following command as root then log out and back in:
The Clear Linux focus is on *native* performance and security and not
cross-compilation. For that reason it uniquely exports by default to the
:ref:`environment <env_vars>` of all users a list of compiler and linker
flags. Zephyr's CMake build system will either warn or fail because of
these. To clear the C/C++ flags among these and fix the Zephyr build, run
the following command as root then log out and back in:
.. code-block:: console
.. code-block:: console
# echo 'unset CFLAGS CXXFLAGS' >> /etc/profile.d/unset_cflags.sh
echo 'unset CFLAGS CXXFLAGS' >> /etc/profile.d/unset_cflags.sh
Note this command unsets the C/C++ flags for *all users on the
system*. Each Linux distribution has a unique, relatively complex and
potentially evolving sequence of bash initialization files sourcing each
other and Clear Linux is no exception. If you need a more flexible
solution, start by looking at the logic in
``/usr/share/defaults/etc/profile``.
Note this command unsets the C/C++ flags for *all users on the
system*. Each Linux distribution has a unique, relatively complex and
potentially evolving sequence of bash initialization files sourcing each
other and Clear Linux is no exception. If you need a more flexible
solution, start by looking at the logic in
``/usr/share/defaults/etc/profile``.
Arch Linux:
.. group-tab:: Arch Linux
.. code-block:: console
.. code-block:: console
sudo pacman -S git cmake ninja gperf ccache dfu-util dtc wget \
python-pip python-setuptools python-wheel tk xz file make
sudo pacman -S git cmake ninja gperf ccache dfu-util dtc wget \
python-pip python-setuptools python-wheel tk xz file make
**CMake version 3.13.1 or higher is required**. Check what version you have by
CMake
=====
CMake version 3.13.1 or higher is required. Check what version you have by
using ``cmake --version``. If you have an older version, there are several ways
of obtaining a more recent one:
* Use ``pip3`` (see :ref:`python-pip` for more details):
* On Ubuntu, you can follow the instructions for adding the
`kitware third-party apt repository <https://apt.kitware.com/>`_
to get an updated version of cmake using apt.
* Download and install a packaged cmake from the CMake project site.
(Note this won't uninstall the previous version of cmake.)
.. code-block:: console
pip3 install --user cmake
cd ~
wget https://github.com/Kitware/CMake/releases/download/v3.15.3/cmake-3.15.3-Linux-x86_64.sh
chmod +x cmake-3.15.3-Linux-x86_64.sh
sudo ./cmake-3.15.3-Linux-x86_64.sh --skip-license --prefix=/usr/local
hash -r
The ``hash -r`` command may be necessary if the installation script
put cmake into a new location on your PATH.
* Download and install from the pre-built binaries provided by the CMake
project itself in the `CMake Downloads`_ page.
@ -136,6 +157,17 @@ of obtaining a more recent one:
yes | sh cmake-3.13.1-Linux-x86_64.sh | cat
echo "export PATH=$PWD/cmake-3.13.1-Linux-x86_64/bin:\$PATH" >> $HOME/.zephyrrc
* Use ``pip3``:
.. code-block:: console
pip3 install --user cmake
Note this won't uninstall the previous version of cmake and will
install the new cmake into your ~/.local/bin folder so
you'll need to add ~/.local/bin to your PATH. (See :ref:`python-pip`
for details.)
* Check your distribution's beta or unstable release package library for an
update.
@ -145,10 +177,16 @@ of obtaining a more recent one:
sudo snap install cmake
After updating cmake, verify that the newly installed cmake is found
using ``cmake --version``.
You might also want to uninstall the CMake provided by your package manager to
avoid conflicts.
avoid conflicts. (Use ``whereis cmake`` to find other installed
versions.)
**A recent DTC version (1.4.6 or higher) is required**. Check what version you
DTC (Device Tree Compiler)
==========================
A recent DTC version (1.4.6 or higher) is required. Check what version you
have by using ``dtc --version``. If you have an older version, either install a
more recent one by building from source, or use the one that is bundled in
the :ref:`Zephyr SDK <zephyr_sdk>` by installing it and setting the

4
doc/getting_started/installation_mac.rst
View file

@ -3,10 +3,6 @@
Install macOS Host Dependencies
###############################
.. important::
Go back to the main :ref:`getting_started` when you're done here.
This section describes how to set up a Zephyr development environment on macOS.
These instructions have been tested on the following macOS versions:

4
doc/getting_started/installation_win.rst
View file

@ -3,10 +3,6 @@
Install Windows Host Dependencies
#################################
.. important::
Go back to the main :ref:`getting_started` when you're done here.
This guide was tested on Windows versions 7, 8.1, and 10.
Update Your Operating System

318
doc/guides/beyond-GSG.rst Normal file
View file

@ -0,0 +1,318 @@
.. _beyond-gsg:
Beyond the Getting Started Guide
################################
The :ref:`getting_started` gives a straight-forward path to set up
your Linux, macOS, or Windows environment for Zephyr development. In
this document, we delve deeper into Zephyr development setup
issues and alternatives.
.. _python-pip:
Python and pip
**************
Python 3 and its package manager, pip\ [#pip]_, are used extensively by Zephyr
to install and run scripts required to compile and run Zephyr
applications, set up and maintain the Zephyr development environment,
and build project documentation.
Depending on your operating system, you may 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 `information on -\\-user`_.
- On Linux, make sure ``~/.local/bin`` is at the front of your :envvar:`PATH`
:ref:`environment variable <env_vars>`, or programs installed with ``--user``
won't be found. Installing with ``--user`` avoids conflicts between pip
and the system package manager, and is the default on Debian-based
distributions.
- On macOS, `Homebrew disables -\\-user`_.
- On Windows, see the `Installing Packages`_ information on ``--user`` if you
require using this option.
On all operating systems, pip's ``-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. (Check the :zephyr_file:`scripts/requirements.txt` file to
see if a specific Python package version is expected.)
Advanced Setup and tool chain alternatives
******************************************
Here are some alternative instructions for more advanced platform setup
configurations for supported development platforms:
.. toctree::
:maxdepth: 1
Linux setup alternatives <../getting_started/installation_linux.rst>
macOS setup alternatives <../getting_started/installation_mac.rst>
Windows setup alternatives <../getting_started/installation_win.rst>
.. _gs_toolchain:
Set Up a Toolchain
******************
Zephyr binaries are compiled and linked by a *toolchain* comprised of
a cross-compiler and related tools which are different than the compiler
and tools used for developing software that runs
natively on your operating system.
On Linux systems, you can install the :ref:`Zephyr SDK <zephyr_sdk>` to
get toolchains for all supported architectures. Otherwise, you can
install other toolchains in the usual way for your operating system: with
installer programs or system package managers, by downloading and
extracting a zip archive, etc.
You configure the Zephyr build system to use a specific toolchain by
setting :ref:`environment variables <env_vars>` such as
:envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to a supported value, along with
additional variable(s) specific to the toolchain variant.
While the Zephyr SDK includes standard tool chains for all supported
architectures, there are also customized alternatives as described in
these documents. (If you're not sure which to use, check your specific
:ref:`board-level documentation <boards>`. If you're targeting an Arm
Cortex-M board, for example, :ref:`toolchain_gnuarmemb` is a safe bet.)
.. toctree::
:maxdepth: 2
../getting_started/toolchain_3rd_party_x_compilers.rst
../getting_started/toolchain_other_x_compilers.rst
../getting_started/toolchain_host.rst
../getting_started/toolchain_custom_cmake.rst
Cloning the Zephyr Repositories
*******************************
The Zephyr project source is maintained in the `GitHub zephyr repo
<https://github.com/zephyrproject-rtos/zephyr>`_. External modules used
by Zephyr are found in the parent `GitHub Zephyr project
<https://github.com/zephyrproject-rtos/>`_. Because of these
dependencies, it's convenient to use the Zephyr-created :ref:`west
<west>` tool to fetch and manage the Zephyr and external module source
code. See :ref:`west-multi-repo` for more details.
Once your development tools are installed, use :ref:`west` to create,
initialize, and download sources from the zephyr and external module
repos. We'll use the name ``zephyrproject``, but you can choose any
name that does not contain a space anywhere in the path.
.. code-block:: console
west init zephyrproject
cd zephyrproject
west update
The ``west update`` command fetches and keeps :ref:`modules` in the
:file:`zephyrproject` folder in sync with the code in the local zephyr
repo.
.. warning::
You must run ``west update`` any time the :file:`zephyr/west.yml`
changes, caused, for example, when you pull the :file:`zephyr`
repository, switch branches in it, or perform a ``git bisect`` inside of
it.
Build and Run an Application
****************************
You can build, flash, and run Zephyr applications on real
hardware using a 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 Blinky
============
Let's build the :ref:`blinky-sample` sample application.
Zephyr applications are built to run on specific hardware, called a
"board"\ [#board_misnomer]_. We'll use the Phytec :ref:`reel_board
<reel_board>` here, but you can change the ``reel_board`` build target
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 variables:
.. code-block:: console
# Linux and macOS
source zephyr-env.sh
# Windows
zephyr-env.cmd
#. Build the blinky sample for the ``reel_board``:
.. zephyr-app-commands::
:app: samples/basic/blinky
:board: reel_board
:goals: build
The main build products will be in :file:`build/zephyr`;
:file:`build/zephyr/zephyr.elf` is the blinky application binary in ELF
format. Other binary formats, disassembly, and map files may be present
depending on your board.
The other sample applications in the :zephyr_file:`samples` folder are
documented in :ref:`samples-and-demos`.
.. note:: If you want to re-use an
existing build directory for another board or application, you need to
add the parameter ``-p=auto`` to ``west build`` to clean out settings
and artifacts from the previous build.
Run the Application by Flashing to a Board
==========================================
Most hardware boards supported by Zephyr can be flashed by running
``west flash``. This may require board-specific tool installation and
configuration to work properly.
See :ref:`application_run` and your specific board's documentation in
:ref:`boards` for additional details.
.. _setting-udev-rules:
Setting udev rules
===================
Flashing a board requires permission to directly access the board
hardware, usually managed by installation of the flashing tools. On
Linux systems, if the ``west flash`` command fails, you likely need to
define udev rules to grant the needed access permission.
Udev is a device manager for the Linux kernel and the udev daemon
handles all user space events raised when a hardware device is added (or
removed) from the system. We can add a rules file to grant access
permission by non-root users to certain USB-connected devices.
The OpenOCD (On-Chip Debugger) project conveniently provides a rules
file that defined board-specific rules for most Zephyr-supported
arm-based boards, so we recommend installing this rules
file by downloading it from their sourceforge repo, or if you've
installed the Zephyr SDK there is a copy of this rules file in the SDK
folder:
* Either download the OpenOCD rules file and copy it to the right
location::
wget -O 60-openocd.rules https://sf.net/p/openocd/code/ci/master/tree/contrib/60-openocd.rules?format=raw
sudo cp 60-openocd.rules /etc/udev/rules.d
* or copy the rules file from the Zephyr SDK folder::
sudo cp ${ZEPHYR_SDK_INSTALL_DIR}/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
Then, in either case, ask the udev daemon to reload these rules::
sudo udevadm control --reload
Unplug and plug in the USB connection to your board, and you should have
permission to access the board hardware for flashing. Check your
board-specific documentation (:ref:`boards`) for further information if
needed.
Run the Application in QEMU
===========================
On Linux and macOS, you can run Zephyr applications via emulation on your host
system using `QEMU <https://www.qemu.org/>`_ when targeting either
the x86 or ARM Cortex-M3 architectures. (QEMU is included with the Zephyr
SDK installation.)
For example, you can build and run the :ref:`hello_world` sample using
the x86 emulation board configuration (``qemu_x86``), with:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:host-os: unix
:board: qemu_x86
:goals: build run
To exit QEMU, type :kbd:`Ctrl-a`, then :kbd:`x`.
Use ``qemu_cortex_m3`` to target an emulated Arm Cortex-M3 sample.
.. _gs_posix:
Run a Sample Application natively (POSIX OS)
============================================
You can 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.
.. [#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
.. _Installing Packages:
https://packaging.python.org/tutorials/installing-packages/

1
doc/guides/index.rst
View file

@ -7,6 +7,7 @@ User and Developer Guides
:maxdepth: 1
getting-help.rst
beyond-GSG.rst
bluetooth/index.rst
c_library
../README.rst

36
doc/static/zephyr-custom.css vendored
View file

@ -43,6 +43,10 @@ div.rst-other-versions dl {
margin-bottom: 0;
}
/* tweak spacing after a toctree */
.toctree-wrapper ul, .section ul {
margin-bottom: 24px !important;
}
/* code block highlight color in rtd changed to lime green, no no no */
@ -240,8 +244,8 @@ kbd
.grid-item a:hover {
background-color: #C756E9;
color: white;
background-color: #C756E9;
color: white;
}
@ -264,3 +268,31 @@ kbd
.rst-columns {
column-width: 18em;
}
/* numbered "h2" steps */
body {
counter-reset: step-count;
}
div.numbered-step h2::before {
counter-increment: step-count;
content: counter(step-count);
background: #cccccc;
border-radius: 0.8em;
-moz-border-radius: 0.8em;
-webkit-border-radius: 0.8em;
color: #ffffff;
display: inline-block;
font-weight: bold;
line-height: 1.6em;
margin-right: 5px;
text-align: center;
width: 1.6em;
}
/* tweak bottom margin of a code block in a list */
.tab div[class^='highlight']:last-child {
margin-bottom: 1em;
}

4
doc/substitutions.txt
View file

@ -2,6 +2,10 @@
<br />
.. |p| raw:: html .. force a blank line in HTML output (blank lines needed here)
<p></p>
.. These are replacement strings for non-ASCII characters used within the project
using the same name as the html entity names (e.g., &copy;) for that character