Migrating metadata to OE-Core

The classes and BitBake configuration used in OpenEmbedded-Core require a few changes for recipes brought over from OE-Classic (and for new recipes written by developers used to working with OE-Classic).

Mandatory changes

For recipes the following changes are required in order to build successfully:

• Add LIC_FILES_CHKSUM: this specifies one or more files or sections of files from the source that can be used to detect if the license of the software has been changed in a newer version. It is mandatory and checked at the end of do_configure. See Specifying LIC_FILES_CHKSUM for more details.
• Remove legacy staging: legacy staging (do_stage) is no longer supported and BitBake will error out on parse of recipes that use it. Items previously in do_stage should be moved to do_install as appropriate; however they should actually install the files to somewhere under ${D} and not copy them into the staging directory directly or things will break later on.
• Ensure LICENSE is present: the LICENSE field, whilst usually included in most recipes in the past anyway, is now mandatory. It should be as specific and as correct as possible (e.g. "GPLv2", not just "GPL") and try to be consistent with other recipes.
• Ensure SRC_URI checksums are present: for entries in SRC_URI pointing to sources other than SCMs or local files, i.e. http, ftp, etc., at least one SRC_URI checksum (md5sum/sha256sum) must be provided. If these are not present for an entry where it is required you will get an error which gives you the appropriate values to be added to the recipe. You can use the "name=" parameter within SRC_URI to distinguish between multiple entries. (This used to be optional, now it is mandatory.)
• Remove comments in string values: recent versions of BitBake no longer allow comments in multi-line strings, so the tradition of being able to comment out lines within a multi-line SRC_URI or when setting configure flags etc. is no longer allowed. Remove the commented out lines or move them to beyond where the string terminates.
• Ensure values are quoted: the very latest version of BitBake requires that values are quoted; this was optional in the past. Single or double quotes are allowed but all values must now be quoted. (This does not affect how numeric values are interpreted, these have always been treated as strings.)
• Use package name override with R* variables: the runtime dependency variables (RDEPENDS, RRECOMMENDS, RSUGGESTS, RPROVIDES, RCONFLICTS, RREPLACES) should always have a package name override. For example to set a runtime dependency for the main package use RDEPENDS_${PN}.
• Replace oe* logging commands: Any calls to oenote, oewarn, oefatal etc. in shell scripts need to be replaced with the "bb" equivalent, i.e. bbnote, bbwarn, bbfatal etc.
• Use FILESEXTRAPATHS to extend file search path: Modifications to FILESPATHPKG and/or FILESPATH should be replaced by prepending to FILESEXTRAPATHS; in addition, you no longer need to define THISDIR (and should not do so). For example, to add a directory to be searched for patches and other files which is named with PN, do the following (note the immediate evaluation operator := and trailing colon, these are important):

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"

Changes applicable to BitBake 1.15.3 and later:

• Python functions should always use four spaces for indentation and not tabs - a warning will be produced if tabs are found. Previously four spaces was the convention but many python functions used tabs. This has been fixed in OE-Core and other layers, and since python uses indentation for statement blocks and thus it is very important that you make the same changes to python functions in your recipes.
• Change proto= to protocol= in SRC_URI - all fetchers have been changed to be consistent. Previously, some fetchers used proto and some protocol.

Best practices

The following practices are required for patch submission to layers such as OE-Core and meta-oe, and recommended for recipes in your own layers:

• Machine and distro-specific overrides should be removed from recipes for generic layers (especially meta-oe and OE-Core). These can be moved to bbappends in the appropriate machine / distro layer respectively. (Note however that architecture-specific overrides are allowed if necessary.)
• In-tree patches to be applied to the source should have a proper header explaining what the patch does, a valid Signed-off-by, and for OE-Core should have an Upstream-Status indicator.
• Initially reset PR to "r0" (or remove it which amounts to the same thing). PR is definitely still used, but we can start again from r0.
• NATIVE_INSTALL_WORKS for native recipes is no longer used and should be removed.
• PRIORITY is no longer used and should be removed.
• "Bashisms" in shell scripts (particularly those that will be executed on the host) should be avoided. This allows compatibility with alternative shells e.g. Ubuntu's default (dash).