documentation/brief-yoctoprojectqs/index.rst

1 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
4 Yocto Project Quick Build
11 image build using the Yocto Project. The document also introduces how to
12 configure a build for specific hardware. You will use Yocto Project to
13 build a reference embedded OS called Poky.
17    -  The examples in this paper assume you are using a native Linux
18       system running a recent Ubuntu Linux distribution. If the machine
19       you want to use Yocto Project on to build an image
20       (:term:`Build Host`) is not
21       a native Linux system, you can still perform these steps by using
23       :ref:`dev-manual/start:setting up to use cross platforms (crops)`
28    -  You may use version 2 of Windows Subsystem For Linux (WSL 2) to set
29       up a build host using Windows 10 or later, Windows Server 2019 or later.
30       See the :ref:`dev-manual/start:setting up to use windows subsystem for
35 Project, see the :doc:`/overview-manual/index`.
40 Make sure your :term:`Build Host` meets the
43 -  At least &MIN_DISK_SPACE; Gbytes of free disk space, though
45    performance by reusing build artifacts.
47 -  At least &MIN_RAM; Gbytes of RAM, though a modern modern build host with as
49    maximize build performance.
51 -  Runs a supported Linux distribution (i.e. recent releases of Fedora,
54    :ref:`ref-manual/system-requirements:supported linux distributions`
56    information on preparing your build host, see the
57    :ref:`dev-manual/start:preparing the build host`
60 -
62    -  Git &MIN_GIT_VERSION; or greater
63    -  tar &MIN_TAR_VERSION; or greater
64    -  Python &MIN_PYTHON_VERSION; or greater.
65    -  gcc &MIN_GCC_VERSION; or greater.
66    -  GNU make &MIN_MAKE_VERSION; or greater
68 If your build host does not meet any of these three listed version
69 requirements, you can take steps to prepare the system so that you
71 :ref:`ref-manual/system-requirements:required git, tar, python, make and gcc versions`
74 Build Host Packages
77 You must install essential host packages on your build host. The
86    see the :ref:`ref-manual/system-requirements:required packages for the build host`
93 get a copy of the Poky repository on your build host. Use the following
96 .. code-block:: shell
113 .. code-block:: shell
116    $ git branch -a
120    remotes/origin/HEAD -> origin/master
122    remotes/origin/dunfell-next
127    remotes/origin/gatesgarth-next
132    remotes/origin/master-next
141 .. code-block:: shell
143    $ git checkout -t origin/&DISTRO_NAME_NO_CAP; -b my-&DISTRO_NAME_NO_CAP;
144 …Branch 'my-&DISTRO_NAME_NO_CAP;' set up to track remote branch '&DISTRO_NAME_NO_CAP;' from 'origin…
145    Switched to a new branch 'my-&DISTRO_NAME_NO_CAP;'
148 ``my-&DISTRO_NAME_NO_CAP;``. The files available to you in that branch
155 .. code-block:: shell
161 :ref:`dev-manual/start:locating yocto project source files`
167 Use the following steps to build your image. The build process creates
172    -  If you are working behind a firewall and your build host is not
173       set up for proxies, you could encounter problems with the build
177    -  If you do not know your proxy settings, consult your local network
184 #. **Initialize the Build Environment:** From within the ``poky``
185    directory, run the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\``
187    setup script to define Yocto Project's build environment on your
188    build host.
190    .. code-block:: shell
193       $ source oe-init-build-env
215           core-image-minimal
216           core-image-full-cmdline
217           core-image-sato
218           core-image-weston
219           meta-toolchain
220           meta-ide-support
222       You can also run generated QEMU images with a command like 'runqemu qemux86-64'
225        - 'devtool' and 'recipetool' handle common recipe tasks
226        - 'bitbake-layers' handles common layer tasks
227        - 'oe-pkgdata-util' handles common target package tasks
229    Among other things, the script creates the :term:`Build Directory`, which is
230    ``build`` in this case and is located in the :term:`Source Directory`.  After
232    :term:`Build Directory`. Later, when the build completes, the
233    :term:`Build Directory` contains all the files created during the build.
235 #. **Examine Your Local Configuration File:** When you set up the build
237    available in a ``conf`` subdirectory of the :term:`Build Directory`. For this
238    example, the defaults are set to build for a ``qemux86`` target,
244       You can significantly speed up your build and guard against fetcher
245       failures by using :ref:`overview-manual/concepts:shared state cache`
246       mirrors and enabling :ref:`overview-manual/concepts:hash equivalence`.
247       This way, you can use pre-built artifacts rather than building them.
249       can download these artifacts faster than you would be able to build them.
252       file in the :term:`Build Directory`::
260       or later. Debian GNU/Linux 12 (Bookworm) and later, Fedora, CentOS Stream
265 #. **Start the Build:** Continue with the following command to build an OS
266    image for the target, which is ``core-image-sato`` in this example:
268    .. code-block:: shell
270       $ bitbake core-image-sato
273    :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and
275    :ref:`bitbake-user-manual/bitbake-user-manual-intro:the bitbake command`
282    .. code-block:: shell
284       $ runqemu qemux86-64
287    :ref:`dev-manual/qemu:using the quick emulator (qemu)` chapter in
291    ``Ctrl-C`` in the QEMU transcript window from which you evoked QEMU.
293 Customizing Your Build for Specific Hardware
297 emulation only. This section shows you how to customize your build for
308    By convention, layer names start with the string "meta-".
315    `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer.
321    .. code-block:: shell
324       $ git clone https://github.com/kraj/meta-altera.git
325       Cloning into 'meta-altera'...
328       remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219
334    next to other layers inside the Poky reference repository on your build
335    host as ``meta-altera`` and contains all the metadata needed to
344 #. **Change the Configuration to Build for a Specific Machine:** The
346    ``local.conf`` file specifies the machine for the build. For this
349    https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf.
354       information on configuring the build.
357    a layer during a build, you must add it to your ``bblayers.conf``
358    file, which is found in the :term:`Build Directory` ``conf`` directory.
360    Use the ``bitbake-layers add-layer`` command to add the layer to the
363    .. code-block:: shell
365       $ cd poky/build
366       $ bitbake-layers add-layer ../meta-altera
374    :ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`
377 Completing these steps has added the ``meta-altera`` layer to your Yocto
378 Project development environment and configured it to build for the
384    to attempt to build an image for the ``cyclone5`` machine, you should
392 ``bitbake-layers create-layer`` command. The tool automates layer
394 configuration file, a ``recipes-example`` subdirectory that contains an
398 ``meta-mylayer`` in the ``poky`` directory:
400 .. code-block:: shell
403    $ bitbake-layers create-layer meta-mylayer
405    Add your new layer with 'bitbake-layers add-layer meta-mylayer'
409 :ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`
419 -  **Website:** The :yocto_home:`Yocto Project Website <>` provides
424 -  **Video Seminar:** The `Introduction to the Yocto Project and BitBake, Part 1
431 -  **Yocto Project Overview and Concepts Manual:** The
432    :doc:`/overview-manual/index` is a great
438 -  **Yocto Project Wiki:** The :yocto_wiki:`Yocto Project Wiki <>`
443 -  **Yocto Project Mailing Lists:** Related mailing lists provide a forum
446    :ref:`ref-manual/resources:mailing lists`
450 -  **Comprehensive List of Links and Other Documentation:** The
451    :ref:`ref-manual/resources:links and related documentation`