@@ -87,80 +87,122 @@ distribution:
see the :ref:`ref-manual/system-requirements:required packages for the build host`
section in the Yocto Project Reference Manual.
-Use Git to Clone Poky
-=====================
+Use Git to Clone bitbake-setup
+==============================
Once you complete the setup instructions for your machine, you need to
-get a copy of the Poky repository on your build host. Use the following
-commands to clone the Poky repository.
+get a copy of the ``bitbake-setup`` tool to setup the :term:`Poky` reference
+distribution on your build host. Use the following commands to clone
+the bitbake repository.
.. code-block:: shell
- $ git clone git://git.yoctoproject.org/poky
- Cloning into 'poky'...
- remote: Counting
- objects: 432160, done. remote: Compressing objects: 100%
- (102056/102056), done. remote: Total 432160 (delta 323116), reused
- 432037 (delta 323000) Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done.
- Resolving deltas: 100% (323116/323116), done.
- Checking connectivity... done.
+ $ git clone git://git.openembedded.org/bitbake bitbake-setup
-Go to :yocto_wiki:`Releases wiki page </Releases>`, and choose a release
-codename (such as ``&DISTRO_NAME_NO_CAP;``), corresponding to either the
-latest stable release or a Long Term Support release.
-
-Then move to the ``poky`` directory and take a look at existing branches:
+Setup a build environment with the following command:
.. code-block:: shell
- $ cd poky
- $ git branch -a
- .
- .
- .
- remotes/origin/HEAD -> origin/master
- remotes/origin/dunfell
- remotes/origin/dunfell-next
- .
- .
- .
- remotes/origin/gatesgarth
- remotes/origin/gatesgarth-next
- .
- .
- .
- remotes/origin/master
- remotes/origin/master-next
- .
- .
- .
-
-
-For this example, check out the ``&DISTRO_NAME_NO_CAP;`` branch based on the
-``&DISTRO_NAME;`` release:
+ $ ./bitbake-setup/bin/bitbake-setup init
+
+By default, this will setup a top directory in ``$HOME/bitbake-builds``.
+
+If you prefer to setup your builds in a different top directory, for example the
+current directory, you can set it with the ``bitbake-setup settings`` command:
.. code-block:: shell
- $ git checkout -t origin/&DISTRO_NAME_NO_CAP; -b my-&DISTRO_NAME_NO_CAP;
- Branch 'my-&DISTRO_NAME_NO_CAP;' set up to track remote branch '&DISTRO_NAME_NO_CAP;' from 'origin'.
- Switched to a new branch 'my-&DISTRO_NAME_NO_CAP;'
+ $ ./bitbake-setup/bin/bitbake-setup settings set --global default top-dir-prefix $PWD
+
+.. note::
-The previous Git checkout command creates a local branch named
-``my-&DISTRO_NAME_NO_CAP;``. The files available to you in that branch
-exactly match the repository's files in the ``&DISTRO_NAME_NO_CAP;``
-release branch.
+ Use ``bitbake-setup settings list`` to get an overview of the settings.
-Note that you can regularly type the following command in the same directory
-to keep your local files in sync with the release branch:
+``bitbake-setup init`` is an interactive program by default and will ask you to
+make some decisions. Depending on your answers, the choices may differ from the
+examples below.
-.. code-block:: shell
+#. Choose a configuration (for example, ``poky-master``):
- $ git pull
+ .. code-block:: shell
-For more options and information about accessing Yocto Project related
-repositories, see the
-:ref:`dev-manual/start:locating yocto project source files`
-section in the Yocto Project Development Tasks Manual.
+ Available configurations:
+ 0. poky-master Poky - The Yocto Project testing distribution configurations and hardware test platforms
+ 1. oe-nodistro OpenEmbedded - 'nodistro' basic configuration
+
+ Please select one of the above configurations by its number:
+ 0
+
+ Depending on the choice above, new options can be prompted to further specify
+ which configuration to use. For example:
+
+ .. code-block:: shell
+
+ Available bitbake configurations:
+ 0. poky Poky - The Yocto Project testing distribution
+ 1. poky-with-sstate Poky - The Yocto Project testing distribution with internet sstate acceleration. Use with caution as it requires a completely robust local network with sufficient bandwidth.
+
+ Please select one of the above bitbake configurations by its number:
+ 0
+
+#. Choose a target :term:`MACHINE` (for example, ``qemux86-64``):
+
+ .. code-block:: shell
+
+ Target machines:
+ 0. machine/qemux86-64
+ 1. machine/qemuarm64
+ 2. machine/qemuriscv64
+ 3. machine/genericarm64
+ 4. machine/genericx86-64
+
+ Please select one of the above options by its number:
+ 0
+
+#. Choose a :term:`DISTRO` (for example, ``poky``):
+
+ .. code-block:: shell
+
+ Distribution configuration variants:
+ 0. distro/poky
+ 1. distro/poky-altcfg
+ 2. distro/poky-tiny
+
+ Please select one of the above options by its number:
+ 0
+
+.. note::
+
+ If you prefer to run non-interactively, you can run a command like the
+ following:
+
+ .. code-block:: shell
+
+ $ bitbake-setup init --non-interactive poky-master poky-with-sstate distro/poky machine/qemux86-64
+
+The ``init`` command creates a new folder in the top directory. Its name is
+derived from the selected configuration above.
+
+For the selected options in the above example, this would be::
+
+ poky-master-poky-distro_poky-machine_qemux86-64
+
+This will be our example configuration in the following sections.
+
+This directory contains:
+
+- The :term:`Build Directory`, named ``build``. Later, when the build
+ completes, the :term:`Build Directory` contains all the files created during
+ the build.
+
+ This :term:`Build Directory` also contains a ``README``, describing the
+ currently configuration and minimal instructions.
+
+- The :term:`layers <Layer>` needed to build the Poky reference distribution,
+ in the ``layers`` directory.
+
+- A ``config`` directory, representing the current configuration used in this
+ directory.
Building Your Image
===================
@@ -182,86 +224,64 @@ an entire Linux distribution, including the toolchain, from source.
":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
page of the Yocto Project Wiki.
-#. **Initialize the Build Environment:** From within the ``poky``
- directory, run the :ref:`ref-manual/structure:``oe-init-build-env```
- environment
- setup script to define Yocto Project's build environment on your
- build host.
+#. **Initialize the Build Environment:** Source the ``init-build-env``
+ environment setup script within the build directory to setup Yocto Project's
+ build environment on your :term:`Build Host`:
- .. code-block:: shell
+ .. code-block:: shell
+
+ $ source poky-master-poky-distro_poky-machine_qemux86-64/build/init-build-env
+ Poky reference distro build
+
+#. **Examine Your Current Configuration:** When you set up the build
+ environment, an configuration file named :ref:`toolcfg.conf
+ <structure-build-conf-toolcfg.conf>` becomes available in a ``conf``
+ sub-directory of the :term:`Build Directory`. This file is automatically
+ modified by the ``bitbake-config-build`` command-line tool. With this tool,
+ list the currently enabled :term:`configuration fragments <Configuration
+ Fragment>`:
+
+ .. code-block:: shell
+
+ $ bitbake-config-build list-fragments
+
+ For this configuration, the default is to use two :term:`Built-in Fragments
+ <Built-in Fragment>`:
+
+ - ``distro/poky`` sets the :term:`DISTRO` to :term:`Poky`
+ (:ref:`ref-fragments-builtin-core-distro`).
+ - ``machine/qemux86-64`` sets the :term:`MACHINE` to ``qemux86-64``
+ (:ref:`ref-fragments-builtin-core-machine`).
+
+ These fragments correspond to the choices made when running ``bitbake-setup
+ init``.
+
+ 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
+ :ref:`structure-build-conf-site.conf` file and adding the following
+ statement::
- $ cd poky
- $ source oe-init-build-env
- You had no conf/local.conf file. This configuration file has therefore been
- created for you with some default values. You may wish to edit it to, for
- example, select a different MACHINE (target hardware). See conf/local.conf
- for more information as common configuration options are commented.
-
- You had no conf/bblayers.conf file. This configuration file has therefore
- been created for you with some default values. To add additional metadata
- layers into your configuration please add entries to conf/bblayers.conf.
-
- The Yocto Project has extensive documentation about OE including a reference
- manual which can be found at:
- https://docs.yoctoproject.org
-
- For more information about OpenEmbedded see their website:
- https://www.openembedded.org/
-
- ### Shell environment set up for builds. ###
-
- You can now run 'bitbake <target>'
-
- Common targets are:
- core-image-minimal
- core-image-full-cmdline
- core-image-sato
- core-image-weston
- meta-toolchain
- meta-ide-support
-
- You can also run generated QEMU images with a command like 'runqemu qemux86-64'
-
- Other commonly useful commands are:
- - 'devtool' and 'recipetool' handle common recipe tasks
- - 'bitbake-layers' handles common layer tasks
- - 'oe-pkgdata-util' handles common target package tasks
-
- 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`` subdirectory of the :term:`Build Directory`. For this
- example, the defaults are set to build for a ``qemux86`` 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``.
+ EXTRA_IMAGE_FEATURES = "allow-empty-password empty-root-password allow-root-login"
+
+ .. note::
+
+ 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.
+
+ .. note::
+
+ 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, enable the
+ :ref:`ref-fragments-core-yocto-sstate-mirror-cdn` fragment::
+
+ $ bitbake-config-build enable-fragment core/yocto/sstate-mirror-cdn
#. **Start the Build:** Continue with the following command to build an OS
image for the target, which is ``core-image-sato`` in this example:
@@ -310,80 +330,53 @@ modular development and makes it easier to reuse the layer metadata.
Follow these steps to add a hardware layer:
-#. **Find a Layer:** Many hardware layers are available. The Yocto Project
- :yocto_git:`Source Repositories <>` has many hardware layers.
- This example adds the
- `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer.
+#. **Find a Layer:** Many hardware layers, or :ref:`BSP layers
+ <overview-manual/concepts:bsp layer>` are available. The
+ :oe_layerindex:`layer index <>` can be used to find such layers. This example
+ adds the :yocto_git:`meta-yocto-bsp </meta-yocto/tree/meta-yocto-bsp>` BSP
+ layer.
-#. **Clone the Layer:** Use Git to make a local copy of the layer on your
- machine. You can put the copy in the top level of the copy of the
- Poky repository created earlier:
-
- .. code-block:: shell
+#. **Add Your Layer to the Layer Configuration File:** Before you can use
+ a layer during a build, you must add it to your ``bblayers.conf``
+ file, which is found in the :term:`Build Directory` ``conf`` directory.
- $ cd poky
- $ git clone https://github.com/kraj/meta-altera.git
- Cloning into 'meta-altera'...
- remote: Counting objects: 25170, done.
- remote: Compressing objects: 100% (350/350), done.
- remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219
- Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done.
- Resolving deltas: 100% (13385/13385), done.
- Checking connectivity... done.
+ This layer is already part of ``meta-yocto``, so from the :term:`Build
+ Directory` use the ``bitbake-layers add-layer`` command to add the layer to
+ the configuration file:
- The hardware layer is now available
- next to other layers inside the Poky reference repository on your build
- host as ``meta-altera`` and contains all the metadata needed to
- support hardware from Altera, which is owned by Intel.
+ .. code-block:: shell
- .. note::
+ $ bitbake-layers add-layer ../layers/meta-yocto/meta-yocto-bsp
- It is recommended for layers to have a branch per Yocto Project release.
- Please make sure to checkout the layer branch supporting the Yocto Project
- release you're using.
+ You can find more information on adding layers in the
+ :ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\`
+ script` section.
-#. **Change the Configuration to Build for a Specific Machine:** The
- :term:`MACHINE` variable in the
- ``local.conf`` file specifies the machine for the build. For this
- example, set the :term:`MACHINE` variable to ``cyclone5``. These
- configurations are used:
- https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf.
+#. **Change the Configuration to Build for a Specific Machine:** The
+ :term:`MACHINE` variable defined by the
+ :ref:`ref-fragments-builtin-core-machine` fragment defines the machine for
+ the build. For this example. The ``meta-yocto-bsp`` provides the
+ :yocto_git:`beaglebone-yocto </meta-yocto/tree/meta-yocto-bsp/conf/machine/beaglebone-yocto.conf>`
+ machine, make it the one used for the build with ``bitbake-config-build``:
- .. note::
+ .. code-block:: shell
- See the "Examine Your Local Configuration File" step earlier for more
- information on configuring the build.
+ $ bitbake-config-build enable-fragment machine/beaglebone-yocto
-#. **Add Your Layer to the Layer Configuration File:** Before you can use
- a layer during a build, you must add it to your ``bblayers.conf``
- file, which is found in the :term:`Build Directory` ``conf`` directory.
+ .. note::
- Use the ``bitbake-layers add-layer`` command to add the layer to the
- configuration file:
+ See the "Examine Your Current Configuration" step earlier for more
+ information on configuring the build.
- .. code-block:: shell
-
- $ cd poky/build
- $ bitbake-layers add-layer ../meta-altera
- NOTE: Starting bitbake server...
- Parsing recipes: 100% |##################################################################| Time: 0:00:32
- Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets,
- 123 skipped, 0 masked, 0 errors.
-
- You can find
- more information on adding layers in the
- :ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`
- section.
-
-Completing these steps has added the ``meta-altera`` layer to your Yocto
+Completing these steps has added the ``meta-yocto-bsp`` layer to your Yocto
Project development environment and configured it to build for the
-``cyclone5`` machine.
+``beaglebone-yocto`` machine.
.. note::
The previous steps are for demonstration purposes only. If you were
- to attempt to build an image for the ``cyclone5`` machine, you should
- read the Altera ``README``.
+ to attempt to build an image for the ``beaglebone-yocto `` machine, you
+ should read the ``README`` in ``meta-yocto-bsp``.
Creating Your Own General Layer
===============================
@@ -396,14 +389,17 @@ configuration file, a ``recipes-example`` subdirectory that contains an
``example.bb`` recipe, a licensing file, and a ``README``.
The following commands run the tool to create a layer named
-``meta-mylayer`` in the ``poky`` directory:
+``meta-mylayer``:
.. code-block:: shell
- $ cd poky
- $ bitbake-layers create-layer meta-mylayer
+ $ bitbake-layers create-layer ../layers/meta-mylayer
NOTE: Starting bitbake server...
- Add your new layer with 'bitbake-layers add-layer meta-mylayer'
+ Add your new layer with 'bitbake-layers add-layer ../layers/meta-mylayer'
+
+.. note::
+
+ By convention, layers are placed side-by-side.
For more information
on layers and how to create them, see the
@@ -368,6 +368,11 @@ symbolic link to a common ``site.conf`` file::
This way, site-specific settings can be shared for multiple build
configurations.
+.. note::
+
+ For more information on how to use ``bitbake-setup``, see the
+ :doc:`/brief-yoctoprojectqs/index` document.
+
.. _structure-build-conf-bblock.conf:
``build/conf/bblock.conf``
Switch to bitbake-setup as it has been merged in BitBake with commit b96154aeb1fc ("bitbake-setup: add the initial implementation"). This is the default way to setup repositories now, so describe it in brief-yoctoprojectqs.rst. Update the BSP layer addition section to use meta-yocto-bsp as meta-altera seems abandoned (latest compatible version: mickedore). meta-yocto-bsp is probably already part of the bblayers.conf file when we instruct to add it with bitbake-layers, but this does not produce an error and is still nice to have for demo purposes. Co-developed-by: Tim Orling <tim.orling@konsulko.com> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> --- documentation/brief-yoctoprojectqs/index.rst | 390 +++++++++++++-------------- documentation/ref-manual/structure.rst | 5 + 2 files changed, 198 insertions(+), 197 deletions(-)