Skip to content

Commit

Permalink
Cleanup lmp-extending user guide
Browse files Browse the repository at this point in the history 
Typos fixed and style rules applied, other small changes to increase
readability.

QA Steps: Checked rendered HTML, no issues seen. Ran linter within
editor, no new issues discovered.

No related ticket, quick fix.

Signed-off-by: Katrina Prosise <[email protected]>
  • Loading branch information
@kprosise
kprosise committed Jun 13, 2024
1 parent 0a2c5c3 commit 41b27fa
Showing 1 changed file with 44 additions and 46 deletions.
90 changes: 44 additions & 46 deletions source/user-guide/lmp-customization/linux-extending.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ For a quick example let us add the ``stress-ng`` utility package to the build:
git clone https://source.foundries.io/factories/<myfactory>/meta-subscriber-overrides.git
vi meta-subscriber-overrides/recipes-samples/images/lmp-factory-image.bb
Add "stress-ng" to the package list.::
Add "stress-ng" to the package list::

vim \
stress-ng \
Expand All @@ -36,22 +36,24 @@ You can check the status at:

``https://ci.foundries.io/projects/<myfactory>/lmp/``

Once completed, the device will reboot after the update is applied.
This behavior is customizable so that you can apply rules to determine when devices should be restarted.
Once restarted the stress-ng command will be available.
Once completed and the update is applied, the device will reboot.
This behavior is customizable; you can apply rules to determine when devices should restart.
Once restarted, the ``stress-ng`` command will be available.

List of Available Recipes
-------------------------
OE provides a tool_ to search layers and recipes.

OE provides a `tool`_ to search layers and recipes.
Remember to set the same branch name used by the current factory version.

.. _tool:
https://layers.openembedded.org/layerindex/branch/master/layers/

Creating a Python3 Package from PyPi
------------------------------------
There are Python packages that do not yet have a recipe for python3 in OE.
If this is the case with a desired package, use this template below to add a new package from PyPi.

Some Python packages do not yet have a recipe for python3 in OE.
If this is the case with a desired package, use the template below to add a new package from PyPi.

Create a recipe in the **meta-subscriber-overrides.git** repository using the following naming scheme:

Expand Down Expand Up @@ -80,7 +82,7 @@ Example file contents::
python3-dateutil \
"

Using the information and packages at the PyPi website, you can fill in the details about the new Python package
Using the information and packages from the PyPi website, fill in the details about the new Python package

.. figure:: /_static/pypi-package.png
:alt: Pypi package
Expand All @@ -89,7 +91,7 @@ Using the information and packages at the PyPi website, you can fill in the deta

Pypi package

Update the following variables to reflect the details from the package you wish to create a recipe for.
Update the following variables to reflect the details for the package you wish to create a recipe for.

#. ``DESCRIPTION``
#. ``HOMEPAGE``
Expand All @@ -100,37 +102,36 @@ Update the following variables to reflect the details from the package you wish
#. ``DEPENDS`` Dependencies resolved at do_configure
#. ``RDEPENDS`` Dependencies resolved at do_build

Using FEATURES to configure LmP
-------------------------------
Using ``FEATURES`` to Configure LmP
-----------------------------------

There are three features variable we can use to control and configure the build system: ``DISTRO_FEATURES``, ``IMAGE_FEATURES`` and ``MACHINE_FEATURES``.
Each one of them takes effect in one aspect of the build system.
Three "features" variables control and configure the build system: ``DISTRO_FEATURES``, ``IMAGE_FEATURES`` and ``MACHINE_FEATURES``.
Each one takes effect in a single aspect of the build system.

.. important::

When changing ``DISTRO_FEATURES``, the distro is changed and it results in
rebuild of several packages which can take a while.

When changing ``MACHINE_FEATURES``, the hardware description changes and it
result in different group of packages being installed in the image.
When changing ``DISTRO_FEATURES``, the distro changes.
This results in the rebuilding of packages, which can take a while.

When changing ``IMAGE_FEATURES``, the image changes, and it may reflect on the
list of packages installed, or in the image configuration.
When changing ``MACHINE_FEATURES``, the hardware description changes.
This results in a different group of packages installing to the image.

Make sure to understand what will be the result in case of any change.
When changing ``IMAGE_FEATURES``, the image changes.
This may reflect in the list of packages installed, or in the image configuration.

DISTRO_FEATURES is a list of configurations from a distro that reflects how some packages are built or installed.
There is a list of `Yocto Project distro features`_ supported.
However, the list can be expanded by other meta layers.
Make sure you understand the result of any change.

For example, the distro feature ``systemd`` or ``wayland`` are used to define the list of packages to be installed, and to configure how some packages build.
The distro feature ``modsign`` is used along with certificates to sign the kernel modules.
``DISTRO_FEATURES`` is a list of configurations from a distro that reflects how some packages build or install.
While there is a list of `Yocto Project distro features`_ supported, the list can expand by including other meta layers.
For example, the distro features ``systemd`` or ``wayland`` define the list of packages to install, and configures how some packages build.
The distro feature ``modsign``,along with certificates, signs the kernel modules.

