diff options
Diffstat (limited to 'poky/documentation/migration-guides')
6 files changed, 89 insertions, 5 deletions
diff --git a/poky/documentation/migration-guides/index.rst b/poky/documentation/migration-guides/index.rst index 6304e6318..287b55319 100644 --- a/poky/documentation/migration-guides/index.rst +++ b/poky/documentation/migration-guides/index.rst @@ -12,6 +12,7 @@ to move to one release of the Yocto Project from the previous one. .. toctree:: migration-general + migration-3.4 migration-3.3 migration-3.2 migration-3.1 diff --git a/poky/documentation/migration-guides/migration-1.4.rst b/poky/documentation/migration-guides/migration-1.4.rst index 3f980915c..baf3c0837 100644 --- a/poky/documentation/migration-guides/migration-1.4.rst +++ b/poky/documentation/migration-guides/migration-1.4.rst @@ -83,7 +83,7 @@ create an append file for the ``init-ifupdown`` recipe instead, which you can find in the :term:`Source Directory` at ``meta/recipes-core/init-ifupdown``. For information on how to use append files, see the -":ref:`dev-manual/common-tasks:using .bbappend files in your layer`" +":ref:`dev-manual/common-tasks:appending other layers metadata with your layer`" section in the Yocto Project Development Tasks Manual. .. _migration-1.4-remote-debugging: diff --git a/poky/documentation/migration-guides/migration-1.5.rst b/poky/documentation/migration-guides/migration-1.5.rst index e1ba4a9a1..11c821265 100644 --- a/poky/documentation/migration-guides/migration-1.5.rst +++ b/poky/documentation/migration-guides/migration-1.5.rst @@ -144,7 +144,7 @@ Shortened Git ``SRCREV`` Values BitBake will now shorten revisions from Git repositories from the normal 40 characters down to 10 characters within :term:`SRCPV` -for improved usability in path and file names. This change should be +for improved usability in path and filenames. This change should be safe within contexts where these revisions are used because the chances of spatially close collisions is very low. Distant collisions are not a major issue in the way the values are used. diff --git a/poky/documentation/migration-guides/migration-2.4.rst b/poky/documentation/migration-guides/migration-2.4.rst index cab81356d..ae1a212b5 100644 --- a/poky/documentation/migration-guides/migration-2.4.rst +++ b/poky/documentation/migration-guides/migration-2.4.rst @@ -286,8 +286,8 @@ The following are additional changes: - BitBake fires multiple "BuildStarted" events when multiconfig is enabled (one per configuration). For more information, see the - ":ref:`Events <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:events>`" section in the BitBake User - Manual. + ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:events`" + section in the BitBake User Manual. - By default, the ``security_flags.inc`` file sets a :term:`GCCPIE` variable with an option to enable diff --git a/poky/documentation/migration-guides/migration-3.0.rst b/poky/documentation/migration-guides/migration-3.0.rst index 20c7026e8..9a5f5714b 100644 --- a/poky/documentation/migration-guides/migration-3.0.rst +++ b/poky/documentation/migration-guides/migration-3.0.rst @@ -194,7 +194,7 @@ The following BitBake changes have occurred. scripts that handles these two events need to be updated. - The arguments passed to functions used with - :term:`bitbake:BB_HASHCHECK_FUNCTION` + :term:`BB_HASHCHECK_FUNCTION` have changed. If you are using your own custom hash check function, see :yocto_git:`/poky/commit/?id=40a5e193c4ba45c928fccd899415ea56b5417725` for details. diff --git a/poky/documentation/migration-guides/migration-3.4.rst b/poky/documentation/migration-guides/migration-3.4.rst new file mode 100644 index 000000000..e83e936b7 --- /dev/null +++ b/poky/documentation/migration-guides/migration-3.4.rst @@ -0,0 +1,83 @@ +Release 3.4 (honister) +====================== + +This section provides migration information for moving to the Yocto +Project 3.4 Release (codename "honister") from the prior release. + +Override syntax changes +----------------------- + +This release requires changes to the metadata to indicate where overrides are +being used in variable key names. This is done with the ``:`` character replacing +the use of ``_`` previously. This means that an entry like:: + + SRC_URI_qemux86 = "file://somefile" + +becomes:: + + SRC_URI:qemux86 = "file://somefile" + +since ``qemux86`` is an override. This applies to any use of override syntax so:: + + SRC_URI_append = " file://somefile" + SRC_URI_append_qemux86 = " file://somefile2" + SRC_URI_remove_qemux86-64 = " file://somefile3" + SRC_URI_prepend_qemuarm = "file://somefile4 " + FILES_${PN}-ptest = "${bindir}/xyz" + IMAGE_CMD_tar = "tar" + BASE_LIB_tune-cortexa76 = "lib" + SRCREV_pn-bash = "abc" + BB_TASK_NICE_LEVEL_task-testimage = '0' + +becomes:: + + SRC_URI:append = " file://somefile" + SRC_URI:append:qemux86 = " file://somefile2" + SRC_URI:remove:qemux86-64 = " file://somefile3" + SRC_URI:prepend:qemuarm = "file://somefile4 " + FILES:${PN}-ptest = "${bindir}/xyz" + IMAGE_CMD:tar = "tar" + BASE_LIB:tune-cortexa76 = "lib" + SRCREV:pn-bash = "abc" + BB_TASK_NICE_LEVEL:task-testimage = '0' + +This also applies to +:ref:`variable queries to the datastore <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:functions for accessing datastore variables>`, +for example using ``getVar`` and similar so ``d.getVar("RDEPENDS_${PN}")`` +becomes ``d.getVar("RDEPENDS:${PN}")``. + +Whilst some of these are fairly obvious such as :term:`MACHINE` and :term:`DISTRO` +overrides, some are less obvious, for example the packaging variables such as +:term:`RDEPENDS`, :term:`FILES` and so on taking package names (e.g. ``${PN}``, +``${PN}-ptest``) as overrides. These overrides are not always in +:term:`OVERRIDES` but applied conditionally in specific contexts +such as packaging. ``task-<taskname>`` is another context specific override, the +context being specific tasks in that case. Tune overrides are another special +case where some code does use them as overrides but some does not. We plan to try +and make the tune code use overrides more consistently in the future. + +There are some variables which do not use override syntax which include the +suffix to variables in ``layer.conf`` files such as :term:`BBFILE_PATTERN`, +:term:`SRCREV`\ ``_xxx`` where ``xxx`` is a name from :term:`SRC_URI` and +:term:`PREFERRED_VERSION`\ ``_xxx``. In particular, ``layer.conf`` suffixes +may be the same as a :term:`DISTRO` override causing some confusion. We do +plan to try and improve consistency as these issues are identified. + +To help with migration of layers there is a script in OE-Core. Once configured +with the overrides used by a layer, this can be run as:: + + <oe-core>/scripts/contrib/convert-overrides.py <layerdir> + +.. note:: + + Please read the notes in the script as it isn't entirely automatic and it isn't + expected to handle every case. In particular, it needs to be told which overrides + the layer uses (usually machine and distro names/overrides) and the result should + be carefully checked since it can be a little enthusiastic and will convert + references to ``_append``, ``_remove`` and ``_prepend`` in function and variables names. + +For reference, this conversion is important as it allows BitBake to know what is +an override and what is not. This should allow us to proceed with other syntax +improvements and simplifications for usability. It also means bitbake no longer +has to guess and maintain large lookup lists just in case ``functionname`` in +``my_functionname`` is an override and this should improve efficiency. |