summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml174
1 files changed, 107 insertions, 67 deletions
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index 6c4e5c2233..02a0b2ffe7 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -745,21 +745,39 @@
745 <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title> 745 <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
746 746
747 <para> 747 <para>
748 The <filename>devtool upgrade</filename> command updates 748 The <filename>devtool upgrade</filename> command upgrades
749 an existing recipe so that you can build it for an updated 749 an existing recipe to that of a more up-to-date version
750 set of source files. 750 found upstream.
751 The command is flexible enough to allow you to specify 751 Throughout the life of software, recipes continually undergo
752 source code revision and versioning schemes, extract code into 752 version upgrades by their upstream publishers.
753 or out of the <filename>devtool</filename> workspace, and 753 You can use the <filename>devtool upgrade</filename>
754 work with any source file forms that the fetchers support. 754 workflow to make sure your recipes you are using for builds
755 are up-to-date with their upstream counterparts.
756 <note>
757 Several methods exist by which you can upgrade recipes.
758 <filename>devtool upgrade</filename> happens to be one.
759 You can read about all the methods by which you can
760 upgrade recipes in the
761 "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes'>Upgrading Recipes</ulink>"
762 section of the Yocto Project Development Tasks Manual.
763 </note>
755 </para> 764 </para>
756 765
757 <para> 766 <para>
758 Depending on your particular scenario, the arguments and options 767 The <filename>devtool upgrade</filename> command is flexible
759 you use with <filename>devtool upgrade</filename> form different 768 enough to allow you to specify source code revision and
760 combinations. 769 versioning schemes, extract code into or out of the
770 <filename>devtool</filename>
771 <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>,
772 and work with any source file forms that the fetchers support.
773 </para>
774
775 <para>
776 Depending on your particular scenario, the arguments and
777 options you use with <filename>devtool upgrade</filename> form
778 different combinations.
761 The following diagram shows a common development flow 779 The following diagram shows a common development flow
762 you would use with the <filename>devtool modify</filename> 780 you would use with the <filename>devtool upgrade</filename>
763 command: 781 command:
764 </para> 782 </para>
765 783
@@ -769,110 +787,131 @@
769 787
770 <para> 788 <para>
771 <orderedlist> 789 <orderedlist>
772 <listitem><para><emphasis>Initiate the Upgrade</emphasis>: 790 <listitem><para>
773 The top part of the flow shows a typical scenario by which 791 <emphasis>Initiate the Upgrade</emphasis>:
774 you could use <filename>devtool upgrade</filename>. 792 The top part of the flow shows a typical scenario by
793 which you could use
794 <filename>devtool upgrade</filename>.
775 The following conditions exist: 795 The following conditions exist:
776 <itemizedlist> 796 <itemizedlist>
777 <listitem><para>The recipe exists in some layer external 797 <listitem><para>
798 The recipe exists in some layer external
778 to the <filename>devtool</filename> workspace. 799 to the <filename>devtool</filename> workspace.
779 </para></listitem> 800 </para></listitem>
780 <listitem><para>The source files for the new release 801 <listitem><para>
781 exist adjacent to the same location pointed to by 802 The source files for the new release
803 exist adjacent to the same location pointed to
804 by
782 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 805 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
783 in the recipe (e.g. a tarball with the new version 806 in the recipe (e.g. a tarball with the new
784 number in the name, or as a different revision in 807 version number in the name, or as a different
785 the upstream Git repository). 808 revision in the upstream Git repository).
786 </para></listitem> 809 </para></listitem>
787 </itemizedlist> 810 </itemizedlist>
788 A common situation is where third-party software has 811 A common situation is where third-party software has
789 undergone a revision so that it has been upgraded. 812 undergone a revision so that it has been upgraded.
790 The recipe you have access to is likely in your own layer. 813 The recipe you have access to is likely in your own
814 layer.
791 Thus, you need to upgrade the recipe to use the 815 Thus, you need to upgrade the recipe to use the
792 newer version of the software: 816 newer version of the software:
793 <literallayout class='monospaced'> 817 <literallayout class='monospaced'>
794 $ devtool upgrade -V <replaceable>version recipe</replaceable> 818 $ devtool upgrade -V <replaceable>version recipe</replaceable>
795 </literallayout> 819 </literallayout>
796 By default, the <filename>devtool upgrade</filename> command 820 By default, the <filename>devtool upgrade</filename>
797 extracts source code into the <filename>sources</filename> 821 command extracts source code into the
798 directory in the workspace. 822 <filename>sources</filename> directory in the
799 If you want the code extracted to any other location, you 823 <ulink url='&YOCTO_DOCS_REF_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>.
800 need to provide the <replaceable>srctree</replaceable> 824 If you want the code extracted to any other location,
801 positional argument with the command as follows: 825 you need to provide the
826 <replaceable>srctree</replaceable> positional argument
827 with the command as follows:
802 <literallayout class='monospaced'> 828 <literallayout class='monospaced'>
803 $ devtool upgrade -V <replaceable>version recipe srctree</replaceable> 829 $ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
804 </literallayout> 830 </literallayout>
805 Also, in this example, the "-V" option is used to specify 831 <note>
806 the new version. 832 In this example, the "-V" option specifies the new
833 version.
834 If you don't use "-V", the command upgrades the
835 recipe to the latest version.
836 </note>
807 If the source files pointed to by the 837 If the source files pointed to by the
808 <filename>SRC_URI</filename> statement in the recipe are 838 <filename>SRC_URI</filename> statement in the recipe
809 in a Git repository, you must provide the "-S" option and 839 are in a Git repository, you must provide the "-S"
810 specify a revision for the software.</para> 840 option and specify a revision for the software.</para>
811 841
812 <para>Once <filename>devtool</filename> locates the recipe, 842 <para>Once <filename>devtool</filename> locates the
813 it uses the <filename>SRC_URI</filename> variable to locate 843 recipe, it uses the <filename>SRC_URI</filename>
814 the source code and any local patch files from other 844 variable to locate the source code and any local patch
815 developers are located. 845 files from other developers are located.
816 The result is that the command sets up the source 846 The result is that the command sets up the source
817 code, the new version of the recipe, and an append file 847 code, the new version of the recipe, and an append file
818 all within the workspace. 848 all within the workspace.
819 </para></listitem> 849 </para></listitem>
820 <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>: 850 <listitem><para><emphasis>
821 At this point, there could be some conflicts due to the 851 Resolve any Conflicts created by the Upgrade</emphasis>:
852 At this point, conflicts could exist due to the
822 software being upgraded to a new version. 853 software being upgraded to a new version.
823 This would occur if your recipe specifies some patch files in 854 Conflicts occur if your recipe specifies some patch
824 <filename>SRC_URI</filename> that conflict with changes 855 files in <filename>SRC_URI</filename> that conflict
825 made in the new version of the software. 856 with changes made in the new version of the software.
826 If this is the case, you need to resolve the conflicts 857 If this is the case, you need to resolve the conflicts
827 by editing the source and following the normal 858 by editing the source and following the normal
828 <filename>git rebase</filename> conflict resolution 859 <filename>git rebase</filename> conflict resolution
829 process.</para> 860 process.</para>
830 <para>Before moving onto the next step, be sure to resolve any 861
831 such conflicts created through use of a newer or different 862 <para>Before moving onto the next step, be sure to
832 version of the software. 863 resolve any such conflicts created through use of a
864 newer or different version of the software.
833 </para></listitem> 865 </para></listitem>
834 <listitem><para><emphasis>Build the Recipe</emphasis>: 866 <listitem><para>
867 <emphasis>Build the Recipe</emphasis>:
835 Once you have your recipe in order, you can build it. 868 Once you have your recipe in order, you can build it.
836 You can either use <filename>devtool build</filename> or 869 You can either use <filename>devtool build</filename>
837 <filename>bitbake</filename>. 870 or <filename>bitbake</filename>.
838 Either method produces build output that is stored 871 Either method produces build output that is stored
839 in 872 in
840 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>. 873 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
841 </para></listitem> 874 </para></listitem>
842 <listitem><para><emphasis>Deploy the Build Output</emphasis>: 875 <listitem><para>
876 <emphasis>Deploy the Build Output</emphasis>:
843 When you use the <filename>devtool build</filename> 877 When you use the <filename>devtool build</filename>
844 command or <filename>bitbake</filename> to build out your 878 command or <filename>bitbake</filename> to build
845 recipe, you probably want to see if the resulting build 879 your recipe, you probably want to see if the resulting
846 output works as expected on target hardware. 880 build output works as expected on target hardware.
847 <note> 881 <note>
848 This step assumes you have a previously built 882 This step assumes you have a previously built
849 image that is already either running in QEMU or 883 image that is already either running in QEMU or
850 running on actual hardware. 884 running on actual hardware.
851 Also, it is assumed that for deployment of the image 885 Also, it is assumed that for deployment of the
852 to the target, SSH is installed in the image and if 886 image to the target, SSH is installed in the image
853 the image is running on real hardware that you have 887 and if the image is running on real hardware that
854 network access to and from your development machine. 888 you have network access to and from your
889 development machine.
855 </note> 890 </note>
856 You can deploy your build output to that target hardware by 891 You can deploy your build output to that target
857 using the <filename>devtool deploy-target</filename> command: 892 hardware by using the
893 <filename>devtool deploy-target</filename> command:
858 <literallayout class='monospaced'> 894 <literallayout class='monospaced'>
859 $ devtool deploy-target <replaceable>recipe target</replaceable> 895 $ devtool deploy-target <replaceable>recipe target</replaceable>
860 </literallayout> 896 </literallayout>
861 The <replaceable>target</replaceable> is a live target machine 897 The <replaceable>target</replaceable> is a live target
862 running as an SSH server.</para> 898 machine running as an SSH server.</para>
863 <para>You can, of course, also deploy the image you build 899
864 using the <filename>devtool build-image</filename> command 900 <para>You can, of course, also deploy the image you
901 build using the
902 <filename>devtool build-image</filename> command
865 to actual hardware. 903 to actual hardware.
866 However, <filename>devtool</filename> does not provide a 904 However, <filename>devtool</filename> does not provide
867 specific command that allows you to do this. 905 a specific command that allows you to do this.
868 </para></listitem> 906 </para></listitem>
869 <listitem><para> 907 <listitem><para>
870 <emphasis>Finish Your Work With the Recipe</emphasis>: 908 <emphasis>Finish Your Work With the Recipe</emphasis>:
871 The <filename>devtool finish</filename> command creates 909 The <filename>devtool finish</filename> command creates
872 any patches corresponding to commits in the local 910 any patches corresponding to commits in the local
873 Git repository, moves the new recipe to a more permanent 911 Git repository, moves the new recipe to a more
874 layer, and then resets the recipe so that the recipe is 912 permanent layer, and then resets the recipe so that
875 built normally rather than from the workspace. 913 the recipe is built normally rather than from the
914 workspace.
876 If you specify a destination layer that is the same as 915 If you specify a destination layer that is the same as
877 the original source, then the old version of the 916 the original source, then the old version of the
878 recipe and associated files will be removed prior to 917 recipe and associated files will be removed prior to
@@ -884,6 +923,7 @@
884 Any changes you want to turn into patches must be 923 Any changes you want to turn into patches must be
885 committed to the Git repository in the source tree. 924 committed to the Git repository in the source tree.
886 </note></para> 925 </note></para>
926
887 <para>As a final process of the 927 <para>As a final process of the
888 <filename>devtool finish</filename> command, the state 928 <filename>devtool finish</filename> command, the state
889 of the standard layers and the upstream source is 929 of the standard layers and the upstream source is
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-09 10:23:01 +0000