| .. _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 `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. |
| |
| 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. |
| |
| .. _GNU ARM Embedded: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm |
| .. _CMake: https://cmake.org |