michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: overhaul getting_started

Browse source 
The getting started documentation has become a bit of a mess over
time:

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

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

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

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

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

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

Signed-off-by: Marti Bolivar <marti@foundries.io>
This commit is contained in:
Marti Bolivar 2018-10-14 23:20:24 -06:00 • committed by Anas Nashif
commit 0d811b9aee
8 changed files with 656 additions and 679 deletions
Download patch file Download diff file Expand all files Collapse all files

48
doc/README.rst
View file

@ -55,10 +55,50 @@ Our documentation processing has been tested to run with:
* sphinxcontrib-svg2pdfconverter version 0.1.0
* Latexmk version version 4.56
In order to install the documentation tools, clone a copy of the git repository
for the Zephyr project and set up your development environment as described in
:ref:`getting_started`. This will ensure all the required tools are installed
on your system.
In order to install the documentation tools, first install Zephyr as
described in :ref:`getting_started`. Then install additional tools
that are only required to generate the documentation,
as described below:
On Ubuntu Linux:
.. code-block:: console
sudo apt-get install --no-install-recommends doxygen librsvg2-bin \
texlive-latex-base texlive-latex-extra latexmk texlive-fonts-recommended
On Fedora Linux:
.. code-block:: console
sudo dnf install doxygen texlive-latex latexmk \
texlive-collection-fontsrecommended librsvg2-tools
On Clear Linux:
.. code-block:: console
sudo swupd bundle-add texlive
On Arch Linux:
.. code-block:: console
sudo pacman -S doxygen librsvg texlive-core texlive-bin
On macOS:
.. code-block:: console
brew install doxygen mactex librsvg
tlmgr install latexmk
tlmgr install collection-fontsrecommended
On Windows in an Administrator ``cmd.exe`` prompt:
.. code-block:: console
choco install doxygen.install strawberryperl miktex rsvg-convert
.. note::
On Windows, the Sphinx executable ``sphinx-build.exe`` is placed in

468
doc/getting_started/getting_started.rst
View file

