isar-kylin-addpackage/RECIPE-API-CHANGELOG.md

Recipe API Changelog

Baseline: Release v0.5

Changes in v0.6

Separate do_prepare_build task

All Debianizations of source trees and any further programmatic patching has to be moved from the dpkg_runbuild() task to this new task.

ISAR_CROSS_COMPILE support

Isar now supports cross-compilation. When enabled via ISAR_CROSS_COMPILE = "1" in a global configuration file, all recipes that do not overwrite this variable will build cross-compiled.

If a recipe is not cross-compatible, it should set ISAR_CROSS_COMPILE = "0". Then also all its dependencies that are built by Isar must opt out from cross-building.

wic image type, removal of manual wic invocation

Images that are described by wic files are now generated during the build by setting IMAGE_TYPE = "wic-img". The manual invocation of wic after the bitbake run is no longer needed nor supported.

Optional kernel installation

The installation of a Linux kernel into the isar-image-base can be skipped by setting KERNEL_NAME = "".

Corrected semantic of S

The S variable is now defined as NOT including WORKDIR, like in OE, Gentoo and others. If it was set to, e.g., S = "sources" in a recipe so far, it must be defined as S = ${WORKDIR}/sources from now on.

DISTRO and DISTRO_ARCH are available as OVERRIDES

Bitbake variables can now also refer to the DISTRO as well as the DISTRO_ARCH for overrides.

Set ISAR_RELEASE_CMD in own top-layer

Isar now populates /etc/os-release with information about the image. In order to identify the revision of the top layer that controlled the image build with all its dependencies, set ISAR_RELEASE_CMD so that it picks up the required information.

If the top-layer is managed in git, set LAYERDIR_mylayer = "${LAYERDIR}" in conf/layer.conf and add something along

ISAR_RELEASE_CMD = "git -C ${LAYERDIR_mylayer} describe --tags --dirty \
                        --match 'v[0-9].[0-9]*'"

in the image recipe (or isar-image-base.bbappend) of that layer.

ROOTFS_DEV and ROOTFS_TYPE no longer needed

These variables can be removed from own machine.conf or multiconfig files.

If you want to enable support for QEMU in your config (start_vm), specify the QEMU_ROOTFS_DEV and QEMU_DISK_ARGS instead.

KERNEL_NAME_PROVIDED replaces KERNEL_FLAVOR in custom kernels

The matching logic for custom kernel recipes to the selected kernel was reworked and simplified. If your kernel recipe is called linux-foo_4.18.bb, you now have to set KERNEL_NAME = "foo" in order to select that kernel. Alternatively, a recipe with a different naming scheme can set KERNEL_NAME_PROVIDED = "foo" in order to match as well.

Changes in v0.7

dpkg-raw recipes build method changed

These packages are now built using the whole dpkg-buildpackage workflow, and not just packaged as before.

• all files will be owned by root:root before it might have been 1000:1000 use postinst to change that (see example-raw)
• a lot of debhelpers will help .. or complain fix the issues or override the helpers (see example-raw)

Set LAYERSERIESCOMPAT* when an own layer is defined

When defining an own layer LAYERSERIES_COMPAT_mylayer_root_name has to be set, the possible values are listed in the variable LAYERSERIES_CORENAMES.

If you need to express the fact that your layer requires the layer version higher than existing release corename, use the value 'next'.

location of image artifacts

Align with OpenEmbedded and place image artifacts in a per-machine folder placed in tmp/deploy (to avoid collisions among other things).

more consistent artifact names

multiconfig image artifacts are all placed in tmp/deploy/images. They include kernel, initrd and ext4/wic images. A consistent naming scheme is now used: IMAGE-DISTRO-MACHINE.TYPE. This scheme was already used for ext4/wic images so no visible changes there. Kernel and initrd images are however affected; for instance:

vmlinuz-4.9.0-8-armmp_debian-stretch-qemuarm

is now

isar-image-base-debian-stretch-qemuarm.vmlinuz-4.9.0-8-armmp

It should be noted that the KERNEL_IMAGE and INITRD_IMAGE variables were updated hence recipes using them shouldn't be impacted per se.

Append kernel name to custom module and u-boot-script packages

These packages depend on a specific kernel. Its identification is now appended to the binary package names in the form "-${KERNEL_NAME}".

PRESERVE_PERMS needed with dpkg-raw for implicit file permission setting

In order to use the same file permissions for an input file to a dpkg-raw package on the build machine as well as on the target, its absolute target path needs to be listed in the PRESERVE_PERMS variable (space-separated list of files). Otherwise, default permissions are used.

Reduce requirements on custom module makefiles

It's now sufficient to provide only kbuild rules. Makefile targets like modules or modules_install as well as KDIR and DESTDIR evaluation are no longer needed.

Remove setting of root passwords in custom packages

Custom packages that are not installed via the IMAGE_TRANSIENT_PACKAGES and set a root password, leak that password via its script in /var/lib/dpkg/info.

Instead set the CFG_ROOT_PW variable to the encrypted password and use the transient 'isar-cfg-rootpw' package (now installed as transient package per default).

