1.. _installation_linux: 2 3Install Linux Host Dependencies 4############################### 5 6Documentation is available for these Linux distributions: 7 8* Ubuntu 9* Fedora 10* Clear Linux 11* Arch Linux 12 13For distributions that are not based on rolling releases, some of the 14requirements and dependencies may not be met by your package manager. In that 15case please follow the additional instructions that are provided to find 16software from sources other than the package manager. 17 18.. note:: If you're working behind a corporate firewall, you'll likely 19 need to configure a proxy for accessing the internet, if you haven't 20 done so already. While some tools use the environment variables 21 ``http_proxy`` and ``https_proxy`` to get their proxy settings, some 22 use their own configuration files, most notably ``apt`` and 23 ``git``. 24 25Update Your Operating System 26**************************** 27 28Ensure your host system is up to date. 29 30.. tabs:: 31 32 .. group-tab:: Ubuntu 33 34 .. code-block:: console 35 36 sudo apt-get update 37 sudo apt-get upgrade 38 39 .. group-tab:: Fedora 40 41 .. code-block:: console 42 43 sudo dnf upgrade 44 45 .. group-tab:: Clear Linux 46 47 .. code-block:: console 48 49 sudo swupd update 50 51 .. group-tab:: Arch Linux 52 53 .. code-block:: console 54 55 sudo pacman -Syu 56 57.. _linux_requirements: 58 59Install Requirements and Dependencies 60************************************* 61 62.. NOTE FOR DOCS AUTHORS: DO NOT PUT DOCUMENTATION BUILD DEPENDENCIES HERE. 63 64 This section is for dependencies to build Zephyr binaries, *NOT* this 65 documentation. If you need to add a dependency only required for building 66 the docs, add it to doc/README.rst. (This change was made following the 67 introduction of LaTeX->PDF support for the docs, as the texlive footprint is 68 massive and not needed by users not building PDF documentation.) 69 70Note that both Ninja and Make are installed with these instructions; you only 71need one. 72 73.. tabs:: 74 75 .. group-tab:: Ubuntu 76 77 .. code-block:: console 78 79 sudo apt-get install --no-install-recommends git cmake ninja-build gperf \ 80 ccache dfu-util device-tree-compiler wget \ 81 python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \ 82 make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1 83 84 .. group-tab:: Fedora 85 86 .. code-block:: console 87 88 sudo dnf group install "Development Tools" "C Development Tools and Libraries" 89 sudo dnf install cmake ninja-build gperf dfu-util dtc wget which \ 90 python3-pip python3-tkinter xz file python3-devel SDL2-devel 91 92 .. group-tab:: Clear Linux 93 94 .. code-block:: console 95 96 sudo swupd bundle-add c-basic dev-utils dfu-util dtc \ 97 os-core-dev python-basic python3-basic python3-tcl 98 99 The Clear Linux focus is on *native* performance and security and not 100 cross-compilation. For that reason it uniquely exports by default to the 101 :ref:`environment <env_vars>` of all users a list of compiler and linker 102 flags. Zephyr's CMake build system will either warn or fail because of 103 these. To clear the C/C++ flags among these and fix the Zephyr build, run 104 the following command as root then log out and back in: 105 106 .. code-block:: console 107 108 echo 'unset CFLAGS CXXFLAGS' >> /etc/profile.d/unset_cflags.sh 109 110 Note this command unsets the C/C++ flags for *all users on the 111 system*. Each Linux distribution has a unique, relatively complex and 112 potentially evolving sequence of bash initialization files sourcing each 113 other and Clear Linux is no exception. If you need a more flexible 114 solution, start by looking at the logic in 115 ``/usr/share/defaults/etc/profile``. 116 117 .. group-tab:: Arch Linux 118 119 .. code-block:: console 120 121 sudo pacman -S git cmake ninja gperf ccache dfu-util dtc wget \ 122 python-pip python-setuptools python-wheel tk xz file make 123 124CMake 125===== 126 127A :ref:`recent CMake version <install-required-tools>` is required. Check what 128version you have by using ``cmake --version``. If you have an older version, 129there are several ways of obtaining a more recent one: 130 131* On Ubuntu, you can follow the instructions for adding the 132 `kitware third-party apt repository <https://apt.kitware.com/>`_ 133 to get an updated version of cmake using apt. 134 135* Download and install a packaged cmake from the CMake project site. 136 (Note this won't uninstall the previous version of cmake.) 137 138 .. code-block:: console 139 140 cd ~ 141 wget https://github.com/Kitware/CMake/releases/download/v3.21.1/cmake-3.21.1-Linux-x86_64.sh 142 chmod +x cmake-3.21.1-Linux-x86_64.sh 143 sudo ./cmake-3.21.1-Linux-x86_64.sh --skip-license --prefix=/usr/local 144 hash -r 145 146 The ``hash -r`` command may be necessary if the installation script 147 put cmake into a new location on your PATH. 148 149* Download and install from the pre-built binaries provided by the CMake 150 project itself in the `CMake Downloads`_ page. 151 For example, to install version 3.21.1 in :file:`~/bin/cmake`: 152 153 .. code-block:: console 154 155 mkdir $HOME/bin/cmake && cd $HOME/bin/cmake 156 wget https://github.com/Kitware/CMake/releases/download/v3.21.1/cmake-3.21.1-Linux-x86_64.sh 157 yes | sh cmake-3.21.1-Linux-x86_64.sh | cat 158 echo "export PATH=$PWD/cmake-3.21.1-Linux-x86_64/bin:\$PATH" >> $HOME/.zephyrrc 159 160* Use ``pip3``: 161 162 .. code-block:: console 163 164 pip3 install --user cmake 165 166 Note this won't uninstall the previous version of cmake and will 167 install the new cmake into your ~/.local/bin folder so 168 you'll need to add ~/.local/bin to your PATH. (See :ref:`python-pip` 169 for details.) 170 171* Check your distribution's beta or unstable release package library for an 172 update. 173 174* On Ubuntu you can also use snap to get the latest version available: 175 176 .. code-block:: console 177 178 sudo snap install cmake 179 180After updating cmake, verify that the newly installed cmake is found 181using ``cmake --version``. 182You might also want to uninstall the CMake provided by your package manager to 183avoid conflicts. (Use ``whereis cmake`` to find other installed 184versions.) 185 186DTC (Device Tree Compiler) 187========================== 188 189A :ref:`recent DTC version <install-required-tools>` is required. Check what 190version you have by using ``dtc --version``. If you have an older version, 191either install a more recent one by building from source, or use the one that is 192bundled in the :ref:`Zephyr SDK <toolchain_zephyr_sdk>` by installing it. 193 194Python 195====== 196 197A :ref:`modern Python 3 version <install-required-tools>` is required. Check 198what version you have by using ``python3 --version``. 199 200If you have an older version, you will need to install a more recent Python 3. 201You can build from source, or use a backport from your distribution's package 202manager channels if one is available. Isolating this Python in a virtual 203environment is recommended to avoid interfering with your system Python. 204 205.. _pyenv: https://github.com/pyenv/pyenv 206 207Install the Zephyr Software Development Kit (SDK) 208************************************************* 209 210The Zephyr Software Development Kit (SDK) contains toolchains for each of 211Zephyr's supported architectures. It also includes additional host tools, such 212as custom QEMU and OpenOCD. 213 214Use of the Zephyr SDK is highly recommended and may even be required under 215certain conditions (for example, running tests in QEMU for some architectures). 216 217To install the SDK, follow the Linux steps from the :ref:`Zephyr SDK installation guide <linux_zephyr_sdk>`. 218 219.. _sdkless_builds: 220 221Building on Linux without the Zephyr SDK 222**************************************** 223 224The Zephyr SDK is provided for convenience and ease of use. It provides 225toolchains for all Zephyr target architectures, and does not require any extra 226flags when building applications or running tests. In addition to 227cross-compilers, the Zephyr SDK also provides prebuilt host tools. It is, 228however, possible to build without the SDK's toolchain by using another 229toolchain as described in the :ref:`toolchains` section. 230 231As already noted above, the SDK also includes prebuilt host tools. To use the 232SDK's prebuilt host tools with a toolchain from another source, you must set the 233:envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variable to the Zephyr SDK 234installation directory. To build without the Zephyr SDK's prebuilt host tools, 235the :envvar:`ZEPHYR_SDK_INSTALL_DIR` environment variable must be unset. 236 237To make sure this variable is unset, run: 238 239.. code-block:: console 240 241 unset ZEPHYR_SDK_INSTALL_DIR 242 243.. _Zephyr SDK Releases: https://github.com/zephyrproject-rtos/sdk-ng/tags 244.. _CMake Downloads: https://cmake.org/download 245
