8d0a80c6a9
This change changes the semantics of the environment variable ZEPHYR_SDK_INSTALL_DIR to allow the use of 3rd party toolchains alongside the Zephyr SDK's host tools. Specifically, setting ZEPHYR_SDK_INSTALL_DIR now indicates that the Zephyr SDK host tools are to be used. But not necessarily that the Zephyr SDK's toolchain is to be used. The documentation is also changed to explain this behaviour. Signed-off-by: Sebastian Boe <sebastian.boe@nordicsemi.no>
222 lines
6.6 KiB
ReStructuredText
222 lines
6.6 KiB
ReStructuredText
.. _getting_started:
|
|
|
|
Getting Started Guide
|
|
#####################
|
|
|
|
Use this guide to get started with your :ref:`Zephyr <introducing_zephyr>`
|
|
development.
|
|
|
|
Set Up the Development Environment
|
|
**********************************
|
|
|
|
The Zephyr project supports these operating systems:
|
|
|
|
* Linux
|
|
* macOS
|
|
* Windows 8.1
|
|
|
|
Use the following procedures to create a new development environment.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
installation_linux.rst
|
|
installation_mac.rst
|
|
installation_win.rst
|
|
|
|
|
|
Checking Out the Source Code Anonymously
|
|
========================================
|
|
|
|
The code is hosted in a GitHub repo that supports
|
|
anonymous cloning via git.
|
|
|
|
To clone the repository anonymously, enter:
|
|
|
|
.. code-block:: console
|
|
|
|
$ git clone https://github.com/zephyrproject-rtos/zephyr.git
|
|
|
|
You have successfully checked out a copy of the source code to your local
|
|
machine.
|
|
|
|
.. _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
|
|
|
|
$ export ZEPHYR_GCC_VARIANT=zephyr
|
|
$ export ZEPHYR_SDK_INSTALL_DIR=<sdk installation directory>
|
|
|
|
#. Navigate to the main project directory:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cd zephyr
|
|
|
|
#. Source the project environment file to set the project environment
|
|
variables:
|
|
|
|
.. code-block:: console
|
|
|
|
$ source zephyr-env.sh
|
|
|
|
#. 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
|
|
|
|
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
|
|
|
|
$ make 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
|
|
|
|
$ unset ZEPHYR_GCC_VARIANT
|
|
$ unset ZEPHYR_SDK_INSTALL_DIR
|
|
$ cd <zephyr git clone location>
|
|
$ source zephyr-env.sh
|
|
|
|
#. 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 :ref:`below <third_party_x_compilers>` for
|
|
installing a cross compiler.
|
|
|
|
.. _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 :ref:`the
|
|
section above <sdkless_builds>` 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:`~/gcc-arm-none-eabi-5_3-2016q1/`.
|
|
|
|
#. Build the example :ref:`hello_world` project, enter:
|
|
|
|
.. code-block:: console
|
|
|
|
$ export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
|
|
$ export 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:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cd $ZEPHYR_BASE/samples/hello_world
|
|
$ mkdir qemu_build && cd qemu_build
|
|
$ cmake -DBOARD=qemu_x86 ..
|
|
$ make run
|
|
|
|
To run an application using the ARM qemu_cortex_m3 board configuration
|
|
specify the qemu_cortex_m3 board instead.
|
|
|
|
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.
|
|
|
|
|
|
.. _GCC ARM Embedded: https://launchpad.net/gcc-arm-embedded
|