.. _beyond-gsg: Beyond the Getting Started Guide ################################ The :ref:`getting_started` gives a straight-forward path to set up your Linux, macOS, or Windows environment for Zephyr development. In this document, we delve deeper into Zephyr development setup issues and alternatives. .. _python-pip: Python and pip ************** Python 3 and its package manager, pip\ [#pip]_, are used extensively by Zephyr to install and run scripts required to compile and run Zephyr applications, set up and maintain the Zephyr development environment, and build project documentation. Depending on your operating system, you may need to provide the ``--user`` flag to the ``pip3`` command when installing new packages. This is documented throughout the instructions. See `Installing Packages`_ in the Python Packaging User Guide for more information about pip\ [#pip]_, including `information on -\\-user`_. - On Linux, make sure ``~/.local/bin`` is at the front of your :envvar:`PATH` :ref:`environment variable `, or programs installed with ``--user`` won't be found. Installing with ``--user`` avoids conflicts between pip and the system package manager, and is the default on Debian-based distributions. - On macOS, `Homebrew disables -\\-user`_. - On Windows, see the `Installing Packages`_ information on ``--user`` if you require using this option. On all operating systems, pip's ``-U`` flag installs or updates the package if the package is already installed locally but a more recent version is available. It is good practice to use this flag if the latest version of a package is required. (Check the :zephyr_file:`scripts/requirements.txt` file to see if a specific Python package version is expected.) Advanced Platform Setup *********************** Here are some alternative instructions for more advanced platform setup configurations for supported development platforms: .. toctree:: :maxdepth: 1 Linux setup alternatives macOS setup alternatives Windows setup alternatives .. _gs_toolchain: Install a Toolchain ******************* Zephyr binaries are compiled and linked by a *toolchain* comprised of a cross-compiler and related tools which are different from the compiler and tools used for developing software that runs natively on your host operating system. You can install the :ref:`Zephyr SDK ` to get toolchains for all supported architectures, or install an :ref:`alternate toolchain ` recommended by the SoC vendor or a specific board (check your specific :ref:`board-level documentation `). You can configure the Zephyr build system to use a specific toolchain by setting :ref:`environment variables ` such as :envvar:`ZEPHYR_TOOLCHAIN_VARIANT <{TOOLCHAIN}_TOOLCHAIN_PATH>` to a supported value, along with additional variable(s) specific to the toolchain variant. .. _gs_toolchain_update: Updating the Zephyr SDK toolchain ********************************* When updating Zephyr SDK, check whether the :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` or :envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variables are already set. * If the variables are not set, the latest compatible version of Zephyr SDK will be selected by default. Proceed to next step without making any changes. * If :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` is set, the corresponding toolchain will be selected at build time. Zephyr SDK is identified by the value ``zephyr``. If the :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` environment variable is not ``zephyr``, then either unset it or change its value to ``zephyr`` to make sure Zephyr SDK is selected. * If the :envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variable is set, it will override the default lookup location for Zephyr SDK. If you install Zephyr SDK to one of the :ref:`recommended locations `, you can unset this variable. Otherwise, set it to your chosen install location. For more information about these environment variables in Zephyr, see :ref:`env_vars_important`. Cloning the Zephyr Repositories ******************************* The Zephyr project source is maintained in the `GitHub zephyr repo `_. External modules used by Zephyr are found in the parent `GitHub Zephyr project `_. Because of these dependencies, it's convenient to use the Zephyr-created :ref:`west ` tool to fetch and manage the Zephyr and external module source code. See :ref:`west-basics` for more details. Once your development tools are installed, use :ref:`west` to create, initialize, and download sources from the zephyr and external module repos. We'll use the name ``zephyrproject``, but you can choose any name that does not contain a space anywhere in the path. .. code-block:: console west init zephyrproject cd zephyrproject west update The ``west update`` command fetches and keeps :ref:`modules` in the :file:`zephyrproject` folder in sync with the code in the local zephyr repo. .. warning:: You must run ``west update`` any time the :file:`zephyr/west.yml` changes, caused, for example, when you pull the :file:`zephyr` repository, switch branches in it, or perform a ``git bisect`` inside of it. Keeping Zephyr updated ====================== To update the Zephyr project source code, you need to get the latest changes via ``git``. Afterwards, run ``west update`` as mentioned in the previous paragraph. .. code-block:: console # replace zephyrproject with the path you gave west init cd zephyrproject/zephyr git pull west update Export Zephyr CMake package *************************** The :ref:`cmake_pkg` can be exported to CMake's user package registry if it has not already been done as part of :ref:`getting_started`. .. _gs-board-aliases: Board Aliases ************* Developers who work with multiple boards may find explicit board names cumbersome and want to use aliases for common targets. This is supported by a CMake file with content like this: .. code-block:: cmake # Variable foo_BOARD_ALIAS=bar replaces BOARD=foo with BOARD=bar and # sets BOARD_ALIAS=foo in the CMake cache. set(pca10028_BOARD_ALIAS nrf51dk/nrf51822) set(pca10056_BOARD_ALIAS nrf52840dk/nrf52840) set(k64f_BOARD_ALIAS frdm_k64f) set(sltb004a_BOARD_ALIAS efr32mg_sltb004a) and specifying its location in :envvar:`ZEPHYR_BOARD_ALIASES`. This enables use of aliases ``pca10028`` in contexts like ``cmake -DBOARD=pca10028`` and ``west -b pca10028``. Build and Run an Application **************************** You can build, flash, and run Zephyr applications on real hardware using a supported host system. Depending on your operating system, you can also run it in emulation with QEMU, or as a native application with :ref:`native_sim `. Additional information about building applications can be found in the :ref:`build_an_application` section. Build Blinky ============ Let's build the :zephyr:code-sample:`blinky` sample application. Zephyr applications are built to run on specific hardware, called a "board"\ [#board_misnomer]_. We'll use the Phytec :ref:`reel_board ` here, but you can change the ``reel_board`` build target to another value if you have a different board. See :ref:`boards` or run ``west boards`` from anywhere inside the ``zephyrproject`` directory for a list of supported boards. #. Go to the zephyr repository: .. code-block:: console cd zephyrproject/zephyr #. Build the blinky sample for the ``reel_board``: .. zephyr-app-commands:: :zephyr-app: samples/basic/blinky :board: reel_board :goals: build The main build products will be in :file:`build/zephyr`; :file:`build/zephyr/zephyr.elf` is the blinky application binary in ELF format. Other binary formats, disassembly, and map files may be present depending on your board. The other sample applications in the :zephyr_file:`samples` folder are documented in :zephyr:code-sample-category:`samples`. .. note:: If you want to reuse an existing build directory for another board or application, you need to add the parameter ``-p=auto`` to ``west build`` to clean out settings and artifacts from the previous build. Run the Application by Flashing to a Board ========================================== Most hardware boards supported by Zephyr can be flashed by running ``west flash``. This may require board-specific tool installation and configuration to work properly. See :ref:`application_run` and your specific board's documentation in :ref:`boards` for additional details. .. _setting-udev-rules: Setting udev rules =================== Flashing a board requires permission to directly access the board hardware, usually managed by installation of the flashing tools. On Linux systems, if the ``west flash`` command fails, you likely need to define udev rules to grant the needed access permission. Udev is a device manager for the Linux kernel and the udev daemon handles all user space events raised when a hardware device is added (or removed) from the system. We can add a rules file to grant access permission by non-root users to certain USB-connected devices. The OpenOCD (On-Chip Debugger) project conveniently provides a rules file that defined board-specific rules for most Zephyr-supported arm-based boards, so we recommend installing this rules file by downloading it from their sourceforge repo, or if you've installed the Zephyr SDK there is a copy of this rules file in the SDK folder: * Either download the OpenOCD rules file and copy it to the right location:: wget -O 60-openocd.rules https://sf.net/p/openocd/code/ci/master/tree/contrib/60-openocd.rules?format=raw sudo cp 60-openocd.rules /etc/udev/rules.d * or copy the rules file from the Zephyr SDK folder:: sudo cp ${ZEPHYR_SDK_INSTALL_DIR}/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d Then, in either case, ask the udev daemon to reload these rules:: sudo udevadm control --reload Unplug and plug in the USB connection to your board, and you should have permission to access the board hardware for flashing. Check your board-specific documentation (:ref:`boards`) for further information if needed. Run the Application in QEMU =========================== On Linux and macOS, you can run Zephyr applications via emulation on your host system using `QEMU `_ when targeting either the x86 or ARM Cortex-M3 architectures. (QEMU is included with the Zephyr SDK installation.) On Windows, you need to install QEMU manually from `Download QEMU `_. After installation, add path to QEMU installation folder to PATH environment variable. To enable QEMU in Test Runner (Twister) on Windows, :ref:`set the environment variable ` ``QEMU_BIN_PATH`` to the path of QEMU installation folder. For example, you can build and run the :zephyr:code-sample:`hello_world` sample using the x86 emulation board configuration (``qemu_x86``), with: .. zephyr-app-commands:: :zephyr-app: samples/hello_world :host-os: unix :board: qemu_x86 :goals: build run To exit QEMU, type :kbd:`Ctrl-a`, then :kbd:`x`. Use ``qemu_cortex_m3`` to target an emulated Arm Cortex-M3 sample. .. _gs_native: Run a Sample Application natively (Linux) ========================================= You can compile some samples to run as host programs on Linux. See :ref:`native_sim` for more information. On 64-bit host operating systems, you need to install a 32-bit C library, or build targeting :ref:`native_sim/native/64`. First, build Hello World for ``native_sim``. .. zephyr-app-commands:: :zephyr-app: samples/hello_world :host-os: unix :board: native_sim :goals: build Next, run the application. .. code-block:: console west build -t run # or just run zephyr.exe directly: ./build/zephyr/zephyr.exe Press :kbd:`Ctrl-C` to exit. You can run ``./build/zephyr/zephyr.exe --help`` to get a list of available options. This executable can be instrumented using standard tools, such as gdb or valgrind. .. rubric:: Footnotes .. [#pip] pip is Python's package installer. Its ``install`` command first tries to reuse packages and package dependencies already installed on your computer. If that is not possible, ``pip install`` downloads them from the Python Package Index (PyPI) on the Internet. The package versions requested by Zephyr's :file:`requirements.txt` may conflict with other requirements on your system, in which case you may want to set up a virtualenv for Zephyr development. .. [#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. .. _information on -\\-user: https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site .. _Homebrew disables -\\-user: https://docs.brew.sh/Homebrew-and-Python#note-on-pip-install---user .. _Installing Packages: https://packaging.python.org/tutorials/installing-packages/