| .. _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 |
| |
| $ cd ~ |
| $ 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. |
| |
| 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 |
| |
| |
| .. _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 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. |
| |
| |
| .. _GCC ARM Embedded: https://launchpad.net/gcc-arm-embedded |