mirror of
https://github.com/zephyrproject-rtos/zephyr
synced 2025-09-02 09:12:44 +00:00
e09af5f008
"Getting Started" does not clearly state how to use a custom cross compiler. This patch adds a new section "Using Custom Cross Compilers" to it. To support users without SDK, we have the section "Building without the Zephyr SDK". But the section is all about prebuilt tools in the SDK but not build process. This patch adds two pointers "Using 3rd Party Cross Compilers" and "Using Custom Cross Compilers" pointing to the actual building process, and let those section describe ZEPHYR_TOOLCHAIN_VARIANT, which is cross compilers dependent variable. The patch also clarify what a 3rd party cross compiler is and what a custom compiler is. Signed-off-by: Yasushi SHOJI <y-shoji@ispace-inc.com>
328 lines
10 KiB
ReStructuredText
328 lines
10 KiB
ReStructuredText
.. _getting_started:
|
|
|
|
Getting Started Guide
|
|
#####################
|
|
|
|
Use this guide to get started with your :ref:`Zephyr <introducing_zephyr>`
|
|
development.
|
|
|
|
Checking Out the Source Code Anonymously
|
|
****************************************
|
|
|
|
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.)
|
|
|
|
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.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
installation_linux.rst
|
|
installation_mac.rst
|
|
installation_win.rst
|
|
|
|
|
|
.. _getting_started_run_sample:
|
|
|
|
Building and Running an Application
|
|
***********************************
|
|
|
|
Next, build a sample Zephyr application. You can then run it either in
|
|
emulation or using POSIX APIs available on your host.
|
|
|
|
If your board is supported by Zephyr (see :ref:`boards` for a list),
|
|
consult its documentation for flashing and running instructions.
|
|
|
|
Building a Sample Application
|
|
=============================
|
|
|
|
Follow these steps to build the :ref:`hello_world` sample application
|
|
provided with Zephyr.
|
|
|
|
#. Navigate to the main project directory:
|
|
|
|
.. code-block:: console
|
|
|
|
cd zephyr
|
|
|
|
#. Set up your build environment:
|
|
|
|
.. code-block:: console
|
|
|
|
# On Linux/macOS
|
|
source zephyr-env.sh
|
|
# On Windows
|
|
zephyr-env.cmd
|
|
|
|
#. Build the :ref:`hello_world` example for the `arduino_101` board, enter:
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-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
|
|
: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:
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/hello_world
|
|
:board: arduino_due
|
|
:build-dir: arduino_due
|
|
:goals: build
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
ninja usage
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
.. _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 `GCC 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 `GCC ARM Embedded`_ compiler for this example, download the
|
|
package suitable for your operating system from the `GCC 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-5_3-2016q1/`.
|
|
|
|
#. Build the example :ref:`hello_world` project, enter:
|
|
|
|
.. code-block:: console
|
|
|
|
# On Linux/macOS
|
|
export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
|
|
export ZEPHYR_TOOLCHAIN_VARIANT=gccarmemb
|
|
# On Windows
|
|
set GCCARMEMB_TOOLCHAIN_PATH="%userprofile%\gcc-arm-none-eabi-5_3-2016q1\"
|
|
set ZEPHYR_TOOLCHAIN_VARIANT=gccarmemb
|
|
|
|
.. 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 GCCARMEMB_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.
|
|
|
|
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:
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/hello_world
|
|
:host-os: unix
|
|
:board: qemu_x86
|
|
:goals: build run
|
|
|
|
To exit the qemu emulator, press ``Ctrl-a``, followed by ``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.
|
|
|
|
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.
|
|
|
|
To compile and run an application in this way, type:
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/hello_world
|
|
:host-os: unix
|
|
:board: native_posix
|
|
:goals: build
|
|
|
|
and then:
|
|
|
|
.. code-block:: console
|
|
|
|
ninja run
|
|
|
|
# or just:
|
|
zephyr/zephyr.exe
|
|
# Press Ctrl+C to exit
|
|
|
|
You can run ``zephyr/zephyr.exe --help`` to get a list of available
|
|
options. See the :ref:`native_posix` document for more information.
|
|
|
|
This executable can be instrumented like any other Linux process. For ex. with gdb
|
|
or valgrind.
|
|
Note that the native port is currently only tested in Linux.
|
|
|
|
.. _GCC ARM Embedded: https://launchpad.net/gcc-arm-embedded
|
|
.. _CMake: https://cmake.org
|