2bc9d69981
This will replace the current goal of 'make qemu' with 'make run' and moves Qemu handling into its own file and into the boards instead of being architecture specific. We should be able to add new boards that support some other type of emulation (by adding scripts/Makefile.<emu type>) and allow the board to define their own options for the use type of emulation. 'make qemu' will still work, however it will be deprecated, starting with this commit it is recommended to use 'make run'. Jira: ZEP-359 Change-Id: I1cacd56b4ec09421a58cf5d010e22e9035214df6 Signed-off-by: Anas Nashif <anas.nashif@intel.com>
225 lines
6.4 KiB
ReStructuredText
225 lines
6.4 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
|
|
* Mac OS
|
|
* 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 at the Linux Foundation with a Gerrit backend that supports
|
|
anonymous cloning via git.
|
|
|
|
To clone the repository anonymously, enter:
|
|
|
|
.. code-block:: console
|
|
|
|
$ git clone https://gerrit.zephyrproject.org/r/zephyr zephyr-project
|
|
|
|
You have successfully checked out a copy of the source code to your local
|
|
machine.
|
|
|
|
Once you're ready to start contributing, follow the steps to make yourself
|
|
a Linux Foundation account at `Gerrit Accounts`_.
|
|
|
|
.. _Gerrit Accounts: https://wiki.zephyrproject.org/view/Gerrit_accounts
|
|
|
|
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 Mac OS 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-project
|
|
|
|
#. Source the project environment file to set the project environtment
|
|
variables:
|
|
|
|
.. code-block:: console
|
|
|
|
$ source zephyr-env.sh
|
|
|
|
#. Build the example project, enter:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cd $ZEPHYR_BASE/samples/hello_world
|
|
|
|
$ make
|
|
|
|
The above invocation of make will build the hello_world sample application
|
|
using the default settings defined in the application's Makefile. You can
|
|
build for a different board by defining the variable BOARD with one of the
|
|
supported boards, for example:
|
|
|
|
.. code-block:: console
|
|
|
|
$ make BOARD=arduino_101
|
|
|
|
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 help
|
|
|
|
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
|
|
:file:`outdir` sub-directory under the application root directory, in a
|
|
subdirectory that matches the BOARD string.
|
|
|
|
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.
|
|
|
|
.. _third_party_x_compilers:
|
|
|
|
Using Custom and 3rd Party Cross Compilers
|
|
==========================================
|
|
|
|
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.
|
|
|
|
If you have a custom cross-compiler or if you wish to use a vendor provided SDK,
|
|
follow the steps below to build with any custom or 3rd party cross-compilers:
|
|
|
|
#. To avoid any conflicts with the Zephyr SDK, enter the following commands.
|
|
|
|
.. code-block:: console
|
|
|
|
$ unset ZEPHYR_GCC_VARIANT
|
|
|
|
$ unset ZEPHYR_SDK_INSTALL_DIR
|
|
|
|
#. 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/`.
|
|
|
|
#. Navigate to the main project directory:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cd zephyr-project
|
|
|
|
#. Source the project environment file to set the project environment
|
|
variables:
|
|
|
|
.. code-block:: console
|
|
|
|
$ source zephyr-env.sh
|
|
|
|
#. Build the example project and make sure you supply the CROSS_COMPILE on the command line, enter:
|
|
|
|
.. code-block:: console
|
|
|
|
$ export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
|
|
|
|
$ export ZEPHYR_GCC_VARIANT=gccarmemb
|
|
|
|
$ cd $ZEPHYR_BASE/samples/hello_world
|
|
|
|
$ make CROSS_COMPILE=~/gcc-arm-none-eabi-5_3-2016q1/bin/arm-none-eabi- BOARD=arduino_due
|
|
|
|
The above will build the sample using the toolchain downloaded from
|
|
`GCC ARM Embedded`_.
|
|
|
|
Alternatively, you can use the existing support for GCC ARM Embedded:
|
|
|
|
.. code-block:: console
|
|
|
|
$ export GCCARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-5_3-2016q1/"
|
|
|
|
$ export ZEPHYR_GCC_VARIANT=gccarmemb
|
|
|
|
$ cd zephyr-project
|
|
|
|
$ source zephyr-env.sh
|
|
|
|
$ cd $ZEPHYR_BASE/samples/hello_world
|
|
|
|
$ make BOARD=arduino_due
|
|
|
|
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
|
|
|
|
$ make BOARD=qemu_x86 run
|
|
|
|
To run an application using the ARM qemu_cortex_m3 board configuration, type:
|
|
|
|
.. code-block:: console
|
|
|
|
$ make BOARD=qemu_cortex_m3 run
|
|
|
|
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.
|
|
|
|
|
|
.. _Linux Foundation ID website: https://identity.linuxfoundation.org
|
|
|
|
.. _Gerrit: https://gerrit.zephyrproject.org/
|
|
|
|
.. _GCC ARM Embedded: https://launchpad.net/gcc-arm-embedded
|