.. _getting_started: Getting Started Guide ##################### Use this guide to get started with your :ref:`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= #. 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 `. 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 qemu To run an application using the ARM qemu_cortex_m3 board configuration, type: .. code-block:: console $ make BOARD=qemu_cortex_m3 qemu 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