| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
| <!--SPDX-License-Identifier: CC-BY-2.0-UK--> |
| |
| <chapter id='ref-manual-system-requirements'> |
| <title>System Requirements</title> |
| |
| <para> |
| Welcome to the Yocto Project Reference Manual! |
| This manual provides reference information for the current release |
| of the Yocto Project, and |
| is most effectively used after you have an understanding |
| of the basics of the Yocto Project. |
| The manual is neither meant to be read as a starting point to the |
| Yocto Project, nor read from start to finish. |
| Rather, use this manual to find variable definitions, class |
| descriptions, and so forth as needed during the course of using |
| the Yocto Project. |
| </para> |
| |
| <para> |
| For introductory information on the Yocto Project, see the |
| <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and the |
| "<ulink url='&YOCTO_DOCS_OM_URL;#overview-development-environment'>Yocto Project Development Environment</ulink>" |
| chapter in the Yocto Project Overview and Concepts Manual. |
| </para> |
| |
| <para> |
| If you want to use the Yocto Project to quickly build an image |
| without having to understand concepts, work through the |
| <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink> |
| document. |
| You can find "how-to" information in the |
| <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Tasks Manual</ulink>. |
| You can find Yocto Project overview and conceptual information in the |
| <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>. |
| <note><title>Tip</title> |
| For more information about the Yocto Project Documentation set, |
| see the |
| "<link linkend='resources-links-and-related-documentation'>Links and Related Documentation</link>" |
| section. |
| </note> |
| </para> |
| |
| <section id='detailed-supported-distros'> |
| <title>Supported Linux Distributions</title> |
| |
| <para> |
| Currently, the Yocto Project is supported on the following |
| distributions: |
| <note><title>Notes</title> |
| <itemizedlist> |
| <listitem><para> |
| Yocto Project releases are tested against the stable |
| Linux distributions in the following list. |
| The Yocto Project should work on other distributions but |
| validation is not performed against them. |
| </para></listitem> |
| <listitem><para> |
| In particular, the Yocto Project does not support |
| and currently has no plans to support |
| rolling-releases or development distributions due to |
| their constantly changing nature. |
| We welcome patches and bug reports, but keep in mind |
| that our priority is on the supported platforms listed |
| below. |
| </para></listitem> |
| <listitem><para> |
| You may use Windows Subsystem For Linux v2 to set up a build |
| host using Windows 10, but validation is not performed |
| against build hosts using WSLv2. |
| <note> |
| The Yocto Project is not compatible with WSLv1, it is |
| compatible but not officially supported nor validated |
| with WSLv2, if you still decide to use WSL please upgrade |
| to WSLv2. |
| </note> |
| </para></listitem> |
| <listitem><para> |
| If you encounter problems, please go to |
| <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink> |
| and submit a bug. |
| We are interested in hearing about your experience. |
| For information on how to submit a bug, see the |
| Yocto Project |
| <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink> |
| and the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-defect-against-the-yocto-project'>Submitting a Defect Against the Yocto Project</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para></listitem> |
| </itemizedlist> |
| </note> |
| <itemizedlist> |
| <listitem><para>Ubuntu 16.04 (LTS)</para></listitem> |
| <listitem><para>Ubuntu 18.04 (LTS)</para></listitem> |
| <listitem><para>Ubuntu 20.04</para></listitem> |
| <listitem><para>Fedora 30</para></listitem> |
| <listitem><para>Fedora 31</para></listitem> |
| <listitem><para>Fedora 32</para></listitem> |
| <listitem><para>CentOS 7.x</para></listitem> |
| <listitem><para>CentOS 8.x</para></listitem> |
| <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem> |
| <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem> |
| <listitem><para>Debian GNU/Linux 10.x (Buster)</para></listitem> |
| <listitem><para>OpenSUSE Leap 15.1</para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <note> |
| While the Yocto Project Team attempts to ensure all Yocto Project |
| releases are one hundred percent compatible with each officially |
| supported Linux distribution, instances might exist where you |
| encounter a problem while using the Yocto Project on a specific |
| distribution. |
| </note> |
| </section> |
| |
| <section id='required-packages-for-the-build-host'> |
| <title>Required Packages for the Build Host</title> |
| |
| <para> |
| The list of packages you need on the host development system can |
| be large when covering all build scenarios using the Yocto Project. |
| This section describes required packages according to |
| Linux distribution and function. |
| </para> |
| |
| <section id='ubuntu-packages'> |
| <title>Ubuntu and Debian</title> |
| |
| <para> |
| The following list shows the required packages by function |
| given a supported Ubuntu or Debian Linux distribution: |
| <note><title>Notes</title> |
| <itemizedlist> |
| <listitem><para> |
| If your build system has the |
| <filename>oss4-dev</filename> package installed, you |
| might experience QEMU build failures due to the package |
| installing its own custom |
| <filename>/usr/include/linux/soundcard.h</filename> on |
| the Debian system. |
| If you run into this situation, either of the following |
| solutions exist: |
| <literallayout class='monospaced'> |
| $ sudo apt-get build-dep qemu |
| $ sudo apt-get remove oss4-dev |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| For Debian-8, <filename>python3-git</filename> and <filename>pylint3</filename> are no longer available via <filename>apt-get</filename>. |
| <literallayout class='monospaced'> |
| $ sudo pip3 install GitPython pylint==1.9.5 |
| </literallayout> |
| </para></listitem> |
| </itemizedlist> |
| </note> |
| <itemizedlist> |
| <listitem><para><emphasis>Essentials:</emphasis> |
| Packages needed to build an image on a headless |
| system: |
| <literallayout class='monospaced'> |
| $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; |
| </literallayout></para></listitem> |
| <listitem><para><emphasis>Documentation:</emphasis> |
| Packages needed if you are going to build out the |
| Yocto Project documentation manuals: |
| <literallayout class='monospaced'> |
| $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto |
| </literallayout></para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='fedora-packages'> |
| <title>Fedora Packages</title> |
| |
| <para> |
| The following list shows the required packages by function |
| given a supported Fedora Linux distribution: |
| <itemizedlist> |
| <listitem><para><emphasis>Essentials:</emphasis> |
| Packages needed to build an image for a headless |
| system: |
| <literallayout class='monospaced'> |
| $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; |
| </literallayout></para></listitem> |
| <listitem><para><emphasis>Documentation:</emphasis> |
| Packages needed if you are going to build out the |
| Yocto Project documentation manuals: |
| <literallayout class='monospaced'> |
| $ sudo dnf install docbook-style-dsssl docbook-style-xsl \ |
| docbook-dtds docbook-utils fop libxslt dblatex xmlto |
| </literallayout></para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='opensuse-packages'> |
| <title>openSUSE Packages</title> |
| |
| <para> |
| The following list shows the required packages by function |
| given a supported openSUSE Linux distribution: |
| <itemizedlist> |
| <listitem><para><emphasis>Essentials:</emphasis> |
| Packages needed to build an image for a headless |
| system: |
| <literallayout class='monospaced'> |
| $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; |
| </literallayout></para></listitem> |
| <listitem><para><emphasis>Documentation:</emphasis> |
| Packages needed if you are going to build out the |
| Yocto Project documentation manuals: |
| <literallayout class='monospaced'> |
| $ sudo zypper install dblatex xmlto |
| </literallayout></para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='centos-7-packages'> |
| <title>CentOS-7 Packages</title> |
| |
| <para> |
| The following list shows the required packages by function |
| given a supported CentOS-7 Linux distribution: |
| <itemizedlist> |
| <listitem><para><emphasis>Essentials:</emphasis> |
| Packages needed to build an image for a headless |
| system: |
| <literallayout class='monospaced'> |
| $ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL; |
| </literallayout> |
| <note><title>Notes</title> |
| <itemizedlist> |
| <listitem><para> |
| Extra Packages for Enterprise Linux |
| (i.e. <filename>epel-release</filename>) |
| is a collection of packages from Fedora |
| built on RHEL/CentOS for easy installation |
| of packages not included in enterprise |
| Linux by default. |
| You need to install these packages |
| separately. |
| </para></listitem> |
| <listitem><para> |
| The <filename>makecache</filename> command |
| consumes additional Metadata from |
| <filename>epel-release</filename>. |
| </para></listitem> |
| </itemizedlist> |
| </note> |
| </para></listitem> |
| <listitem><para><emphasis>Documentation:</emphasis> |
| Packages needed if you are going to build out the |
| Yocto Project documentation manuals: |
| <literallayout class='monospaced'> |
| $ sudo yum install docbook-style-dsssl docbook-style-xsl \ |
| docbook-dtds docbook-utils fop libxslt dblatex xmlto |
| </literallayout> |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='centos-8-packages'> |
| <title>CentOS-8 Packages</title> |
| |
| <para> |
| The following list shows the required packages by function |
| given a supported CentOS-8 Linux distribution: |
| <itemizedlist> |
| <listitem><para><emphasis>Essentials:</emphasis> |
| Packages needed to build an image for a headless |
| system: |
| <literallayout class='monospaced'> |
| $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL; |
| </literallayout> |
| <note><title>Notes</title> |
| <itemizedlist> |
| <listitem><para> |
| Extra Packages for Enterprise Linux |
| (i.e. <filename>epel-release</filename>) |
| is a collection of packages from Fedora |
| built on RHEL/CentOS for easy installation |
| of packages not included in enterprise |
| Linux by default. |
| You need to install these packages |
| separately. |
| </para></listitem> |
| <listitem><para> |
| The <filename>PowerTools</filename> repo |
| provides additional packages such as |
| <filename>rpcgen</filename> and |
| <filename>texinfo</filename>. |
| </para></listitem> |
| <listitem><para> |
| The <filename>makecache</filename> command |
| consumes additional Metadata from |
| <filename>epel-release</filename>. |
| </para></listitem> |
| </itemizedlist> |
| </note> |
| </para></listitem> |
| <listitem><para><emphasis>Documentation:</emphasis> |
| Packages needed if you are going to build out the |
| Yocto Project documentation manuals: |
| <literallayout class='monospaced'> |
| $ sudo dnf install docbook-style-dsssl docbook-style-xsl \ |
| docbook-dtds docbook-utils fop libxslt dblatex xmlto |
| </literallayout> |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| </section> |
| |
| <section id='required-git-tar-python-and-gcc-versions'> |
| <title>Required Git, tar, Python and gcc Versions</title> |
| |
| <para> |
| In order to use the build system, your host development system |
| must meet the following version requirements for Git, tar, and |
| Python: |
| <itemizedlist> |
| <listitem><para>Git 1.8.3.1 or greater</para></listitem> |
| <listitem><para>tar 1.28 or greater</para></listitem> |
| <listitem><para>Python 3.5.0 or greater</para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| If your host development system does not meet all these requirements, |
| you can resolve this by installing a <filename>buildtools</filename> |
| tarball that contains these tools. |
| You can get the tarball one of two ways: download a pre-built |
| tarball or use BitBake to build the tarball. |
| </para> |
| |
| <para> |
| In addition, your host development system must meet the following |
| version requirement for gcc: |
| <itemizedlist> |
| <listitem><para>gcc 5.0 or greater</para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| If your host development system does not meet this requirement, |
| you can resolve this by installing a <filename>buildtools-extended</filename> |
| tarball that contains additional tools, the equivalent of <filename>buildtools-essential</filename>. |
| </para> |
| <section id='installing-a-pre-built-buildtools-tarball-with-install-buildtools-script'> |
| <title>Installing a Pre-Built <filename>buildtools</filename> Tarball with <filename>install-buildtools</filename> script</title> |
| |
| <para> |
| The <filename>install-buildtools</filename> script is the easiest |
| of the three methods by which you can get these tools. It downloads |
| a pre-built buildtools installer and automatically installs the tools |
| for you: |
| <orderedlist> |
| <listitem><para> |
| Execute the <filename>install-buildtools</filename> script. |
| Here is an example: |
| <literallayout class='monospaced'> |
| $ cd poky |
| $ scripts/install-buildtools --without-extended-buildtools \ |
| --base-url &YOCTO_DL_URL;/releases/yocto \ |
| --release yocto-&DISTRO; \ |
| --installer-version &DISTRO; |
| </literallayout> |
| <para> |
| During execution, the buildtools tarball will be downloaded, |
| the checksum of the download will be verified, the installer |
| will be run for you, and some basic checks will be run to |
| to make sure the installation is functional. |
| </para> |
| <para> |
| To avoid the need of <filename>sudo</filename> privileges, |
| the <filename>install-buildtools</filename> script will |
| by default tell the installer to install in: |
| <literallayout class='monospaced'> |
| <replaceable>/path/to/</replaceable>poky/buildtools |
| </literallayout> |
| </para> |
| <para> |
| If your host development system needs the additional tools |
| provided in the <filename>buildtools-extended</filename> |
| tarball, you can instead execute the |
| <filename>install-buildtools</filename> script with the |
| default parameters: |
| <literallayout class='monospaced'> |
| $ cd poky |
| $ scripts/install-buildtools |
| </literallayout> |
| </para> |
| </para></listitem> |
| <listitem><para> |
| Source the tools environment setup script by using a |
| command like the following: |
| <literallayout class='monospaced'> |
| $ source <replaceable>/path/to/</replaceable>poky/buildtools/environment-setup-x86_64-pokysdk-linux |
| </literallayout> |
| Of course, you need to supply your installation directory and be |
| sure to use the right file (i.e. i586 or x86_64). |
| </para> |
| <para> |
| After you have sourced the setup script, |
| the tools are added to <filename>PATH</filename> |
| and any other environment variables required to run the |
| tools are initialized. |
| The results are working versions versions of Git, tar, |
| Python and <filename>chrpath</filename>. And in the case of |
| the <filename>buildtools-extended</filename> tarball, additional |
| working versions of tools including <filename>gcc</filename>, |
| <filename>make</filename> and the other tools included in |
| <filename>packagegroup-core-buildessential</filename>. |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| |
| <section id='downloading-a-pre-built-buildtools-tarball'> |
| <title>Downloading a Pre-Built <filename>buildtools</filename> Tarball</title> |
| |
| <para> |
| Downloading and running a pre-built buildtools installer is |
| the easiest of the two methods by which you can get these tools: |
| <orderedlist> |
| <listitem><para> |
| Locate and download the <filename>*.sh</filename> at |
| <ulink url='&YOCTO_RELEASE_DL_URL;/buildtools/'></ulink>. |
| </para></listitem> |
| <listitem><para> |
| Execute the installation script. |
| Here is an example for the traditional installer: |
| <literallayout class='monospaced'> |
| $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh |
| </literallayout> |
| Here is an example for the extended installer: |
| <literallayout class='monospaced'> |
| $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh |
| </literallayout> |
| During execution, a prompt appears that allows you to |
| choose the installation directory. |
| For example, you could choose the following: |
| <literallayout class='monospaced'> |
| /home/<replaceable>your-username</replaceable>/buildtools |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| Source the tools environment setup script by using a |
| command like the following: |
| <literallayout class='monospaced'> |
| $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux |
| </literallayout> |
| Of course, you need to supply your installation directory and be |
| sure to use the right file (i.e. i585 or x86-64). |
| </para> |
| <para> |
| After you have sourced the setup script, |
| the tools are added to <filename>PATH</filename> |
| and any other environment variables required to run the |
| tools are initialized. |
| The results are working versions versions of Git, tar, |
| Python and <filename>chrpath</filename>. And in the case of |
| the <filename>buildtools-extended</filename> tarball, additional |
| working versions of tools including <filename>gcc</filename>, |
| <filename>make</filename> and the other tools included in |
| <filename>packagegroup-core-buildessential</filename>. |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| |
| <section id='building-your-own-buildtools-tarball'> |
| <title>Building Your Own <filename>buildtools</filename> Tarball</title> |
| |
| <para> |
| Building and running your own buildtools installer applies |
| only when you have a build host that can already run BitBake. |
| In this case, you use that machine to build the |
| <filename>.sh</filename> file and then |
| take steps to transfer and run it on a |
| machine that does not meet the minimal Git, tar, and Python |
| (or gcc) requirements. |
| </para> |
| |
| <para> |
| Here are the steps to take to build and run your own |
| buildtools installer: |
| <orderedlist> |
| <listitem><para> |
| On the machine that is able to run BitBake, |
| be sure you have set up your build environment with |
| the setup script |
| (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). |
| </para></listitem> |
| <listitem><para> |
| Run the BitBake command to build the tarball: |
| <literallayout class='monospaced'> |
| $ bitbake buildtools-tarball |
| </literallayout> |
| or run the BitBake command to build the extended tarball: |
| <literallayout class='monospaced'> |
| $ bitbake buildtools-extended-tarball |
| </literallayout> |
| <note> |
| The |
| <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link> |
| variable in your <filename>local.conf</filename> file |
| determines whether you build tools for a 32-bit |
| or 64-bit system. |
| </note> |
| Once the build completes, you can find the |
| <filename>.sh</filename> file that installs |
| the tools in the <filename>tmp/deploy/sdk</filename> |
| subdirectory of the |
| <link linkend='build-directory'>Build Directory</link>. |
| The installer file has the string "buildtools" |
| (or "buildtools-extended") in the name. |
| </para></listitem> |
| <listitem><para> |
| Transfer the <filename>.sh</filename> file from the |
| build host to the machine that does not meet the |
| Git, tar, or Python (or gcc) requirements. |
| </para></listitem> |
| <listitem><para> |
| On the machine that does not meet the requirements, |
| run the <filename>.sh</filename> file |
| to install the tools. |
| Here is an example for the traditional installer: |
| <literallayout class='monospaced'> |
| $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh |
| </literallayout> |
| Here is an example for the extended installer: |
| <literallayout class='monospaced'> |
| $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh |
| </literallayout> |
| During execution, a prompt appears that allows you to |
| choose the installation directory. |
| For example, you could choose the following: |
| <literallayout class='monospaced'> |
| /home/<replaceable>your_username</replaceable>/buildtools |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| Source the tools environment setup script by using a |
| command like the following: |
| <literallayout class='monospaced'> |
| $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-x86_64-poky-linux |
| </literallayout> |
| Of course, you need to supply your installation directory and be |
| sure to use the right file (i.e. i586 or x86_64). |
| </para> |
| <para> |
| After you have sourced the setup script, |
| the tools are added to <filename>PATH</filename> |
| and any other environment variables required to run the |
| tools are initialized. |
| The results are working versions versions of Git, tar, |
| Python and <filename>chrpath</filename>. And in the case of |
| the <filename>buildtools-extended</filename> tarball, additional |
| working versions of tools including <filename>gcc</filename>, |
| <filename>make</filename> and the other tools included in |
| <filename>packagegroup-core-buildessential</filename>. |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| </section> |
| </chapter> |
| <!-- |
| vim: expandtab tw=80 ts=4 |
| --> |