summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorRichard Purdie <richard.purdie@linuxfoundation.org>2021-07-29 23:09:45 +0100
committerRichard Purdie <richard.purdie@linuxfoundation.org>2021-07-30 22:49:15 +0100
commit0d527052cbc73d177d23efcda1e53f28ec9aedf5 (patch)
treec2af44c27a02d7d1aa678f66876f761d3a7d9638 /documentation
parenteb31b774b15cd29316c3ae6ee2a96d9aa625ca64 (diff)
downloadpoky-0d527052cbc73d177d23efcda1e53f28ec9aedf5.tar.gz
migration-guides: Add start of 3.4 guide with override migration notes
(From yocto-docs rev: e60019c81e63250feaee4937873a90042074030b) Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org> Reviewed-by: Quentin Schulz <foss@0leil.net> Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/migration-guides/index.rst1
-rw-r--r--documentation/migration-guides/migration-3.4.rst76
2 files changed, 77 insertions, 0 deletions
diff --git a/documentation/migration-guides/index.rst b/documentation/migration-guides/index.rst
index 6304e6318c..287b553195 100644
--- a/documentation/migration-guides/index.rst
+++ b/documentation/migration-guides/index.rst
@@ -12,6 +12,7 @@ to move to one release of the Yocto Project from the previous one.
12.. toctree:: 12.. toctree::
13 13
14 migration-general 14 migration-general
15 migration-3.4
15 migration-3.3 16 migration-3.3
16 migration-3.2 17 migration-3.2
17 migration-3.1 18 migration-3.1
diff --git a/documentation/migration-guides/migration-3.4.rst b/documentation/migration-guides/migration-3.4.rst
new file mode 100644
index 0000000000..6fa1ab20cb
--- /dev/null
+++ b/documentation/migration-guides/migration-3.4.rst
@@ -0,0 +1,76 @@
1Release 3.4 (honister)
2======================
3
4This section provides migration information for moving to the Yocto
5Project 3.4 Release (codename "honister") from the prior release.
6
7Override syntax changes
8-----------------------
9
10This release requires changes to the metadata to indicate where overrides are
11being used in variable key names. This is done with the ``:`` character replacing
12the use of ``_`` previously. This means that an entry like::
13
14 SRC_URI_qemux86 = "file://somefile"
15
16becomes::
17
18 SRC_URI:qemux86 = "file://somefile"
19
20since ``qemux86`` is an override. This applies to any use of override syntax so::
21
22 SRC_URI_append = " file://somefile"
23 SRC_URI_append_qemux86 = " file://somefile2"
24 SRC_URI_remove_qemux86-64 = " file://somefile3"
25 SRC_URI_prepend_qemuarm = "file://somefile4 "
26 FILES_${PN}-ptest = "${bindir}/xyz"
27 IMAGE_CMD_tar = "tar"
28 BASE_LIB_tune-cortexa76 = "lib"
29 SRCREV_pn-bash = "abc"
30 BB_TASK_NICE_LEVEL_task-testimage = '0'
31
32becomes::
33
34 SRC_URI:append = " file://somefile"
35 SRC_URI:append:qemux86 = " file://somefile2"
36 SRC_URI:remove:qemux86-64 = " file://somefile3"
37 SRC_URI:prepend:qemuarm = "file://somefile4 "
38 FILES:${PN}-ptest = "${bindir}/xyz"
39 IMAGE_CMD:tar = "tar"
40 BASE_LIB:tune-cortexa76 = "lib"
41 SRCREV:pn-bash = "abc"
42 BB_TASK_NICE_LEVEL:task-testimage = '0'
43
44This also applies to
45:ref:`variable queries to the datastore <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:functions for accessing datastore variables>`,
46for example using ``getVar`` and similar so ``d.getVar("RDEPENDS_${PN}")``
47becomes ``d.getVar("RDEPENDS:${PN}")``.
48
49Whilst some of these are fairly obvious such as :term:`MACHINE` and :term:`DISTRO`
50overrides, some are less obvious, for example the packaging variables such as
51:term:`RDEPENDS`, :term:`FILES` and so on taking package names (e.g. ``${PN}``,
52``${PN}-ptest``) as overrides. These overrides are not always in
53:term:`OVERRIDES` but applied conditionally in specific contexts
54such as packaging. ``task-<taskname>`` is another context specific override, the
55context being specific tasks in that case. Tune overrides are another special
56case where some code does use them as overrides but some does not. We plan to try
57and make the tune code use overrides more consistently in the future.
58
59To help with migration of layers there is a script in OE-Core. Once configured
60with the overrides used by a layer, this can be run as::
61
62 <oe-core>/scripts/contrib/convert-overrides.py <layerdir>
63
64.. note::
65
66 Please read the notes in the script as it isn't entirely automatic and it isn't
67 expected to handle every case. In particular, it needs to be told which overrides
68 the layer uses (usually machine and distro names/overrides) and the result should
69 be carefully checked since it can be a little enthusiastic and will convert
70 references to ``_append``, ``_remove`` and ``_prepend`` in function and variables names.
71
72For reference, this conversion is important as it allows BitBake to know what is
73an override and what is not. This should allow us to proceed with other syntax
74improvements and simplifications for usability. It also means bitbake no longer
75has to guess and maintain large lookup lists just in case ``functionname`` in
76``my_functionname`` is an override and this should improve efficiency.