You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
304 lines
9.1 KiB
304 lines
9.1 KiB
.. _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 the ~/zephyr folder. |
|
|
|
.. _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 |
|
*********************************** |
|
|
|
Using the 'Hello World' sample application as a base model, the following |
|
section will describe the pieces necessary for creating a Zephyr application. |
|
|
|
The processes to build and run a Zephyr application are the same across |
|
operating systems. Nevertheless, the commands needed do differ from one OS to |
|
the next. The following sections contain the commands used in a Linux |
|
development environment. If you are using macOS please use the appropriate |
|
commands for your OS. |
|
|
|
Building a Sample Application |
|
============================= |
|
|
|
To build an example application follow these steps: |
|
|
|
|
|
#. Make sure your environment is setup by exporting the following environment |
|
variables. When using the Zephyr SDK on Linux for example, type: |
|
|
|
.. code-block:: console |
|
|
|
|
|
# On Linux/macOS |
|
export ZEPHYR_GCC_VARIANT=zephyr |
|
export ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory> |
|
# On Windows |
|
set ZEPHYR_GCC_VARIANT=zephyr |
|
set ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory> |
|
|
|
#. Navigate to the main project directory: |
|
|
|
.. code-block:: console |
|
|
|
cd zephyr |
|
|
|
#. Set the project environment variables: |
|
|
|
.. code-block:: console |
|
|
|
# On Linux/macOS |
|
source zephyr-env.sh |
|
# On Windows |
|
set ZEPHYR_BASE=%cd% |
|
|
|
#. 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. To use the SDK host tools alongside a custom or 3rd party |
|
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, the host |
|
tools must be built and added to path, and a 3rd party cross-compiler |
|
must be installed. |
|
|
|
#. Follow the steps below to build without the Zephyr SDK: |
|
|
|
.. code-block:: console |
|
|
|
# On Linux/macOS |
|
unset ZEPHYR_GCC_VARIANT |
|
unset ZEPHYR_SDK_INSTALL_DIR |
|
cd <zephyr git clone location> |
|
source zephyr-env.sh |
|
# On Windows |
|
set ZEPHYR_GCC_VARIANT= |
|
set ZEPHYR_SDK_INSTALL_DIR= |
|
cd <zephyr git clone location> |
|
set ZEPHYR_BASE=%cd% |
|
|
|
|
|
#. On UNIX platforms, Build Kconfig in :file:`$ZEPHYR_BASE/build` and add |
|
it to path |
|
|
|
.. code-block:: console |
|
|
|
cd $ZEPHYR_BASE |
|
mkdir build && cd build |
|
cmake $ZEPHYR_BASE/scripts |
|
make |
|
echo "export PATH=$PWD/kconfig:\$PATH" >> $HOME/.zephyrrc |
|
source $ZEPHYR_BASE/zephyr-env.sh |
|
|
|
.. note:: |
|
|
|
You only need to do this once after cloning the git repository. |
|
|
|
Now that the host tools are installed, a 3rd party cross compiler must |
|
be installed. See `Using Custom and 3rd Party Cross Compilers`_ for |
|
details. |
|
|
|
.. _third_party_x_compilers: |
|
|
|
Using Custom and 3rd Party Cross Compilers |
|
========================================== |
|
|
|
To use a 3rd party cross compiler that is not provided by the Zephyr |
|
SDK, follow the steps below. It is possible to use a 3rd party cross |
|
compiler and still use the Zephyr SDK's host tools. See `Building |
|
without the Zephyr SDK`_ for details. |
|
|
|
#. 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_GCC_VARIANT=gccarmemb |
|
# On Windows |
|
set GCCARMEMB_TOOLCHAIN_PATH="%userprofile%\gcc-arm-none-eabi-5_3-2016q1\" |
|
set ZEPHYR_GCC_VARIANT=gccarmemb |
|
|
|
.. zephyr-app-commands:: |
|
:zephyr-app: samples/hello_world |
|
:board: arduino_due |
|
:goals: build |
|
|
|
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. |
|
|
|
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 |
|
|
|
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 |
|
|
|
|