.. _getting_started: Getting Started Guide ##################### Follow this guide to set up a :ref:`Zephyr ` development environment on your system, and then build and run a sample application. .. _host_setup: Set Up a Development System *************************** Follow one of the following guides for your host operating system. .. toctree:: :maxdepth: 1 Linux macOS Windows Clone the Zephyr Repository *************************** To clone the Zephyr source code repository from GitHub: .. code-block:: console git clone https://github.com/zephyrproject-rtos/zephyr .. warning:: Don't clone Zephyr to a directory with spaces anywhere in the path. For example, on Windows, :file:`C:\\Users\\YourName\\zephyr` will work, but :file:`C:\\Users\\Your Name\\zephyr` will cause cryptic errors when you try to build an application. Install Python Dependencies *************************** Next, install additional Python packages required by Zephyr in a shell or ``cmd.exe`` prompt: .. code-block:: console # Linux pip3 install --user -r zephyr/scripts/requirements.txt # macOS and Windows pip3 install -r zephyr/scripts/requirements.txt Some notes on pip's ``--user`` option: - Installing with ``--user`` is the default behavior on Debian-based distributions and is generally recommended on Linux to avoid conflicts with Python packages installed using the system package manager. - On Linux, verify the Python user install directory ``~/.local/bin`` is at the front of your PATH environment variable, otherwise installed packages won't be found. - On macOS, Homebrew disables the ``--user`` flag\ [#homebrew_user]_. - On Windows using ``cmd.exe``, although it's possible to use the ``--user`` flag, it makes it harder for the command prompt to find executables installed by pip. Set Up a Toolchain ****************** .. note:: On Linux, you can skip this step if you installed the :ref:`Zephyr SDK `, which includes toolchains for all supported Zephyr architectures. If you want, you can use the SDK host tools (such as OpenOCD) with a different toolchain by keeping the :envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variable set to the Zephyr SDK installation directory, while setting :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` appropriately for a non-SDK toolchain. Zephyr binaries are compiled using software called a *toolchain*. You need to *install* and *configure* a toolchain to develop Zephyr applications\ [#tools_native_posix]_. Toolchains can be *installed* in different ways, including using installer programs, system package managers, or simply downloading a zip file or other archive and extracting the files somewhere on your computer. You *configure* the toolchain by setting the environment variable :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to a recognized value, along with some additional variable(s) specific to that toolchain (usually, this is just one more variable which contains the path where you installed the toolchain on your file system). .. note:: In previous releases of Zephyr, the ``ZEPHYR_TOOLCHAIN_VARIANT`` variable was called ``ZEPHYR_GCC_VARIANT``. The following toolchain installation options are available. The right choice for you depends on where you want to run Zephyr and any other requirements you may have. Check your :ref:`board-level documentation ` if you are unsure about what choice to use. .. toctree:: :maxdepth: 2 toolchain_3rd_party_x_compilers.rst toolchain_other_x_compilers.rst toolchain_custom_cmake.rst To use the same toolchain in new sessions in the future you can make sure the variables are set persistently. On macOS and Linux, you can set the variables by putting the ``export`` lines setting environment variables in a file :file:`~/.zephyrrc`. On Windows, you can put the ``set`` lines in :file:`%userprofile%\\zephyrrc.cmd`. These files are used to modify your environment when you run ``zephyr-env.sh`` (Linux, macOS) and ``zephyr-env.cmd`` (Windows), which you will learn about in the next step. .. _getting_started_run_sample: Build and Run an Application **************************** Next, build a sample Zephyr application. You can then flash and run it on real hardware using any supported host system. Depending on your operating system, you can also run it in emulation with QEMU or as a native POSIX application. .. _getting_started_cmake: A Brief Note on the Zephyr Build System ======================================= The Zephyr build system uses `CMake`_. CMake creates build systems in different formats, called `generators`_. Zephyr supports the following generators: * ``Unix Makefiles``: Supported on UNIX-like platforms (Linux, macOS). * ``Ninja``: Supported on all platforms. This documentation and Zephyr's continuous integration system mainly use ``Ninja``, but you should be able to use any supported generator to build Zephyr applications. Build the Application ===================== Follow these steps to build the :ref:`hello_world` sample application provided with Zephyr. Zephyr applications have to be configured and built to run on some hardware configuration, which is called a "board"\ [#board_misnomer]_. These steps show how to build the Hello World application for the :ref:`arduino_101` board. You can build for a different board by changing ``arduino_101`` to another supported value. See :ref:`boards` for more information, or run ``ninja usage`` from the build directory (once you've run ``cmake``) to get a list. .. note:: If you want to re-use your existing build directory to build for another board, you must delete that directory's contents first by running ``ninja pristine``. #. 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 Hello World sample for the ``arduino_101``: .. Note: we don't use :zephyr-app: here because we just told the user to cd to ZEPHYR_BASE, so it's not necessary for clarity and would clutter the instructions a bit. .. zephyr-app-commands:: :app: samples/hello_world :board: arduino_101 :goals: build On Linux/macOS you can also build with ``make`` instead of ``ninja``: .. zephyr-app-commands:: :app: samples/hello_world :generator: make :host-os: unix :board: arduino_101 :goals: build The main build products are in :file:`zephyr/samples/hello_world/build/zephyr`. The final application binary in ELF format is named :file:`zephyr.elf` by default. Other binary formats and byproducts such as disassembly and map files will be present depending on the target and build system configuration. Other sample projects demonstrating Zephyr's features are located in :file:`zephyr/samples` and are documented in :ref:`samples-and-demos`. Run the Application by Flashing to Another Board ================================================ Most "real hardware" boards supported by Zephyr can be flashed by running ``ninja flash`` from the build directory. However, this may require board-specific tool installation and configuration to work properly. See :ref:`application_run` in the Application Development Primer and the documentation provided with your board at :ref:`boards` for additional details if you get an error. Run the Application in QEMU =========================== On Linux and macOS, you can run Zephyr applications in emulation on your host system using QEMU when targeting either the X86 or ARM Cortex-M3 architectures. To build and run Hello World 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, type :kbd:`Ctrl-a`, then :kbd:`x`. Use the ``qemu_cortex_m3`` board configuration to run on an emulated Arm Cortex-M3. Running a Sample Application natively (POSIX OS) ================================================ Finally, it is also possible to compile some samples to run as native processes on a POSIX OS. This is currently only tested on Linux hosts. On 64 bit host operating systems, you will also need a 32 bit C library installed. See the :ref:`native_posix` section on host dependencies for more information. To compile and run Hello World 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 using standard tools, such as gdb or valgrind. .. rubric:: Footnotes .. [#homebrew_user] For details, see https://docs.brew.sh/Homebrew-and-Python#note-on-pip-install---user. .. [#tools_native_posix] Usually, the toolchain is a cross-compiler and related tools which are different than the host compilers and other programs available for developing software to run natively on your operating system. One exception is when building Zephyr as a host binary to run on a POSIX operating system. In this case, you still need to set up a toolchain, but it will provide host compilers instead of cross compilers. For details on this option, see :ref:`native_posix`. .. [#board_misnomer] This has become something of a misnomer over time. While the target can be, and often is, a microprocessor running on its own dedicated hardware board, Zephyr also supports using QEMU to run targets built for other architectures in emulation, targets which produce native host system binaries that implement Zephyr's driver interfaces with POSIX APIs, and even running different Zephyr-based binaries on CPU cores of differing architectures on the same physical chip. Each of these hardware configurations is called a "board," even though that doesn't always make perfect sense in context. .. _CMake: https://cmake.org .. _generators: https://cmake.org/cmake/help/v3.8/manual/cmake-generators.7.html