The default value used by LmP is defined in the ``meta-lmp/meta-lmp-base/conf/distro/include/lmp.inc`` and can be customized by architecture, machine, or any other override.
To customize it, use ``DISTRO_FEATURES:append = <value>`` to add a feature to the list, and ``DISTRO_FEATURES:remove = <value>`` to remove a feature from the list.
The default value used by LmP is defined in ``meta-lmp/meta-lmp-base/conf/distro/include/lmp.inc``.
This can be customized by architecture, machine, or any other override.
To customize, use ``DISTRO_FEATURES:append = <value>`` to add a feature, and ``DISTRO_FEATURES:remove = <value>`` to remove one.
To remove a feature from an override list, use ``DISTRO_FEATURES:remove:<machine> = <value>``.

The command ``bitbake-getvar`` can be used to see the value of some variables, and all the intermediate values::
Use the command ``bitbake-getvar`` to see the value of some variables, and all the intermediate values::

$ bitbake-getvar DISTRO_FEATURES
NOTE: Starting bitbake server...
Expand All @@ -155,16 +156,18 @@ The command ``bitbake-getvar`` can be used to see the value of some variables, a
DISTRO_FEATURES="acl argp bluetooth ext2 ipv4 ipv6 largefile usbgadget usbhost wifi xattr zeroconf pci vfat modsign efi security tpm integrity seccomp pam usrmerge virtualization ptest
alsa sota systemd"

The log is generated using ``DISTRO="lmp"``. The ``DISTRO_FEATURES`` changed with seven operations and only one of them is for an override (``tegra``).
The log also shows the file path and line for each operation.
Using ``DISTRO="lmp"`` generates the log.
``DISTRO_FEATURES`` changes seven operations and one of them is for an override (``tegra``).
The log also shows file path and line for each operation.

The line starting with ``DISTRO_FEATURES=`` show the variable value.

The Yocto Project also provides ``IMAGE_FEATURES`` and ``MACHINE_FEATURES``, a list of features for the image and to describe the machine.
There is a list of `Yocto Project image features`_ and `Yocto Project machine features`_ supported by the project.
The Yocto Project also provides ``IMAGE_FEATURES`` and ``MACHINE_FEATURES``.
These are lists of features for the image and to describe the machine, respectively.
There is also lists of `Yocto Project image features`_ and `Yocto Project machine features`_ supported by the project.

The LmP uses the ``MACHINE_FEATURES`` from a machine to define if a package is included.
For example, the OP-Tee package is only included in an image if the target machine includes the feature ``optee`` in ``MACHINE_FEATURE``.
The LmP uses the ``MACHINE_FEATURES`` for a machine to determine if a package gets included.
For example, the OP-Tee package is only included in an image if the target machine includes the feature ``optee`` within ``MACHINE_FEATURES``.

.. _Yocto Project distro features:
https://docs.yoctoproject.org/kirkstone/ref-manual/features.html#distro-features
Expand All @@ -180,28 +183,23 @@ For example, the OP-Tee package is only included in an image if the target machi
Including Private Git+ssh Repositories
--------------------------------------

Sometimes custom recipes need access to private Git repositories that
are only available via SSH. The ci-scripts_ repository has logic to
handle this when a Factory has secrets created using a simple naming
convention.
Custom recipes may need access to private Git repositories only available via SSH.
The ci-scripts_ repo has logic to handle this when a Factory has secrets created using a simple naming convention.

.. _ci-scripts:
https://github.com/foundriesio/ci-scripts/blob/master/lmp/bb-build.sh

Every secret matching the pattern ``ssh-*.key`` will be loaded into an
ssh-agent and ``ssh-known_hosts`` will be used to set the trusted
host keys for the Git server(s).
Secrets matching the pattern ``ssh-*.key`` are loaded into an ssh-agent, and ``ssh-known_hosts`` is used to sets the trusted host keys for the Git server(s).

For the ``ssh-known_host`` it can be generated like this::
To generate ``ssh-known_hosts``::

$ ssh-keyscan github.com > /tmp/ssh-known_hosts

For example, a private GitHub repository could be accessed with::
An example for accessing a private GitHub repo::

$ fioctl secrets update ssh-github.key==/tmp/ssh-github.key
$ fioctl secrets update ssh-known_hosts==/tmp/ssh-known_hosts

At that point new CI jobs will be able to access recipes that have
``SRC_URI`` items like::
At this point new CI jobs will be able to access recipes that have ``SRC_URI`` items like::

SRC_URI = "git://[email protected]/<repo>;protocol=ssh;branch=main"

0 comments on commit 41b27fa

Please sign in to comment.