summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.pngbin0 -> 139827 bytes
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml164
2 files changed, 164 insertions, 0 deletions
diff --git a/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png b/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png
new file mode 100644
index 0000000000..65474dad02
--- /dev/null
+++ b/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png
Binary files differ
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index bb51683a44..67df1b0975 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -604,6 +604,170 @@
604 </orderedlist> 604 </orderedlist>
605 </para> 605 </para>
606 </section> 606 </section>
607
608 <section id='sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>
609 <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
610
611 <para>
612 The <filename>devtool upgrade</filename> command updates
613 an existing recipe so that you can build it for an updated
614 set of source files.
615 The command is flexible enough to allow you to specify
616 source code revision and versioning schemes, extract code into
617 or out of the <filename>devtool</filename> workspace, and
618 work with any source file forms that the fetchers support.
619 </para>
620
621 <para>
622 Depending on your particular scenario, the arguments and options
623 you use with <filename>devtool upgrade</filename> form different
624 combinations.
625 The following diagram shows a common development flow
626 you would use with the <filename>devtool modify</filename>
627 command:
628 </para>
629
630 <para>
631 <imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" />
632 </para>
633
634 <para>
635 <orderedlist>
636 <listitem><para><emphasis>Initiate the Upgrade</emphasis>:
637 The top part of the flow shows a typical scenario by which
638 you could use <filename>devtool upgrade</filename>.
639 The following conditions exist:
640 <itemizedlist>
641 <listitem><para>The recipe exists in some layer external
642 to the <filename>devtool</filename> workspace.
643 </para></listitem>
644 <listitem><para>The source files for the new release
645 exist adjacent to the same location pointed to by
646 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
647 in the recipe (e.g. a tarball with the new version
648 number in the name, or as a different revision in
649 the upstream Git repository).
650 </para></listitem>
651 </itemizedlist>
652 A common situation is where third-party software has
653 undergone a revision so that it has been upgraded.
654 The recipe you have access to is likely in your own layer.
655 Thus, you need to upgrade the recipe to use the
656 newer version of the software:
657 <literallayout class='monospaced'>
658 $ devtool upgrade -V <replaceable>version recipe</replaceable>
659 </literallayout>
660 By default, the <filename>devtool upgrade</filename> command
661 extracts source code into the <filename>sources</filename>
662 directory in the workspace.
663 If you want the code extracted to any other location, you
664 need to provide the <replaceable>srctree</replaceable>
665 positional argument with the command as follows:
666 <literallayout class='monospaced'>
667 $ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
668 </literallayout>
669 Also, in this example, the "-V" option is used to specify
670 the new version.
671 If the source files pointed to by the
672 <filename>SRC_URI</filename> statement in the recipe are
673 in a Git repository, you must provide the "-S" option and
674 specify a revision for the software.</para>
675
676 <para>Once <filename>devtool</filename> locates the recipe,
677 it uses the <filename>SRC_URI</filename> variable to locate
678 the source code and any local patch files from other
679 developers are located.
680 The result is that the command sets up the source
681 code, the new version of the recipe, and an append file
682 all within the workspace.
683 </para></listitem>
684 <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
685 At this point, there could be some conflicts due to the
686 software being upgraded to a new version.
687 This would occur if your recipe specifies some patch files in
688 <filename>SRC_URI</filename> that conflict with changes
689 made in the new version of the software.
690 If this is the case, you need to resolve the conflicts
691 by editing the source and following the normal
692 <filename>git rebase</filename> conflict resolution
693 process.</para>
694 <para>Before moving onto the next step, be sure to resolve any
695 such conflicts created through use of a newer or different
696 version of the software.
697 </para></listitem>
698 <listitem><para><emphasis>Build the Recipe</emphasis>:
699 Once you have your recipe in order, you can build it.
700 You can either use <filename>devtool build</filename> or
701 <filename>bitbake</filename>.
702 Either method produces build output that is stored
703 in
704 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
705 </para></listitem>
706 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
707 When you use the <filename>devtool build</filename>
708 command or <filename>bitbake</filename> to build out your
709 recipe, you probably want to see if the resulting build
710 output works as expected on target hardware.
711 <note>
712 This step assumes you have a previously built
713 image that is already either running in QEMU or
714 running on actual hardware.
715 Also, it is assumed that for deployment of the image
716 to the target, SSH is installed in the image and if
717 the image is running on real hardware that you have
718 network access to and from your development machine.
719 </note>
720 You can deploy your build output to that target hardware by
721 using the <filename>devtool deploy-target</filename> command:
722 <literallayout class='monospaced'>
723 $ devtool deploy-target <replaceable>recipe target</replaceable>
724 </literallayout>
725 The <replaceable>target</replaceable> is a live target machine
726 running as an SSH server.</para>
727 <para>You can, of course, also deploy the image you build
728 using the <filename>devtool build-image</filename> command
729 to actual hardware.
730 However, <filename>devtool</filename> does not provide a
731 specific command that allows you to do this.
732 </para></listitem>
733 <listitem><para>
734 <emphasis>Finish Your Work With the Recipe</emphasis>:
735 The <filename>devtool finish</filename> command creates
736 any patches corresponding to commits in the local
737 Git repository, updates the recipe to point to them
738 (or creates a <filename>.bbappend</filename> file to do
739 so, depending on the specified destination layer), and
740 then resets the recipe so that the recipe is built normally
741 rather than from the workspace.
742 <literallayout class='monospaced'>
743 $ devtool finish <replaceable>recipe layer</replaceable>
744 </literallayout>
745 <note>
746 Any changes you want to turn into patches must be
747 committed to the Git repository in the source tree.
748 </note></para>
749 <para>Because there is no need to move the recipe,
750 <filename>devtool finish</filename> either updates the
751 original recipe in the original layer or the command
752 creates a <filename>.bbappend</filename> in a different
753 layer as provided by <replaceable>layer</replaceable>.
754 </para>
755 <para>As a final process of the
756 <filename>devtool finish</filename> command, the state
757 of the standard layers and the upstream source is
758 restored so that you can build the recipe from those
759 areas rather than the workspace.
760 <note>
761 You can use the <filename>devtool reset</filename>
762 command to put things back should you decide you
763 do not want to proceed with your work.
764 If you do use this command, realize that the source
765 tree is preserved.
766 </note>
767 </para></listitem>
768 </orderedlist>
769 </para>
770 </section>
607</section> 771</section>
608 772
609<section id='sdk-a-closer-look-at-devtool-add'> 773<section id='sdk-a-closer-look-at-devtool-add'>