@@ -205,6 +205,12 @@ This directory contains:
- A ``config`` directory, representing the current configuration used for this
:term:`bitbake:setup`.
+.. note::
+
+ It is also possible to setup the :term:`Poky` reference distro manually. For
+ that refer to the :doc:`/dev-manual/poky-manual-setup` section of the Yocto
+ Project Development Tasks Manual.
+
Building Your Image
===================
@@ -261,7 +267,9 @@ an entire Linux distribution, including the toolchain, from source.
These set up the environment similar to what was previously in the local
configuration file :ref:`local.conf <structure-build-conf-local.conf>`,
- which is now largely empty.
+ which is now largely empty. To setup the build how it was done
+ previously, see the :doc:`/dev-manual/poky-manual-setup` section of the
+ Yocto Project Development Tasks Manual.
The current configuration does not allow the ``root`` user to login. As this
can be useful for development, you can enable ``root`` login by opening the
@@ -17,6 +17,7 @@ Yocto Project Development Tasks Manual
upgrading-recipes
temporary-source-code
creating-fragments
+ poky-manual-setup
quilt.rst
development-shell
python-development-shell
new file mode 100644
@@ -0,0 +1,125 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+Setting Up the Poky Reference Distro Manually
+*********************************************
+
+While the default way to setup the :term:`Poky` reference distro is to use
+``bitbake-setup``, it is also possible to manually setup the environment. This
+document guides through this setup step-by-step.
+
+.. note::
+
+ This document will produce a setup similar to what is described in
+ :doc:`/brief-yoctoprojectqs/index`, which shows how to setup :term:`Poky`
+ with ``bitbake-setup``.
+
+Use Git to Clone The Layers
+===========================
+
+Go to :yocto_wiki:`Releases wiki page </Releases>`, and choose a release
+(such as ``&DISTRO_REL_LATEST_TAG;``), corresponding to either the latest stable
+release or a Long Term Support release.
+
+Once you complete the setup instructions for your machine (see the
+:doc:`/ref-manual/system-requirements` section of the Yocto Project Reference
+Manual), you need to get a copy of the different :term:`layers <Layer>` needed
+to setup the :term:`Poky` reference distribution on your build host. Use the
+following commands:
+
+.. code-block:: shell
+
+ $ mkdir layers/
+ $ git clone -b &DISTRO_REL_LATEST_TAG; https://git.openembedded.org/bitbake ./layers/bitbake
+ $ git clone -b &DISTRO_REL_LATEST_TAG; https://git.openembedded.org/openembedded-core ./layers/openembedded-core
+ $ git clone -b &DISTRO_REL_LATEST_TAG; https://git.yoctoproject.org/meta-yocto ./layers/meta-yocto
+
+Building Your Image
+===================
+
+Use the following steps to build your image. The build process creates
+an entire Linux distribution, including the toolchain, from source.
+
+.. note::
+
+ - If you are working behind a firewall and your build host is not
+ set up for proxies, you could encounter problems with the build
+ process when fetching source code (e.g. fetcher failures or Git
+ failures).
+
+ - If you do not know your proxy settings, consult your local network
+ infrastructure resources and get that information. A good starting
+ point could also be to check your web browser settings. Finally,
+ you can find more information on the
+ ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
+ page of the Yocto Project Wiki.
+
+#. **Initialize the Build Environment:** From your current working directory,
+ setup a build environment with the following command:
+
+ .. code-block:: shell
+
+ $ TEMPLATECONF=$PWD/layers/meta-yocto/meta-poky/conf/templates/default source ./layers/openembedded-core/oe-init-build-env
+
+ Among other things, the script creates the :term:`Build Directory`, which is
+ ``build`` in this case and is located in the :term:`Source Directory`.
+ After the script runs, your current working directory is set to the
+ :term:`Build Directory`. Later, when the build completes, the :term:`Build
+ Directory` contains all the files created during the build.
+
+#. **Examine Your Local Configuration File:** When you set up the build
+ environment, a local configuration file named ``local.conf`` becomes
+ available in a ``conf`` sub-directory of the :term:`Build Directory`. For
+ this example, the defaults are set to build for a ``qemux86-64`` target,
+ which is suitable for emulation. The package manager used is set to the RPM
+ package manager.
+
+ .. tip::
+
+ You can significantly speed up your build and guard against fetcher
+ failures by using :ref:`overview-manual/concepts:shared state cache`
+ mirrors and enabling :ref:`overview-manual/concepts:hash equivalence`.
+ This way, you can use pre-built artifacts rather than building them.
+ This is relevant only when your network and the server that you use
+ can download these artifacts faster than you would be able to build them.
+
+ To use such mirrors, uncomment the below lines in your ``conf/local.conf``
+ file in the :term:`Build Directory`::
+
+ BB_HASHSERVE_UPSTREAM = "wss://hashserv.yoctoproject.org/ws"
+ SSTATE_MIRRORS ?= "file://.* http://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH"
+ BB_HASHSERVE = "auto"
+ BB_SIGNATURE_HANDLER = "OEEquivHash"
+
+ The hash equivalence server needs the websockets python module version 9.1
+ or later. Debian GNU/Linux 12 (Bookworm) and later, Fedora, CentOS Stream
+ 9 and later, and Ubuntu 22.04 (LTS) and later, all have a recent enough
+ package. Other supported distributions need to get the module some other
+ place than their package feed, e.g. via ``pip``.
+
+#. **Start the Build:** Continue with the following command to build an OS
+ image for the target, which is ``core-image-sato`` in this example:
+
+ .. code-block:: shell
+
+ $ bitbake core-image-sato
+
+ For information on using the ``bitbake`` command, see the
+ :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and
+ Concepts Manual, or see
+ :ref:`bitbake-user-manual/bitbake-user-manual-intro:the bitbake command`
+ in the BitBake User Manual.
+
+#. **Simulate Your Image Using QEMU:** Once this particular image is
+ built, you can start QEMU, which is a Quick EMUlator that ships with
+ the Yocto Project:
+
+ .. code-block:: shell
+
+ $ runqemu qemux86-64
+
+ If you want to learn more about running QEMU, see the
+ :ref:`dev-manual/qemu:using the quick emulator (qemu)` chapter in
+ the Yocto Project Development Tasks Manual.
+
+#. **Exit QEMU:** Exit QEMU by either clicking on the shutdown icon or by typing
+ ``Ctrl-C`` in the QEMU transcript window from which you evoked QEMU.
Add a new document describing how to setup the Poky reference distribution manually. This document is referenced in the Quick Guide, so that users that _know_ they want to setup Poky without bitbake-setup have a link to it. This document is also important to reflect the layout of the layers expected by the bblayers.conf.sample file, as explained in [1]. [1]: https://lore.kernel.org/poky/20251028-update-bblayers-sample-v1-1-97ec54cda94e@bootlin.com/ Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> --- documentation/brief-yoctoprojectqs/index.rst | 10 +- documentation/dev-manual/index.rst | 1 + documentation/dev-manual/poky-manual-setup.rst | 125 +++++++++++++++++++++++++ 3 files changed, 135 insertions(+), 1 deletion(-)