@ -3,84 +3,163 @@
Getting Started Guide
#####################
Use this guide to get started with your :ref:`Zephyr <introducing_zephyr>`
development.
Follow this guide to set up a :ref:`Zephyr <introducing_zephyr>` development
environment on your system, and then build and run a sample application.
Checking Out the Source Code Anonymously
****************************************
.. _host_setup:
The Zephyr source code is hosted in a GitHub repo that supports
anonymous cloning via git. There are scripts and such in this repo that
you'll need to set up your development environment, and we'll be using
Git to get this repo. (If you don't have Git installed, see the
beginning of the OS-specific instructions below for help.)
Set Up a Development System
***************************
We'll begin by
using Git to clone the repository anonymously. Enter:
.. code-block:: console
# On Linux/macOS
cd ~
# On Windows
cd %userprofile%
git clone https://github.com/zephyrproject-rtos/zephyr.git
You have successfully checked out a copy of the source code to your local
machine in a ``zephyr`` folder in your home directory.
.. _getting_started_cmake:
A brief note on the Zephyr build system
***************************************
The Zephyr project uses `CMake`_ as a tool for managing the building of the
project. CMake is able to generate build files in different formats (also
known as "generators"), and the following ones are currently supported
by Zephyr:
* ``make``: Supported on UNIX-like platforms (Linux, macOS).
* ``ninja``: Supported on all platforms.
Most of the examples in the Zephyr documentation use ``ninja`` as a build tool,
but you should be able to use any generator on any of the examples listed.
Set Up the Development Environment
**********************************
The Zephyr project supports these operating systems:
* Linux
* macOS
* Microsoft Windows
Use the following procedures to create a new development environment.
Follow one of the following guides for your host operating system.
.. toctree::
:maxdepth: 1
installation_linux.rst
installation_mac.rst
installation_win.rst
Linux <installation_linux.rst>
macOS <installation_mac.rst>
Windows <installation_win.rst>
Clone the Zephyr Repository
***************************
To clone the Zephyr source code repository from GitHub:
.. code-block:: console
git clone https://github.com/zephyrproject-rtos/zephyr
.. warning::
Don't clone Zephyr to a directory with spaces anywhere in the path.
For example, on Windows, :file:`C:\\Users\\YourName\\zephyr` will
work, but :file:`C:\\Users\\Your Name\\zephyr` will cause cryptic
errors when you try to build an application.
Install Python Dependencies
***************************
Next, install additional Python packages required by Zephyr in a shell or
``cmd.exe`` prompt:
.. code-block:: console
# Linux
pip3 install -r --user zephyr/scripts/requirements.txt
# macOS and Windows
pip3 install -r zephyr/scripts/requirements.txt
Some notes on pip's ``--user`` option:
- Installing with ``--user`` is the default behavior on Debian-based
distributions and is generally recommended on Linux to avoid conflicts with
Python packages installed using the system package manager.
- On macOS, Homebrew disables the ``--user`` flag\ [#homebrew_user]_.
- On Windows using ``cmd.exe``, although it's possible to use the ``--user``
flag, it makes it harder for the command prompt to find executables installed
by pip.
Set Up a Toolchain
******************
.. note::
On Linux, you can skip this step if you installed the :ref:`Zephyr SDK
<zephyr_sdk>`, which includes toolchains for all supported Zephyr
architectures.
If you want, you can use the SDK host tools (such as OpenOCD) with a
different toolchain by keeping the :envvar:`ZEPHYR_SDK_INSTALL_DIR`
environment variable set to the Zephyr SDK installation directory, while
setting :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` appropriately for a non-SDK
toolchain.
Zephyr binaries are compiled using software called a *toolchain*. You need to
*install* and *configure* a toolchain to develop Zephyr applications\
[#tools_native_posix]_.
Toolchains can be *installed* in different ways, including using installer
programs, system package managers, or simply downloading a zip file or other
archive and extracting the files somewhere on your computer. You *configure*
the toolchain by setting the environment variable
:envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to a recognized value, along with some
additional variable(s) specific to that toolchain (usually, this is just one
more variable which contains the path where you installed the toolchain on your
file system).
.. note::
In previous releases of Zephyr, the ``ZEPHYR_TOOLCHAIN_VARIANT`` variable
was called ``ZEPHYR_GCC_VARIANT``.
The following toolchain installation options are available. The right choice
for you depends on where you want to run Zephyr and any other requirements you
may have. Check your :ref:`board-level documentation <boards>` if you are
unsure about what choice to use.
.. toctree::
:maxdepth: 2
toolchain_3rd_party_x_compilers.rst
toolchain_other_x_compilers.rst
toolchain_custom_cmake.rst
To use the same toolchain in new sessions in the future you can make
sure the variables are set persistently.
On macOS and Linux, you can set the variables by putting the ``export`` lines
setting environment variables in a file :file:`~/.zephyrrc`. On Windows, you
can put the ``set`` lines in :file:`%userprofile%\\zephyrrc.cmd`. These files
are used to modify your environment when you run ``zephyr-env.sh`` (Linux,
macOS) and ``zephyr-env.cmd`` (Windows), which you will learn about in the next
step.
.. _getting_started_run_sample:
Building and Running an Application
***********************************
Build and Run an Application
****************************
Next, build a sample Zephyr application. You can then run it either in
emulation or using POSIX APIs available on your host.
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.
If your board is supported by Zephyr (see :ref:`boards` for a list),
consult its documentation for flashing and running instructions.
.. _getting_started_cmake:
Building a Sample Application
=============================
A Brief Note on the Zephyr Build System
=======================================
Follow these steps to build the :ref:`hello_world` sample application
provided with Zephyr.
The Zephyr build system uses `CMake`_. CMake creates build systems in different
formats, called `generators`_. Zephyr supports the following generators:
* ``Unix Makefiles``: Supported on UNIX-like platforms (Linux, macOS).
* ``Ninja``: Supported on all platforms.
This documentation and Zephyr's continuous integration system mainly use
``Ninja``, but you should be able to use any supported generator to build
Zephyr applications.
Build the Application
=====================
Follow these steps to build the :ref:`hello_world` sample application provided
with Zephyr.
Zephyr applications have to be configured and built to run on some hardware
configuration, which is called a "board"\ [#board_misnomer]_. These steps show
how to build the Hello World application for the :ref:`arduino_101` board. You
can build for a different board by changing ``arduino_101`` to another
supported value. See :ref:`boards` for more information, or run ``ninja usage``
from the build directory (once you've run ``cmake``) to get a list.
.. note::
If you want to re-use your existing build directory to build for another
board, you must delete that directory's contents first by running ``ninja
pristine``.
#. Navigate to the main project directory:
@ -97,203 +176,53 @@ provided with Zephyr.
# On Windows
zephyr-env.cmd
#. Build the :ref:`hello_world` example for the `arduino_101` board, enter:
#. Build the Hello World sample for the ``arduino_101``:
.. Note: we don't use :zephyr-app: here because we just told the user to cd
to ZEPHYR_BASE, so it's not necessary for clarity and would clutter the
instructions a bit.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:app: samples/hello_world
:board: arduino_101
:build-dir: arduino_101
:goals: build
On Linux/macOS you can also build with ``make`` instead of ``ninja``:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:app: samples/hello_world
:generator: make
:host-os: unix
:board: arduino_101
:build-dir: arduino_101
:goals: build
You can build for a different board by defining the variable BOARD
with another of the supported boards, for example:
The main build products are in :file:`zephyr/samples/hello_world/build/zephyr`.
The final application binary in ELF format is named :file:`zephyr.elf` by
default. Other binary formats and byproducts such as disassembly and map files
will be present depending on the target and build system configuration.
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: arduino_due
:build-dir: arduino_due
:goals: build
Other sample projects demonstrating Zephyr's features are located in
:file:`zephyr/samples` and are documented in :ref:`samples-and-demos`.
For further information on the supported boards go see
:ref:`here <boards>`. Alternatively, run the following command to obtain a list
of the supported boards:
Run the Application by Flashing to Another Board
================================================
.. code-block:: console
Most "real hardware" boards supported by Zephyr can be flashed by running
``ninja flash`` from the build directory. However, this may require
board-specific tool installation and configuration to work properly.
ninja usage
See :ref:`application_run` in the Application Development Primer and the
documentation provided with your board at :ref:`boards` for additional details
if you get an error.
Sample projects for different features of the project are available at
at :file:`ZEPHYR_BASE/samples`.
After building an application successfully, the results can be found in the
directory where cmake was invoked.
Run the Application in QEMU
===========================
The ELF binaries generated by the build system are named by default
:file:`zephyr.elf`. This value can be overridden in the application
configuration The build system generates different names for different use cases
depending on the hardware and boards used.
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.
.. _sdkless_builds:
Building without the Zephyr SDK
===============================
The Zephyr SDK is provided for convenience and ease of use. It provides
cross-compilers for all ports supported by the Zephyr OS and does not require
any extra flags when building applications or running tests. In addition to
cross-compilers, the Zephyr SDK also provides prebuilt host tools.
It is, however, possible to build without the SDK. If you are using 3rd party
cross compilers, jump forward to `Using 3rd Party Cross Compilers`_ for
details. A "3rd party cross compiler" is a toolchain that the Zephyr build
system already knows about, such as `GNU ARM Embedded`_ that we use in this
document.
If you are going to use custom compilers, check `Using Custom Cross Compilers`_
for more detail. A "custom compiler" would be the one your Linux distribution
packaged, the one you compiled on your own, or the one you downloaded from the
net. The Zephyr build system doesn't know about them and doesn't officially
support them.
As already noted above, the SDK also includes prebuilt host tools. To use the
SDK's prebuilt host tools alongside a 3rd party or custom cross-compiler, keep
the ZEPHYR_SDK_INSTALL_DIR environment variable set to the Zephyr SDK
installation directory. To build without the Zephyr SDK's prebuilt host tools,
the ZEPHYR_SDK_INSTALL_DIR environment variable must be unset
Follow the steps below to build without the Zephyr SDK:
.. code-block:: console
# On Linux/macOS
unset ZEPHYR_SDK_INSTALL_DIR
cd <zephyr git clone location>
source zephyr-env.sh
# On Windows
set ZEPHYR_SDK_INSTALL_DIR=
cd <zephyr git clone location>
zephyr-env.cmd
.. _third_party_x_compilers:
Using 3rd Party Cross Compilers
===============================
To use a 3rd party cross compiler that is not provided by the Zephyr
SDK, follow the steps below.
#. We will use the `GNU ARM Embedded`_ compiler for this example, download the
package suitable for your operating system from the `GNU ARM Embedded`_ website
and extract it on your file system. This example assumes the compiler was
extracted to: :file:`<user folder>/gcc-arm-none-eabi-7-2018-q2-update/`.
#. Build the example :ref:`hello_world` project, enter:
.. code-block:: console
# On Linux/macOS
export GNUARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-7-2018-q2-update/"
export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
# On Windows
set GNUARMEMB_TOOLCHAIN_PATH="%userprofile%\gcc-arm-none-eabi-7-2018-q2-update\"
set ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: arduino_due
:goals: build
Make sure to unset the ZEPHYR_SDK_INSTALL_DIR if you don't use the
SDK's host tools. See `Building without the Zephyr SDK`_ for details.
It is possible to use the Zephyr SDK's host tools along with a 3rd
party cross compiler. To do that, keep the ZEPHYR_SDK_INSTALL_DIR
environment variable set to the Zephyr SDK installation directory.
See `Set Up the Development Environment`_ for more details on the
ZEPHYR_SDK_INSTALL_DIR environment variable.
Using Custom Cross Compilers
============================
To use a custom cross compiler, follow the steps below.
#. Install a cross compiler suitable for your system. We will use the
gcc-arm-none-eabi compiler on Debian system for this example.
.. code-block:: console
# On Debian or Ubuntu
sudo apt-get install gcc-arm-none-eabi
# On Fedora or Red hat
sudo dnf install arm-none-eabi-newlib
#. Build the example :ref:`hello_world` project, enter:
.. code-block:: console
# On Linux
unset GNUARMEMB_TOOLCHAIN_PATH
export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
export CROSS_COMPILE=/usr/bin/arm-none-eabi-
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: arduino_zero
:goals: build
Note that the Zephyr build system assumes that all the tools within your
toolchain used to compile and link your code, reside in the same directory and
have a common prefix. Set the ``CROSS_COMPILE`` environment variable to the
path of your toolchain's location and that common prefix. In the example above,
gcc-arm-none-eabi is installed in ``/usr/bin/`` with the common prefix of
``arm-none-eabi-``. If your toolchain is at ``/opt/mytoolchain/bin`` with the
prefix of ``myarch-none-elf-``, it would be
``CROSS_COMPILE=/opt/mytoolchain/bin/arch-none-elf-``.
Make sure to unset the ZEPHYR_SDK_INSTALL_DIR if you don't use the SDK's host
tools. See `Building without the Zephyr SDK`_ and `Set Up the Development
Environment`_ for more details.
Using Custom Cmake Toolchains
=============================
To use a custom toolchain defined in an external cmake file, export the
following environment variables:
.. code-block:: console
export ZEPHYR_TOOLCHAIN_VARIANT=<toolchain name>
export TOOLCHAIN_ROOT=<path to toolchain>
or set them as cmake variables:
.. code-block:: console
cmake -DZEPHYR_TOOLCHAIN_VARIANT=... -DTOOLCHAIN_ROOT=...
Zephyr will then include the toolchain cmake file located in:
``<path to toolchain>/cmake/toolchain/<toolchain name>.cmake``
Running a Sample Application in QEMU
====================================
To perform rapid testing of an application in the development environment you
can use the QEMU emulation board configuration available for both X86 and ARM
Cortex-M3 architectures. This can be easily accomplished by calling a special
target when building an application that invokes QEMU once the build process is
completed.
To run an application using the x86 emulation board configuration (qemu_x86),
type:
To build and run Hello World using the x86 emulation board configuration
(``qemu_x86``), type:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
@ -301,24 +230,22 @@ type:
:board: qemu_x86
:goals: build run
To exit the qemu emulator, press ``Ctrl-a``, followed by ``x``.
To exit, type :kbd:`Ctrl-a`, then :kbd:`x`.
Use the ``qemu_cortex_m3`` board configuration to test the ARM build.
QEMU is not supported on all boards and SoCs. When developing for a specific
hardware target you should always test on the actual hardware and should not
rely on testing in the QEMU emulation environment only.
Use the ``qemu_cortex_m3`` board configuration to run on an emulated Arm
Cortex-M3.
Running a Sample Application natively (POSIX OS)
================================================
It is also possible to compile some of the sample and test applications to run
as native process on a POSIX OS (e.g. Linux).
To be able to do this, remember to have installed the 32 bit libC if your OS is
natively 64bit. See the :ref:`native_posix` section on host dependencies
for more information.
Finally, it is also possible to compile some samples to run as native processes
on a POSIX OS. This is currently only tested on Linux hosts.
To compile and run an application in this way, type:
On 64 bit host operating systems, you will also need a 32 bit C library
installed. See the :ref:`native_posix` section on host dependencies for more
information.
To compile and run Hello World in this way, type:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
@ -339,9 +266,38 @@ and then:
You can run ``zephyr/zephyr.exe --help`` to get a list of available
options. See the :ref:`native_posix` document for more information.
This executable can be instrumented like any other Linux process. For ex. with gdb
or valgrind.
Note that the native port is currently only tested in Linux.
This executable can be instrumented using standard tools, such as gdb or
valgrind.
.. rubric:: Footnotes
.. [#homebrew_user]
For details, see
https://docs.brew.sh/Homebrew-and-Python#note-on-pip-install---user.
.. [#tools_native_posix]
Usually, the toolchain is a cross-compiler and related tools which are
different than the host compilers and other programs available for
developing software to run natively on your operating system.
One exception is when building Zephyr as a host binary to run on a POSIX
operating system. In this case, you still need to set up a toolchain, but it
will provide host compilers instead of cross compilers. For details on this
option, see :ref:`native_posix`.
.. [#board_misnomer]
This has become something of a misnomer over time. While the target can be,
and often is, a microprocessor running on its own dedicated hardware
board, Zephyr also supports using QEMU to run targets built for other
architectures in emulation, targets which produce native host system
binaries that implement Zephyr's driver interfaces with POSIX APIs, and even
running different Zephyr-based binaries on CPU cores of differing
architectures on the same physical chip. Each of these hardware
configurations is called a "board," even though that doesn't always make
perfect sense in context.
.. _GNU ARM Embedded: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm
.. _CMake: https://cmake.org
.. _generators: https://cmake.org/cmake/help/v3.8/manual/cmake-generators.7.html

138
doc/getting_started/installation_linux.rst
View file

@ -3,32 +3,28 @@
Development Environment Setup on Linux
######################################
This section describes how to set up a Linux development system.
.. important::
After completing these steps, you will be able to compile and run your Zephyr
applications on the following Linux distributions:
This section only describes OS-specific setup instructions; it is the first step in the
complete Zephyr :ref:`getting_started`.
* Ubuntu 16.04 LTS 64-bit
* Fedora 25 64-bit
This section describes how to set up a Zephyr development environment on the
following Linux distributions:
* Ubuntu 16.04 LTS or 18.04 LTS 64-bit
* Fedora 28 64-bit
* Clear Linux
* Arch Linux (install `zephyr-sdk <https://aur.archlinux.org/packages/zephyr-sdk>`_ package from AUR)
* Arch Linux
Where needed, alternative instructions are listed for specific Linux
Where needed, instructions are given which only apply to specific Linux
distributions.
Installing the Host's Operating System
**************************************
Building the project's software components including the kernel has been
tested on Ubuntu and Fedora systems. Instructions for installing these OSes
are beyond the scope of this document.
Update Your Operating System
****************************
Before proceeding with the build, ensure your OS is up to date. On Ubuntu,
you'll first need to update the local database list of available packages
before upgrading:
Ensure your host system is up to date before proceeding.
On Ubuntu:
.. code-block:: console
@ -42,7 +38,7 @@ On Fedora:
sudo dnf upgrade
Note that having a newer version available for an installed package
(and reported by ``dnf check-update``) does not imply a subsequent
(as reported by ``dnf check-update``) does not imply a subsequent
``dnf upgrade`` will install it, because it must also ensure dependencies
and other restrictions are satisfied.
@ -52,43 +48,56 @@ On Clear Linux:
sudo swupd update
Installing Requirements and Dependencies
****************************************
On Arch Linux:
Install the following required packages using either apt-get or dnf.
.. code-block:: console
On Ubuntu host system:
sudo pacman -Syu
Install Requirements and Dependencies
*************************************
.. NOTE FOR DOCS AUTHORS: DO NOT PUT DOCUMENTATION BUILD DEPENDENCIES HERE.
This section is for dependencies to build Zephyr binaries, *NOT* this
documentation. If you need to add a dependency only required for building
the docs, add it to doc/README.rst. (This change was made following the
introduction of LaTeX->PDF support for the docs, as the texlive footprint is
massive and not needed by users not building PDF documentation.)
Install the following packages using your system's package manager. Note that
both Ninja and Make are installed; you may prefer only to install one.
On Ubuntu:
.. code-block:: console
sudo apt-get install --no-install-recommends git cmake ninja-build gperf \
ccache doxygen dfu-util device-tree-compiler \
python3-ply python3-pip python3-setuptools python3-wheel xz-utils file \
make gcc-multilib autoconf automake libtool librsvg2-bin \
texlive-latex-base texlive-latex-extra latexmk texlive-fonts-recommended
ccache dfu-util device-tree-compiler wget \
python3-pip python3-setuptools python3-wheel xz-utils file make
On Fedora host system:
On Fedora:
.. code-block:: console
sudo dnf group install "Development Tools" "C Development Tools and Libraries"
sudo dnf install git cmake ninja-build gperf ccache\
doxygen dfu-util dtc python3-pip \
python3-ply python3-yaml dfu-util dtc python3-pykwalify \
glibc-devel.i686 libstdc++-devel.i686 autoconf automake libtool \
texlive-latex latexmk texlive-collection-fontsrecommended librsvg2-tools
On Clear Linux host system:
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 xz file glibc-devel.i686 libstdc++-devel.i686
On Clear Linux:
.. code-block:: console
sudo swupd bundle-add c-basic dev-utils dfu-util dtc \
os-core-dev python-basic python3-basic texlive
os-core-dev python-basic python3-basic
Install additional packages required for development with Zephyr::
On Arch:
cd ~/zephyr # or to your directory where zephyr is cloned
pip3 install --user -r scripts/requirements.txt
.. code-block:: console
sudo pacman -S git cmake ninja gperf ccache dfu-util dtc wget \
python-pip python-setuptools python-wheel xz file make
CMake version 3.8.2 or higher is required. Check what version you have using
``cmake --version``; if you have an older version, check the backports or
@ -99,25 +108,30 @@ install a more recent version manually. For example, to install version
wget https://cmake.org/files/v3.8/cmake-3.8.2-Linux-x86_64.sh
yes | sh cmake-3.8.2-Linux-x86_64.sh | cat
echo "export PATH=$PWD/cmake-3.8.2-Linux-x86_64/bin:\$PATH" >> $HOME/.zephyrrc
source <zephyr git clone location>/zephyr-env.sh
cmake --version
.. _zephyr_sdk:
Installing the Zephyr Software Development Kit
==============================================
Install the Zephyr Software Development Kit (SDK)
*************************************************
.. note::
Use of the Zephyr SDK is optional, but recommended. Some of the requirements
and dependencies in the previous section are only needed for installing the
SDK.
Zephyr's :abbr:`SDK (Software Development Kit)` contains all necessary tools
and cross-compilers needed to build the kernel on all supported
and cross-compilers needed to build Zephyr on all supported
architectures. Additionally, it includes host tools such as custom QEMU binaries
and a host compiler for building host tools if necessary. The SDK supports the
following architectures:
following target architectures:
* :abbr:`X86 (Intel Architecture 32 bits)`
* :abbr:`X86 IAMCU ABI (Intel Architecture 32 bits IAMCU ABI)`
* :abbr:`ARM (Advanced RISC Machines)`
* :abbr:`Arm (Advanced RISC Machine)`
* :abbr:`ARC (Argonaut RISC Core)`
@ -147,7 +161,7 @@ Follow these steps to install the SDK on your Linux host system.
.. important::
If this fails, make sure Zephyr's dependencies were installed
as described in `Installing Requirements and Dependencies`_.
as described in `Install Requirements and Dependencies`_.
#. Follow the installation instructions on the screen. The toolchain's
default installation location is :file:`/opt/zephyr-sdk/`, but it
@ -164,23 +178,29 @@ Follow these steps to install the SDK on your Linux host system.
export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>
To use the same toolchain in new sessions in the future, you can set the
variables in the file :file:`${HOME}/.zephyrrc`, for example:
.. _sdkless_builds:
.. code-block:: console
Building on Linux without the Zephyr SDK
****************************************
cat <<EOF > ~/.zephyrrc
export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_SDK_INSTALL_DIR=/opt/zephyr-sdk
EOF
The Zephyr SDK is provided for convenience and ease of use. It provides
toolchains for all Zephyr target architectures, and does not require any extra
flags when building applications or running tests. In addition to
cross-compilers, the Zephyr SDK also provides prebuilt host tools. It is,
however, possible to build without the SDK's toolchain by using another
toolchain as as described in the main :ref:`getting_started` document.
.. note::
Use ``<sdk installation directory>`` in place of ``/opt/zephyr-sdk/`` in the
above shown example if the SDK installation location is not default.
As already noted above, the SDK also includes prebuilt host tools. To use the
SDK's prebuilt host tools with a toolchain from another source, keep the
:envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variable set to the Zephyr SDK
installation directory. To build without the Zephyr SDK's prebuilt host tools,
the :envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variable must be unset before
you run ``source zephyr-env.sh`` later on in the Getting Started Guide.
To make sure this variable is unset, run:
.. note:: In previous releases of Zephyr, the ``ZEPHYR_TOOLCHAIN_VARIANT``
variable was called ``ZEPHYR_GCC_VARIANT``.
.. code-block:: console
.. _Zephyr Downloads:
https://www.zephyrproject.org/developers/#downloads
unset ZEPHYR_SDK_INSTALL_DIR
.. _Zephyr Downloads: https://www.zephyrproject.org/developers/#downloads

161
doc/getting_started/installation_mac.rst
View file

@ -3,145 +3,54 @@
Development Environment Setup on macOS
######################################
This section describes how to set up a macOS development system.
.. important::
After completing these steps, you will be able to compile and run your Zephyr
applications on the following macOS version:
This section only describes OS-specific setup instructions; it is the first step in the
complete Zephyr :ref:`getting_started`.
This section describes how to set up a Zephyr development environment on macOS.
These instructions have been tested on the following macOS versions:
* Mac OS X 10.11 (El Capitan)
* macOS Sierra 10.12
Developing for Zephyr on macOS generally requires you to build the
toolchain yourself. However, if there is already an macOS toolchain for your
target architecture you can use it directly.
Using a 3rd Party toolchain
***************************
If a toolchain is available for the architecture you plan to build for, then
you can use it as explained in: :ref:`third_party_x_compilers`.
An example of an available 3rd party toolchain is GCC ARM Embedded for the
Cortex-M family of cores.
.. _mac_requirements:
Installing Requirements and Dependencies
****************************************
To install the software components required to build the Zephyr kernel on a
Mac, you will need to build a cross compiler for the target devices you wish to
build for and install tools that the build system requires.
.. note::
Minor version updates of the listed required packages might also
work.
Update Your Operating System
****************************
Before proceeding with the build, ensure your OS is up to date.
First, install the :program:`Homebrew` (The missing package manager for
macOS). Homebrew is a free and open-source software package management system
that simplifies the installation of software on Apple's macOS operating
system.
.. _mac_requirements:
To install :program:`Homebrew`, visit the `Homebrew site`_ and follow the
installation instructions on the site.
Install Requirements and Dependencies
*************************************
To complete the Homebrew installation, you might be prompted to install some
missing dependency. If so, follow please follow the instructions provided.
.. NOTE FOR DOCS AUTHORS: DO NOT PUT DOCUMENTATION BUILD DEPENDENCIES HERE.
This section is for dependencies to build Zephyr binaries, *NOT* this
documentation. If you need to add a dependency only required for building
the docs, add it to doc/README.rst. (This change was made following the
introduction of LaTeX->PDF support for the docs, as the texlive footprint is
massive and not needed by users not building PDF documentation.)
.. note::
Zephyr requires Python 3, while macOS only provides a Python 2
installation. After following these instructions, the version of Python 2
provided by macOS in ``/usr/bin/`` will sit alongside the Python 3
installation from Homebrew in ``/usr/local/bin``.
First, install :program:`Homebrew` by following instructions on the `Homebrew
site`_. Homebrew is a free and open-source package management system that
simplifies the installation of software on macOS. While installing Homebrew,
you may be prompted to install additional missing dependencies; please follow
any such instructions as well.
After Homebrew is successfully installed, install the following tools using
the brew command line.
.. note::
Zephyr requires Python 3 in order to be built. Since macOS comes bundled
only with Python 2, we will need to install Python 3 with Homebrew. After
installing it you should have the macOS-bundled Python 2 in ``/usr/bin/``
and the Homebrew-provided Python 3 in ``/usr/local/bin``.
Install tools to build Zephyr binaries:
the ``brew`` command line tool in the Terminal application.
.. code-block:: console
brew install cmake ninja dfu-util doxygen qemu dtc python3 gperf
cd ~/zephyr # or to the folder where you cloned the zephyr repo
pip3 install --user -r scripts/requirements.txt
.. note::
If ``pip3`` does not seem to have been installed correctly use
``brew reinstall python3`` in order to reinstall it.
Source :file:`zephyr-env.sh` wherever you have cloned the Zephyr Git repository:
.. code-block:: console
unset ZEPHYR_SDK_INSTALL_DIR
cd <zephyr git clone location>
source zephyr-env.sh
Finally, assuming you are using a 3rd-party toolchain you can try building the :ref:`hello_world` sample to check things out.
To build for the ARM-based Nordic nRF52 Development Kit:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: nrf52_pca10040
:host-os: unix
:goals: build
Install tools to build Zephyr documentation:
.. code-block:: console
brew install mactex librsvg
tlmgr install latexmk
tlmgr install collection-fontsrecommended
.. _setting_up_mac_toolchain:
Setting Up the Toolchain
************************
In case a toolchain is not available for the board you are using, you can build
a toolchain from scratch using crosstool-NG. Follow the steps on the
crosstool-NG website to `prepare your host
<http://crosstool-ng.github.io/docs/os-setup/>`_
Follow the `Zephyr SDK with Crosstool NG instructions <https://github.com/zephyrproject-rtos/sdk-ng/blob/master/README.md>`_ to build
the toolchain for various architectures. You will need to clone the ``sdk-ng``
repo and run the following command::
./go.sh <arch>
.. note::
Currently only i586 and arm builds are verified.
Repeat the step for all architectures you want to support in your environment.
To use the toolchain with Zephyr, export the following environment variables
and use the target location where the toolchain was installed, type:
.. code-block:: console
export ZEPHYR_TOOLCHAIN_VARIANT=xtools
export XTOOLS_TOOLCHAIN_PATH=/Volumes/CrossToolNGNew/build/output/
To use the same toolchain in new sessions in the future you can set the
variables in the file :file:`${HOME}/.zephyrrc`, for example:
.. code-block:: console
cat <<EOF > ~/.zephyrrc
export XTOOLS_TOOLCHAIN_PATH=/Volumes/CrossToolNGNew/build/output/
export ZEPHYR_TOOLCHAIN_VARIANT=xtools
EOF
.. note:: In previous releases of Zephyr, the ``ZEPHYR_TOOLCHAIN_VARIANT``
variable was called ``ZEPHYR_GCC_VARIANT``.
.. _Homebrew site: http://brew.sh/
.. _crosstool-ng site: http://crosstool-ng.org
brew install cmake ninja gperf ccache dfu-util qemu dtc python3
.. _Homebrew site: https://brew.sh/

315
doc/getting_started/installation_win.rst
View file

@ -3,7 +3,12 @@
Development Environment Setup on Windows
########################################
This section describes how to configure your development environment and
.. important::
This section only describes OS-specific setup instructions; it is the first step in the
complete Zephyr :ref:`getting_started`.
This section describes how to configure your development environment
to build Zephyr applications in a Microsoft Windows environment.
This guide was tested by building the Zephyr :ref:`hello_world` sample
@ -17,29 +22,49 @@ Windows system with the latest updates installed.
.. _windows_requirements:
Installing Requirements and Dependencies
****************************************
Install Requirements and Dependencies
*************************************
There are 3 different ways of developing for Zephyr on Microsoft Windows.
The first one is fully Windows native, whereas the 2 additional ones require
emulation layers that slow down build times and are not as optimal. All of
them are presented here for completeness, but unless you have a particular
requirement for a UNIX tool that is not available on Windows, we strongly
recommend you use the Windows Command Prompt for performance and minimal
dependency set.
.. NOTE FOR DOCS AUTHORS: DO NOT PUT DOCUMENTATION BUILD DEPENDENCIES HERE.
This section is for dependencies to build Zephyr binaries, *NOT* this
documentation. If you need to add a dependency only required for building
the docs, add it to doc/README.rst. (This change was made following the
introduction of LaTeX->PDF support for the docs, as the texlive footprint is
massive and not needed by users not building PDF documentation.)
There are 3 different ways of developing for Zephyr on Microsoft Windows:
#. :ref:`windows_install_native`
#. :ref:`windows_install_wsl`
#. :ref:`windows_install_msys2`
The first option is fully Windows native; the rest require emulation layers
that may result in slower build times. All three are included for completeness,
but unless you have a particular requirement for a UNIX tool that is not
available on Windows, we strongly recommend you use the Windows Command Prompt
option for performance and minimal dependency set. If you have a Unix tool
requirement, then we recommend trying the Windows Subsystem for Linux instead of
MSYS2.
.. _windows_install_native:
Option 1: Windows Command Prompt
===================================================
================================
The easiest way to install the dependencies natively on Microsoft Windows is
to use the :program:`Chocolatey` package manager (`Chocolatey website`_).
If you prefer to install those manually then simply download the required
packages from their respective websites.
These instructions assume you are using the ``cmd.exe`` command prompt. Some of
the details, such as setting environment variables, may differ if you are using
PowerShell.
The easiest way to install the 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.
.. note::
There are multiple ``set`` statements in this tutorial. You can avoid
typing them every time by placing them inside a ``.cmd`` file and
running that every time you open a Command Prompt.
running that every time you open a command prompt.
#. If you're behind a corporate firewall, you'll likely need to specify a
proxy to get access to internet resources:
@ -50,12 +75,14 @@ packages from their respective websites.
set HTTPS_PROXY=http://user:password@proxy.mycompany.com:1234
#. Install :program:`Chocolatey` by following the instructions on the
`Chocolatey install`_ website.
`Chocolatey install`_ page.
#. Open a Command Prompt (`cmd.exe`) as an **Administrator**.
#. 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").
#. Optionally disable global confirmation to avoid having to add `-y` to all
commands:
#. Optionally disable global confirmation to avoid having to confirm
installation of individual programs:
.. code-block:: console
@ -71,119 +98,40 @@ packages from their respective websites.
.. code-block:: console
choco install git python ninja dtc-msys2 gperf doxygen.install
choco install git python ninja dtc-msys2 gperf
#. **Optionally** install the tools required to build the documentation in .pdf
format:
#. Close the Administrator command prompt window.
.. code-block:: console
.. NOTE FOR DOCS AUTHORS: as a reminder, do *NOT* put dependencies for building
the documentation itself here.
choco install strawberryperl miktex rsvg-convert
.. _windows_install_wsl:
#. Close the Command Prompt window.
Option 2: Windows 10 WSL (Windows Subsystem for Linux)
======================================================
#. Open a Command Prompt (`cmd.exe`) as a **regular user**.
If you are running a recent version of Windows 10 you can make use of the
built-in functionality to natively run Ubuntu binaries directly on a standard
command-prompt. This allows you to use software such as the :ref:`Zephyr SDK
<zephyr_sdk>` without setting up a virtual machine.
#. Clone a copy of the Zephyr source into your home directory using Git.
.. code-block:: console
cd %userprofile%
git clone https://github.com/zephyrproject-rtos/zephyr.git
#. Install the required Python modules:
.. code-block:: console
cd %userprofile%\zephyr
pip3 install -r scripts/requirements.txt
#. `Install the Windows Subsystem for Linux (WSL)`_.
.. note::
For the Zephyr SDK to function properly you will need Windows 10
build 15002 or greater. You can check which Windows 10 build you are
running in the "About your PC" section of the System Settings.
If you are running an older Windows 10 build you might need to install
the Creator's Update.
Although pip can install packages in the user's directory by means
of the ``--user`` flag, this makes it harder for the Command Prompt
to find the executables in Python modules installed by ``pip3``.
#. Follow the Ubuntu instructions in the :ref:`installation_linux` document.
#. The build system should now be ready to work with any toolchain installed in
your system. In the next step you'll find instructions for installing
toolchains for building both x86 and ARM applications.
.. NOTE FOR DOCS AUTHORS: as a reminder, do *NOT* put dependencies for building
the documentation itself here.
#. Install cross compiler toolchain:
.. _windows_install_msys2:
* For x86, install the 2017 Windows host ISSM toolchain from the Intel
Developer Zone: `ISSM Toolchain`_. Use your web browser to
download the toolchain's ``tar.gz`` file. You can then use 7-Zip or a
similar tool to extract it into a destination folder.
.. note::
The ISSM toolset only supports development for Intel |reg| Quark |trade|
Microcontrollers, for example, the Arduino 101 board. (Check out the
"Zephyr Development Environment
Setup" in this `Getting Started on Arduino 101 with ISSM`_ document.)
Additional setup is required to use the ISSM GUI for development.
* For ARM, install GNU ARM Embedded from the ARM developer website:
`GNU ARM Embedded`_ (install to :file:`c:\\gnuarmemb`).
#. Within the Command Prompt, set up environment variables for the installed
tools and for the Zephyr environment:
For x86:
.. code-block:: console
set ZEPHYR_TOOLCHAIN_VARIANT=issm
set ISSM_INSTALLATION_PATH=c:\issm0-toolchain-windows-2017-01-25
Use the path where you extracted the ISSM toolchain.
For ARM:
.. code-block:: console
set ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
set GNUARMEMB_TOOLCHAIN_PATH=c:\gnuarmemb
To use the same toolchain in new sessions in the future you can set the
variables in the file :file:`%userprofile%\\zephyrrc.cmd`.
And for either, run the :file:`zephyr-env.cmd` file in order to set the
:makevar:`ZEPHYR_BASE` environment variable:
.. code-block:: console
zephyr-env.cmd
.. note:: In previous releases of Zephyr, the ``ZEPHYR_TOOLCHAIN_VARIANT``
variable was called ``ZEPHYR_GCC_VARIANT``.
#. Finally, you can try building the :ref:`hello_world` sample to check things
out.
To build for the Intel |reg| Quark |trade| (x86-based) Arduino 101:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:host-os: win
:generator: ninja
:board: arduino_101
:goals: build
To build for the ARM-based Nordic nRF52 Development Kit:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:host-os: win
:generator: ninja
:board: nrf52_pca10040
:goals: build
This should check that all the tools and toolchain are set up correctly for
your own Zephyr development.
Option 2: MSYS2
Option 3: MSYS2
===============
Alternatively, one can set up the Zephyr development environment with
@ -228,7 +176,7 @@ to set it up:
.. code-block:: console
pacman -Syu
pacman -S git cmake make gcc dtc diffutils ncurses-devel python3 gperf
pacman -S git cmake make gcc dtc diffutils ncurses-devel python3 gperf tar
#. Compile :program:`Ninja` from source (Ninja is not available as
an MSYS2 package) and install it:
@ -240,130 +188,29 @@ to set it up:
./configure.py --bootstrap
cp ninja.exe /usr/bin/
#. From within the MSYS2 MSYS Shell, clone a copy of the Zephyr source
into your home directory using Git. (Some Zephyr tools require
Unix-style line endings, so we'll configure Git for this repo to
not do the automatic Unix/Windows line ending conversion (using
``--config core.autocrlf=false``).
.. code-block:: console
cd ~
git clone --config core.autocrlf=false https://github.com/zephyrproject-rtos/zephyr.git
#. Install pip and the required Python modules::
curl -O 'https://bootstrap.pypa.io/get-pip.py'
./get-pip.py
rm get-pip.py
cd ~/zephyr # or to the folder where you cloned the zephyr repo
pip install --user -r scripts/requirements.txt
#. The build system should now be ready to work with any toolchain installed in
your system. In the next step you'll find instructions for installing
toolchains for building both x86 and ARM applications.
You're now almost ready to continue with the rest of the getting started guide.
#. Install cross compiler toolchain:
* For x86, install the 2017 Windows host ISSM toolchain from the Intel
Developer Zone: `ISSM Toolchain`_. Use your web browser to
download the toolchain's ``tar.gz`` file.
You'll need the tar application to unpack this file. In an ``MSYS2 MSYS``
console, install ``tar`` and use it to extract the toolchain archive::
pacman -S tar
tar -zxvf /c/Users/myusername/Downloads/issm-toolchain-windows-2017-01-15.tar.gz -C /c
substituting the .tar.gz path name with the one you downloaded.
.. note::
The ISSM toolset only supports development for Intel |reg| Quark |trade|
Microcontrollers, for example, the Arduino 101 board. (Check out the
"Zephyr Development Environment
Setup" in this `Getting Started on Arduino 101 with ISSM`_ document.)
Additional setup is required to use the ISSM GUI for development.
* For ARM, install GNU ARM Embedded from the ARM developer website:
`GNU ARM Embedded`_ (install to :file:`c:\\gnuarmemb`).
#. Within the MSYS console, set up environment variables for the installed
tools and for the Zephyr environment (using the provided shell script):
For x86:
Since you're using MSYS2, when you're cloning Zephyr in the next step of the
guide, use this command line instead (i.e. add the ``--config
core.autocrlf=false`` option).
.. code-block:: console
export ZEPHYR_TOOLCHAIN_VARIANT=issm
export ISSM_INSTALLATION_PATH=/c/issm0-toolchain-windows-2017-01-25
git clone --config core.autocrlf=false https://github.com/zephyrproject-rtos/zephyr
Use the path where you extracted the ISSM toolchain.
Furthermore, when you start installing Python dependencies, you'll want to add
the ``--user`` option as is recommended on Linux.
For ARM:
.. NOTE FOR DOCS AUTHORS: as a reminder, do *NOT* put dependencies for building
the documentation itself here.
.. code-block:: console
export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
export GNUARMEMB_TOOLCHAIN_PATH=/c/gnuarmemb
And for either, run the provided script to set up zephyr project specific
variables:
.. code-block:: console
unset ZEPHYR_SDK_INSTALL_DIR
cd <zephyr git clone location>
source zephyr-env.sh
#. Finally, you can try building the :ref:`hello_world` sample to check things
out.
To build for the Intel |reg| Quark |trade| (x86-based) Arduino 101:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: arduino_101
:host-os: win
:goals: build
To build for the ARM-based Nordic nRF52 Development Kit:
.. zephyr-app-commands::
:zephyr-app: samples/hello_world
:board: nrf52_pca10040
:host-os: win
:goals: build
This should check that all the tools and toolchain are set up correctly for
your own Zephyr development.
Option 3: Windows 10 WSL (Windows Subsystem for Linux)
======================================================
If you are running a recent version of Windows 10 you can make use of the
built-in functionality to natively run Ubuntu binaries directly on a standard
command-prompt. This allows you to install the standard Zephyr SDK and build
for all supported architectures without the need for a Virtual Machine.
#. Install Windows Subsystem for Linux (WSL) following the instructions on the
official Microsoft website: `WSL Installation`_
.. note::
For the Zephyr SDK to function properly you will need Windows 10
build 15002 or greater. You can check which Windows 10 build you are
running in the "About your PC" section of the System Settings.
If you are running an older Windows 10 build you might need to install
the Creator's Update.
#. Follow the instructions for Ubuntu detailed in the Zephyr Linux Getting
Started Guide which can be found here: :ref:`installation_linux`
.. _GNU ARM Embedded: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads
.. _Chocolatey website: https://chocolatey.org/
.. _Chocolatey: https://chocolatey.org/
.. _Chocolatey install: https://chocolatey.org/install
.. _MSYS2 website: http://www.msys2.org/
.. _ISSM Toolchain: https://software.intel.com/en-us/articles/issm-toolchain-only-download
.. _Getting Started on Arduino 101 with ISSM: https://software.intel.com/en-us/articles/getting-started-arduino-101genuino-101-with-intel-system-studio-for-microcontrollers
.. _WSL Installation: https://msdn.microsoft.com/en-us/commandline/wsl/install_guide
.. _Install the Windows Subsystem for Linux (WSL): https://msdn.microsoft.com/en-us/commandline/wsl/install_guide

120
doc/getting_started/toolchain_3rd_party_x_compilers.rst Normal file
View file

@ -0,0 +1,120 @@
.. _third_party_x_compilers:
3rd Party Toolchains
####################
A "3rd party toolchain" is an officially supported toolchain provided by an
external organization. Several of these are available.
GNU ARM Embedded
****************
#. Download and install a `GNU ARM Embedded`_ build for your operating system
and extract it on your file system.
.. warning::
Like the Zephyr repository, do not install the toolchain in a directory
with spaces anywhere in the path. On Windows, we'll assume you install
into the directory :file:`C:\\gnu_arm_embedded`.
#. Configure the environment variables needed to inform the Zephyr build system
to use this toolchain:
- Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``gnuarmemb``.
- Set :envvar:`GNUARMEMB_TOOLCHAIN_PATH` to the toolchain installation
directory.
For example:
.. code-block:: console
# Linux or macOS
export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
export GNUARMEMB_TOOLCHAIN_PATH="~/gnu_arm_embedded"
# Windows in cmd.exe
set ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
set GNUARMEMB_TOOLCHAIN_PATH="C:\gnu_arm_embedded"
Intel ISSM
**********
.. note::
The ISSM toolset only supports development for Intel |reg| Quark |trade|
Microcontrollers, for example, the Arduino 101 board. (Check out the
"Zephyr Development Environment
Setup" in this `Getting Started on Arduino 101 with ISSM`_ document.)
Additional setup is required to use the ISSM GUI for development.
#. Install the ISSM toolchain by downloading it from the Intel Developer Zone's
`ISSM Toolchain`_ downloads page, then extracting the archive somewhere on
your system.
.. warning::
Like the Zephyr repository, do not install the toolchain in a directory
with spaces anywhere in the path.
#. Configure the environment variables needed to inform the Zephyr build system
to use this toolchain:
- Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``issm``.
- Set :envvar:`ISSM_INSTALLATION_PATH` to the directory containing the
extracted files.
For example:
.. code-block:: console
# Linux
export ZEPHYR_TOOLCHAIN_VARIANT=issm
export ISSM_INSTALLATION_PATH=/home/you/Downloads/issm0-toolchain-windows-2017-02-07
# Windows in cmd.exe
set ZEPHYR_TOOLCHAIN_VARIANT=issm
set ISSM_INSTALLATION_PATH=c:\issm0-toolchain-windows-2017-01-25
.. _xtools_x_compilers:
Crosstool-NG
************
You can build toolchains from source code using crosstool-NG.
#. Follow the steps on the crosstool-NG website to `prepare your host
<http://crosstool-ng.github.io/docs/os-setup/>`_.
#. Follow the `Zephyr SDK with Crosstool NG instructions
<https://github.com/zephyrproject-rtos/sdk-ng/blob/master/README.md>`_ to
build your toolchain. Repeat as necessary to build toolchains for multiple
target architectures.
You will need to clone the ``sdk-ng`` repo and run the following command:
.. code-block:: console
./go.sh <arch>
.. note::
Currently, only i586 and Arm toolchain builds are verified.
#. Configure the environment variables needed to inform the Zephyr build system
to use this toolchain:
- Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``xtools``.
- Set :envvar:`XTOOLS_TOOLCHAIN_PATH` to the toolchain build directory.
For example:
.. code-block:: console
export ZEPHYR_TOOLCHAIN_VARIANT=xtools
export XTOOLS_TOOLCHAIN_PATH=/Volumes/CrossToolNGNew/build/output/
.. _GNU ARM Embedded: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm
.. _ISSM Toolchain: https://software.intel.com/en-us/articles/issm-toolchain-only-download
.. _Getting Started on Arduino 101 with ISSM: https://software.intel.com/en-us/articles/getting-started-arduino-101genuino-101-with-intel-system-studio-for-microcontrollers
.. _crosstool-ng site: http://crosstool-ng.org

27
doc/getting_started/toolchain_custom_cmake.rst Normal file
View file

@ -0,0 +1,27 @@
.. _custom_cmake_toolchains:
Custom CMake Toolchains
#######################
To use a custom toolchain defined in an external CMake file, export the
following environment variables:
.. code-block:: console
# Linux and macOS
export ZEPHYR_TOOLCHAIN_VARIANT=<toolchain name>
export TOOLCHAIN_ROOT=<path to toolchain>
# Windows
set ZEPHYR_TOOLCHAIN_VARIANT=<toolchain name>
set TOOLCHAIN_ROOT=<path to toolchain>
You can also set them as CMake variables when generating a build
system for a Zephyr application, like so:
.. code-block:: console
cmake -DZEPHYR_TOOLCHAIN_VARIANT=... -DTOOLCHAIN_ROOT=...
Zephyr will then include the toolchain cmake file located in:
``<path to toolchain>/cmake/toolchain/<toolchain name>.cmake``.

58
doc/getting_started/toolchain_other_x_compilers.rst Normal file
View file

@ -0,0 +1,58 @@
.. _other_x_compilers:
Other Cross Compilers
######################
This toolchain variant is borrowed from the Linux kernel build system's
mechanism of using a :envvar:`CROSS_COMPILE` environment variable to set up a
GNU-based cross toolchain.
Examples of such "other cross compilers" are cross toolchains that your Linux
distribution packaged, that you compiled on your own, or that you downloaded
from the net. Unlike toolchains specifically listed in
:ref:`third_party_x_compilers`, the Zephyr build system may not have been
tested with them, and doesn't officially support them. (Nonetheless, the
toolchain set-up mechanism itself is supported.)
Follow these steps to use one of these toolchains.
#. Install a cross compiler suitable for your host and target systems.
For example, you might install the ``gcc-arm-none-eabi`` package on
Debian-based Linux systems, or ``arm-none-eabi-newlib`` on Fedora or Red
Hat:
.. code-block:: console
# On Debian or Ubuntu
sudo apt-get install gcc-arm-none-eabi
# On Fedora or Red Hat
sudo dnf install arm-none-eabi-newlib
#. Configure the environment variables needed to inform the Zephyr build system
to use this toolchain:
- Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``cross-compile``.
- Set :envvar:`CROSS_COMPILE` to the common path prefix which your
toolchain's binaries have, e.g. the path to the directory containing the
compiler binaries plus the target triplet and trailing dash.
Continuing the above Debian or Ubuntu example:
.. code-block:: console
export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
export CROSS_COMPILE=/usr/bin/arm-none-eabi-
You can also set ``CROSS_COMPILE`` as a CMake variable, or using the Kconfig
symbol :option:`CONFIG_CROSS_COMPILE`.
When using this option, all of your toolchain binaries must reside in the same
directory and have a common file name prefix. The ``CROSS_COMPILE`` variable
is set to the directory concatenated with the file name prefix. In the Debian
example above, the ``gcc-arm-none-eabi`` package installs binaries such as
``arm-none-eabi-gcc`` and ``arm-none-eabi-ld`` in directory ``/usr/bin/``, so
the common prefix is ``/usr/bin/arm-none-eabi-`` (including the trailing dash,
``-``). If your toolchain is installed in ``/opt/mytoolchain/bin`` with binary
names based on target triplet ``myarch-none-elf``, ``CROSS_COMPILE`` would be
set to ``/opt/mytoolchain/bin/myarch-none-elf-``.