doc: New developer getting started guide
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:
parent
b4ddc10b42
commit
331214704c
11 changed files with 811 additions and 290 deletions
|
@ -41,6 +41,8 @@ Community Support
|
|||
Community support is provided via mailing lists and Slack; see the Resources
|
||||
below for details.
|
||||
|
||||
.. _project-resources:
|
||||
|
||||
Resources
|
||||
*********
|
||||
|
||||
|
|
|
@ -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
BIN
doc/getting_started/img/ReelBoard-Blinky.gif
Normal file
Binary file not shown.
After Width: | Height: | Size: 178 KiB |
|
@ -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.
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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:
|
||||
|
|
|
@ -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
318
doc/guides/beyond-GSG.rst
Normal 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/
|
|
@ -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
36
doc/static/zephyr-custom.css
vendored
|
@ -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;
|
||||
}
|
||||
|
|
|
@ -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., ©) for that character
|
||||
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue