mirror of
git://git.yoctoproject.org/poky
synced 2025-12-31 13:38:04 +00:00
brief-yoctoprojectqs: switch to bitbake-setup
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-raspberrypi as
meta-altera seems abandoned (latest compatible version: mickedore).
Co-developed-by: Tim Orling <tim.orling@konsulko.com>
(From yocto-docs rev: 868da60dd90ee6c8710df1ed14b046d809d25b52)
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Antonin Godard
Richard Purdie
parent
f4c37762b9
commit
83c5ebde19
@ -87,80 +87,123 @@ 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 -b &DISTRO_REL_LATEST_TAG; 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
|
||||
.
|
||||
.
|
||||
.
|
||||
$ ./bitbake-setup/bin/bitbake-setup init
|
||||
|
||||
By default, this will setup a top directory in ``$HOME/bitbake-builds``.
|
||||
|
||||
For this example, check out the ``&DISTRO_NAME_NO_CAP;`` branch based on the
|
||||
``&DISTRO_NAME;`` release:
|
||||
If you prefer to setup your builds in a different top directory, for example the
|
||||
current directory, you can set it with the :ref:`bitbake:ref-bbsetup-command-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
|
||||
|
||||
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.
|
||||
.. note::
|
||||
|
||||
Note that you can regularly type the following command in the same directory
|
||||
to keep your local files in sync with the release branch:
|
||||
Use :ref:`bitbake:ref-bbsetup-command-list` to get an overview of the settings.
|
||||
|
||||
.. code-block:: shell
|
||||
:ref:`bitbake:ref-bbsetup-command-init` is an interactive program by default and
|
||||
will ask you to make some decisions. Depending on your answers, the output may
|
||||
differ from the examples below.
|
||||
|
||||
$ git pull
|
||||
#. Choose a configuration (for example, ``poky-master``):
|
||||
|
||||
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.
|
||||
.. code-block:: shell
|
||||
|
||||
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 :term:`bitbake:Setup` in the
|
||||
:term:`bitbake: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:`bitbake:BitBake Build` directory, named ``build``. Later, when the
|
||||
build completes, this directory contains all the files created during the
|
||||
build.
|
||||
|
||||
This directory also contains a ``README``, describing the current
|
||||
configuration and showing some instructions.
|
||||
|
||||
- The :term:`layers <Layer>` needed to build the Poky reference distribution,
|
||||
in the ``layers`` directory.
|
||||
|
||||
- A ``config`` directory, representing the current configuration used for this
|
||||
:term:`bitbake:setup`.
|
||||
|
||||
Building Your Image
|
||||
===================
|
||||
@ -182,86 +225,74 @@ 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 :term:`bitbake:BitBake build` directory
|
||||
to setup the :term:`BitBake` build environment on your host:
|
||||
|
||||
.. code-block:: shell
|
||||
.. code-block:: shell
|
||||
|
||||
$ 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.
|
||||
$ source poky-master-poky-distro_poky-machine_qemux86-64/build/init-build-env
|
||||
Poky reference distro build
|
||||
|
||||
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.
|
||||
#. **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:`bitbake:BitBake 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>`:
|
||||
|
||||
The Yocto Project has extensive documentation about OE including a reference
|
||||
manual which can be found at:
|
||||
https://docs.yoctoproject.org
|
||||
.. code-block:: shell
|
||||
|
||||
For more information about OpenEmbedded see their website:
|
||||
https://www.openembedded.org/
|
||||
$ bitbake-config-build list-fragments
|
||||
|
||||
### Shell environment set up for builds. ###
|
||||
For this configuration, the default is to use two :term:`Built-in Fragments
|
||||
<Built-in Fragment>`:
|
||||
|
||||
You can now run 'bitbake <target>'
|
||||
- ``distro/poky`` sets the :term:`DISTRO` to :term:`Poky`
|
||||
(:ref:`ref-fragments-builtin-core-distro` fragment).
|
||||
- ``machine/qemux86-64`` sets the :term:`MACHINE` to ``qemux86-64``
|
||||
(:ref:`ref-fragments-builtin-core-machine` fragment).
|
||||
|
||||
Common targets are:
|
||||
core-image-minimal
|
||||
core-image-full-cmdline
|
||||
core-image-sato
|
||||
core-image-weston
|
||||
meta-toolchain
|
||||
meta-ide-support
|
||||
These fragment values correspond to the choices made when running
|
||||
:ref:`bitbake:ref-bbsetup-command-init`.
|
||||
|
||||
You can also run generated QEMU images with a command like 'runqemu qemux86-64'
|
||||
.. note::
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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.
|
||||
The current configuration does not allow the ``root`` user to login. As this
|
||||
can be useful for development, you can enable the
|
||||
:ref:`ref-fragments-root-login-with-empty-password` fragment:
|
||||
|
||||
#. **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.
|
||||
.. code-block:: shell
|
||||
|
||||
.. tip::
|
||||
$ bitbake-config-build enable-fragment root-login-with-empty-password
|
||||
|
||||
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.
|
||||
.. note::
|
||||
|
||||
To use such mirrors, uncomment the below lines in your ``conf/local.conf``
|
||||
file in the :term:`Build Directory`::
|
||||
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.
|
||||
|
||||
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"
|
||||
To use such mirrors, enable the
|
||||
:ref:`ref-fragments-core-yocto-sstate-mirror-cdn` fragment::
|
||||
|
||||
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``.
|
||||
$ bitbake-config-build enable-fragment core/yocto/sstate-mirror-cdn
|
||||
|
||||
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``. You can otherwise
|
||||
install a :term:`Buildtools` tarball by following the instructions in
|
||||
the :ref:`system-requirements-buildtools` section of the Yocto Project
|
||||
Reference Manual.
|
||||
|
||||
#. **Start the Build:** Continue with the following command to build an OS
|
||||
image for the target, which is ``core-image-sato`` in this example:
|
||||
@ -308,82 +339,73 @@ modular development and makes it easier to reuse the layer metadata.
|
||||
|
||||
By convention, layer names start with the string "meta-".
|
||||
|
||||
Follow these steps to add a hardware layer:
|
||||
Follow these steps to add a :ref:`BSP layer <overview-manual/concepts:bsp
|
||||
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 BSP layers are available. The
|
||||
:oe_layerindex:`layer index <>` can be used to find such layers. This example
|
||||
adds the :yocto_git:`meta-raspberrypi </meta-raspberrypi>` 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:
|
||||
First, clone the layer next the other layers::
|
||||
|
||||
git clone -b &DISTRO_NAME_NO_CAP; https://git.yoctoproject.org/meta-raspberrypi ../layers/meta-raspberrypi
|
||||
|
||||
#. **Add Your Layer to the Layer Configuration File:** Before you can use
|
||||
it, you must add the layer and its dependencies it to your ``bblayers.conf``
|
||||
file, which is found in the :term:`Build Directory` (``conf/``) directory.
|
||||
|
||||
For this, the ``bitbake-layers add-layer`` can be used:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ bitbake-layers add-layer ../layers/meta-raspberrypi
|
||||
|
||||
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 is defined by the :ref:`ref-fragments-builtin-core-machine`
|
||||
fragment. For this example, the meta-raspberrypi layer provides the
|
||||
:yocto_git:`raspberrypi5 </meta-yocto/tree/meta-yocto-bsp/conf/machine/beaglebone-yocto.conf>`
|
||||
machine, so let's make it the :term:`MACHINE` used for the build with
|
||||
``bitbake-config-build``:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ bitbake-config-build enable-fragment machine/raspberrypi5
|
||||
|
||||
.. note::
|
||||
|
||||
See the "Examine Your Current Configuration" step earlier for more
|
||||
information on configuring the build.
|
||||
|
||||
The ``raspberrypi5`` build depends on non-free firmware
|
||||
(https://github.com/RPi-Distro/firmware-nonfree) that includes the
|
||||
`Synaptics` license. See the :yocto_git:`ipcompliance.md
|
||||
</meta-raspberrypi/tree/docs/ipcompliance.md>` document for more information.
|
||||
Add the ``synaptics-killswitch`` value to the :term:`LICENSE_FLAGS_ACCEPTED`
|
||||
variable, in the ``conf/local.conf`` file of your build directory::
|
||||
|
||||
LICENSE_FLAGS_ACCEPTED = "synaptics-killswitch"
|
||||
|
||||
#. **Start The Build:** The configuration is now set to build for the Raspberry
|
||||
Pi 5. Start the build again:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ 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.
|
||||
$ bitbake core-image-sato
|
||||
|
||||
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.
|
||||
|
||||
.. note::
|
||||
|
||||
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.
|
||||
|
||||
#. **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.
|
||||
|
||||
.. note::
|
||||
|
||||
See the "Examine Your Local Configuration File" step earlier for more
|
||||
information on configuring the build.
|
||||
|
||||
#. **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.
|
||||
|
||||
Use the ``bitbake-layers add-layer`` command to add the layer to the
|
||||
configuration file:
|
||||
|
||||
.. 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-raspberrypi`` layer to your Yocto
|
||||
Project development environment and configured it to build for the
|
||||
``cyclone5`` machine.
|
||||
``raspberrypi5`` 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 ``raspberrypi5`` machine, you
|
||||
should read the ``README.md`` file in ``meta-raspberrypi``.
|
||||
|
||||
Creating Your Own General Layer
|
||||
===============================
|
||||
@ -396,14 +418,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
|
||||
|
||||
@ -372,6 +372,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``
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user