Changes in v0.8

apt:// SRC_URIs where added and briefly changed their version picking way

Recipes that use SRC_URIs with apt:// and choose a version with = had a partial matching feature for a short time between 0.7 and 0.8. In 0.8 the version has to be the exact upsteam match. It is probably best to not specify a version if you can.

isar-image.bbclass class will be deprecated in future version of isar

The content of isar-image.bbclass was moved to the image.bbclass file. Recipes that inherit isar-image should be modified to inherit from image instead.

Transient package support was removed

The LOCALE_GEN and LOCALE_DEFAULT variables are now handled by the image-locales-extension class within the image recipe.

Setting of the root password can now be done by the image-account-extension class within the image recipe. To set the root password to empty, you can use this code snippet:

USERS += "root"
USER_root[password] = ""
USER_root[flags] = "allow-empty-password"

Otherwise set a encrypted root password like this:

USERS += "root"
USER_root[password] = "$6$rounds=10000$RXeWrnFmkY$DtuS/OmsAS2cCEDo0BF5qQsizIrq6jPgXnwv3PHqREJeKd1sXdHX/ayQtuQWVDHe0KIO0/sVH8dvQm1KthF0d/"

Use FILESEXTRAPATHS to add custom paths to FILESPATH

Direct modification of FILESPATH variable is discouraged. Use FILESEXTRAPATHS instead to add a custom search path for files and patches. This makes overriding files and patches using bbappend a lot easier.

For example:

FILESEXTRAPATHS_prepend := "$THISDIR/files:"

multiconfig build targets were renamed

bitbake was upgraded to version 1.44.0 where "multiconfig" build targets were renamed "mc". As an example, builds for the qemuarm-stretch machine should now be done as follows:

bitbake mc:qemuarm-stretch:isar-image-base

The old syntax is no longer supported and will produce an error:

bitbake multiconfig:qemuarm-stretch:isar-image-base

Support for kernel config fragments

Kernels built via linux-custom.inc will now get configuration fragments listed in SRC_URI automatically applied. Config fragment files need to end on .cfg. If such a file should not by applied, append ;apply=no to the respective SRC_URI entry.

Control over kernel's LOCALVERSION via LINUX_VERSION_EXTENSION

In order to get a LOCALVERSION appendix into both the kernel config and the version information of the self-built packages, the LINUX_VERSION_EXTENSION is now available. It remains empty by default unless a recipe sets it. The appended version usually starts with a "-".

Image task cache_base_repo was removed

That task used to be at the end of a cache-warming build, a follow-up build with ISAR_USE_CACHED_BASE_REPO did use that. Now we cache all downloads anyway, if ISAR_USE_CACHED_BASE_REPO is set a build will use all the downloads from previous builds for the cache.

Renamed DTB_FILE to DTB_FILES, adding support for multiple entries

DTB_FILES now allows to specify multiple DTBs that should be deployed for consumption by imaging classes.

Add DEBIAN_BUILD_DEPENDS as deb_debianize parameter

Additional build dependencies of auto-debianized packages can now be defined by setting DEBIAN_BUILD_DEPENDS.

Separation of ${S} and ${D} in dpkg-raw

${S} can now be used for checking out sources without being linked implicitly with ${D} which needs to be filled explicitly in do_install as before.

Remove ISARROOT from bitbake environment

ISARROOT variable is now removed from the bitbake environment. It is unset after the initial setup. It is replaced with dedicated variables like BITBAKEDIR, SCRIPTSDIR and TESTSUITEDIR.

Wic adds /boot mountpoint to fstab

In the older version of wic, any mount point named /boot is skipped from adding into the fstab entry.

With the latest wic, this is not the case. /boot mount point, if any, is added to /etc/fstab for automount.

Any wks file which assumed that /boot would be skipped from /etc/fstab should now be corrected. Otherwise, it might conflict with the original /boot contents, i.e kernel initrd & config files will be unavailable after boot.

Below is an example wks entry that might cause an issue. The efi partition created using bootimg-efi-isar plugin has only the efi stub in it. The kernel and initrd are present in the root(/) partition. Now with the latest wic which adds the /boot mount point to fstab, the /boot contents of "part /" would be unavailable after boot. This would break the kernel updates done via apt-get.

part /boot --source bootimg-efi-isar --sourceparams "loader=grub-efi" --ondisk sda --label efi --part-type EF00 --align 1024
part / --source rootfs --ondisk sda --fstype ext4 --label platform --align 1024 --use-uuid

In this case we can either drop the /boot mountpoint or use some other mountpoint like /boot/efi to avoid such issues.

Deprecate BUILD_DEPENDS in u-boot-custom.inc

Use DEBIAN_BUILD_DEPENDS instead, to align with deb_debianize.

Default to PATCHTOOL ?= "git" for dpkg-gbp

Migrate your patches so they can be applied with "git am", or "unset PATCHTOOL" to get old behaviour.

Change kernel image name for arm64

Kernel image name for arm64 platforms is vmlinux now. Image format was not changed (uncompressed executable) but now it is named correctly.