summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-03-07 12:08:00 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-03-25 09:41:11 +0100
commit6cb930c0ead4fc1a9f80a8094ddc79ef56ad2276 (patch)
treeaa6f980856e652a51968604aa22151bf2dec1725 /documentation/dev-manual
parent1fccc4d2ee88827e12655723c3b1781b94da4708 (diff)
downloadpoky-6cb930c0ead4fc1a9f80a8094ddc79ef56ad2276.tar.gz
dev-manual: Added section on manually upgrading recipes
(From yocto-docs rev: b5515ad6f4b5653095e338114607dd11a11181df) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml95
1 files changed, 94 insertions, 1 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 8264331dd1..306ba6d580 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -4156,7 +4156,7 @@
4156 </literallayout> 4156 </literallayout>
4157 </para></listitem> 4157 </para></listitem>
4158 <listitem><para> 4158 <listitem><para>
4159 <emphasis>Clone the AUH Respository:</emphasis> 4159 <emphasis>Clone the AUH Repository:</emphasis>
4160 To use AUH, you must clone the repository onto your 4160 To use AUH, you must clone the repository onto your
4161 development host. 4161 development host.
4162 The following command uses Git to create a local 4162 The following command uses Git to create a local
@@ -4521,6 +4521,99 @@
4521 <section id='dev-manually-upgrading-a-recipe'> 4521 <section id='dev-manually-upgrading-a-recipe'>
4522 <title>Manually Upgrading a Recipe</title> 4522 <title>Manually Upgrading a Recipe</title>
4523 4523
4524 <para>
4525 If for some reason you choose not to upgrade recipes using the
4526 <link linkend='gs-using-the-auto-upgrade-helper'>Auto Upgrade Helper (AUH)</link>
4527 or by using
4528 <link linkend='gs-using-devtool-upgrade'><filename>devtool upgrade</filename></link>,
4529 you can manually edit the recipe files to upgrade the versions.
4530 <note><title>Caution</title>
4531 Manually updating multiple recipes scales poorly and
4532 involves many steps.
4533 The recommendation to upgrade recipe versions is through
4534 AUH or <filename>devtool upgrade</filename>, both of which
4535 automate some steps and provide guidance for others needed
4536 for the manual process.
4537 </note>
4538 </para>
4539
4540 <para>
4541 To manually upgrade recipe versions, follow these general steps:
4542 <orderedlist>
4543 <listitem><para>
4544 <emphasis>Change the Recipe Name:</emphasis>
4545 Adjust the version (i.e.
4546 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>)
4547 part of the recipe name such that it uses the
4548 new version number.
4549 </para></listitem>
4550 <listitem><para>
4551 <emphasis>Update <filename>SRCREV</filename> if Needed:</emphasis>
4552 If the source code your recipe builds is fetched from
4553 Git or some other Version Control System (VCS),
4554 update
4555 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
4556 to point to the commit hash that matches the new
4557 version.
4558 </para></listitem>
4559 <listitem><para>
4560 <emphasis>Build the Software:</emphasis>
4561 Try to build the recipe using BitBake.
4562 Typical build failures include the following:
4563 <itemizedlist>
4564 <listitem><para>
4565 License terms were updated for the new version.
4566 For this case, you need to review the new
4567 terms of the license and update the values of
4568 <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
4569 and
4570 <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
4571 as needed.
4572 </para></listitem>
4573 <listitem><para>
4574 Custom patches carried by the older version of
4575 the recipe might fail to apply to the new
4576 version.
4577 For these cases, you need to review the
4578 failures.
4579 Patches might not be necessary for the new
4580 version of the software if the upgraded version
4581 has fixed those issues.
4582 If a patch is necessary and failing, you need
4583 to rebase it into the new version.
4584 </para></listitem>
4585 </itemizedlist>
4586 </para></listitem>
4587 <listitem><para>
4588 <emphasis>Optionally Attempt to Build for Several Architectures:</emphasis>
4589 Once you successfully build the new software for a
4590 given architecture, you could test the build for
4591 other architectures by changing the
4592 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
4593 variable and rebuilding the software.
4594 This optional step is especially important if the
4595 recipe is public.
4596 </para></listitem>
4597 <listitem><para>
4598 <emphasis>Check the Upstream Change Log or Release Notes:</emphasis>
4599 Checking both these reveals if new features exist that
4600 could break backwards-compatibility.
4601 If so, you need to take steps to mitigate or eliminate
4602 that situation.
4603 </para></listitem>
4604 <listitem><para>
4605 <emphasis>Optionally Create a Bootable Image and Test:</emphasis>
4606 If you want, you can test the new software by booting
4607 it onto actual hardware.
4608 </para></listitem>
4609 <listitem><para>
4610 <emphasis>Create a Commit with the Change in the Layer Repository:</emphasis>
4611 After all builds work and any testing is successful,
4612 you can create commits for any changes in the layer
4613 holding your upgraded recipe.
4614 </para></listitem>
4615 </orderedlist>
4616 </para>
4524 </section> 4617 </section>
4525 </section> 4618 </section>
4526 4619