summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml221
1 files changed, 125 insertions, 96 deletions
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index 4303054cba..3a99b3791b 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -520,21 +520,20 @@
520 520
521 <para> 521 <para>
522 The <filename>devtool modify</filename> command prepares the 522 The <filename>devtool modify</filename> command prepares the
523 way to work on existing code that already has a recipe in 523 way to work on existing code that already has a local recipe in
524 place. 524 place that is used to build the software.
525 The command is flexible enough to allow you to extract code, 525 The command is flexible enough to allow you to extract code
526 specify the existing recipe, and keep track of and gather any 526 from an upstream source, specify the existing recipe, and
527 patch files from other developers that are 527 keep track of and gather any patch files from other developers
528 associated with the code. 528 that are associated with the code.
529 </para> 529 </para>
530 530
531 <para> 531 <para>
532 Depending on your particular scenario, the arguments and options 532 Depending on your particular scenario, the arguments and options
533 you use with <filename>devtool modify</filename> form different 533 you use with <filename>devtool modify</filename> form different
534 combinations. 534 combinations.
535 The following diagram shows common development flows 535 The following diagram shows common development flows for the
536 you would use with the <filename>devtool modify</filename> 536 <filename>devtool modify</filename> command:
537 command:
538 </para> 537 </para>
539 538
540 <para> 539 <para>
@@ -543,140 +542,165 @@
543 542
544 <para> 543 <para>
545 <orderedlist> 544 <orderedlist>
546 <listitem><para><emphasis>Preparing to Modify the Code</emphasis>: 545 <listitem><para>
546 <emphasis>Preparing to Modify the Code</emphasis>:
547 The top part of the flow shows three scenarios by which 547 The top part of the flow shows three scenarios by which
548 you could use <filename>devtool modify</filename> to 548 you could use <filename>devtool modify</filename> to
549 prepare to work on source files. 549 prepare to work on source files.
550 Each scenario assumes the following: 550 Each scenario assumes the following:
551 <itemizedlist> 551 <itemizedlist>
552 <listitem><para>The recipe exists in some layer external 552 <listitem><para>
553 The recipe exists locally in a layer external
553 to the <filename>devtool</filename> workspace. 554 to the <filename>devtool</filename> workspace.
554 </para></listitem> 555 </para></listitem>
555 <listitem><para>The source files exist upstream in an 556 <listitem><para>
557 The source files exist either upstream in an
556 un-extracted state or locally in a previously 558 un-extracted state or locally in a previously
557 extracted state. 559 extracted state.
558 </para></listitem> 560 </para></listitem>
559 </itemizedlist> 561 </itemizedlist>
560 The typical situation is where another developer has 562 The typical situation is where another developer has
561 created some layer for use with the Yocto Project and 563 created a layer for use with the Yocto Project and
562 their recipe already resides in that layer. 564 their recipe already resides in that layer.
563 Furthermore, their source code is readily available 565 Furthermore, their source code is readily available
564 either upstream or locally. 566 either upstream or locally.
565 <itemizedlist> 567 <itemizedlist>
566 <listitem><para><emphasis>Left</emphasis>: 568 <listitem><para>
567 The left scenario represents a common situation 569 <emphasis>Left</emphasis>:
568 where the source code does not exist locally 570 The left scenario in the figure represents a
569 and needs to be extracted. 571 common situation where the source code does
572 not exist locally and it needs to be extracted
573 from an upstream source.
570 In this situation, the source is extracted 574 In this situation, the source is extracted
571 into the default workspace location. 575 into the default <filename>devtool</filename>
576 workspace location.
572 The recipe, in this scenario, is in its own 577 The recipe, in this scenario, is in its own
573 layer outside the workspace 578 layer outside the workspace
574 (i.e. 579 (i.e.
575 <filename>meta-</filename><replaceable>layername</replaceable>). 580 <filename>meta-</filename><replaceable>layername</replaceable>).
576 </para> 581 </para>
577 582
578 <para>The following command identifies the recipe 583 <para>The following command identifies the
579 and by default extracts the source files: 584 recipe and, by default, extracts the source
585 files:
580 <literallayout class='monospaced'> 586 <literallayout class='monospaced'>
581 $ devtool modify <replaceable>recipe</replaceable> 587 $ devtool modify <replaceable>recipe</replaceable>
582 </literallayout> 588 </literallayout>
583 Once <filename>devtool</filename>locates the recipe, 589 Once <filename>devtool</filename>locates the
584 it uses the 590 recipe, <filename>devtool</filename> uses the
591 recipe's
585 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 592 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
586 variable to locate the source code and 593 statements to locate the source code and any
587 any local patch files from other developers are 594 local patch files from other developers.</para>
588 located. 595
589 <note> 596 <para>With this scenario, no
590 You cannot provide an URL for 597 <replaceable>srctree</replaceable> argument
591 <replaceable>srctree</replaceable> when using the 598 exists.
592 <filename>devtool modify</filename> command. 599 Consequently, the default behavior of the
593 </note> 600 <filename>devtool modify</filename> command is
594 With this scenario, however, since no 601 to extract the source files pointed to by the
595 <replaceable>srctree</replaceable> argument exists, the 602 <filename>SRC_URI</filename> statements into a
596 <filename>devtool modify</filename> command by default 603 local Git structure.
597 extracts the source files to a Git structure. 604 Furthermore, the location for the extracted
598 Furthermore, the location for the extracted source is the 605 source is the default area within the
599 default area within the workspace. 606 <filename>devtool</filename> workspace.
600 The result is that the command sets up both the source 607 The result is that the command sets up both
601 code and an append file within the workspace with the 608 the source code and an append file within the
602 recipe remaining in its original location. 609 workspace while the recipe remains in its
610 original location.
603 </para></listitem> 611 </para></listitem>
604 <listitem><para><emphasis>Middle</emphasis>: 612 <listitem><para>
605 The middle scenario represents a situation where 613 <emphasis>Middle</emphasis>:
606 the source code also does not exist locally. 614 The middle scenario in the figure represents a
615 situation where the source code also does not
616 exist locally.
607 In this case, the code is again upstream 617 In this case, the code is again upstream
608 and needs to be extracted to some 618 and needs to be extracted to some
609 local area as a Git repository. 619 local area as a Git repository.
610 The recipe, in this scenario, is again in its own 620 The recipe, in this scenario, is again local
611 layer outside the workspace.</para> 621 and in its own layer outside the workspace.
622 </para>
612 623
613 <para>The following command tells 624 <para>The following command tells
614 <filename>devtool</filename> what recipe with 625 <filename>devtool</filename> what recipe with
615 which to work and, in this case, identifies a local 626 which to work and, in this case, identifies a
616 area for the extracted source files that is outside 627 local area for the extracted source files that
617 of the default workspace: 628 is outside of the default
629 <filename>devtool</filename> workspace:
618 <literallayout class='monospaced'> 630 <literallayout class='monospaced'>
619 $ devtool modify <replaceable>recipe srctree</replaceable> 631 $ devtool modify <replaceable>recipe srctree</replaceable>
620 </literallayout> 632 </literallayout>
633 <note>
634 You cannot provide a URL for
635 <replaceable>srctree</replaceable> using
636 the <filename>devtool</filename> command.
637 </note>
621 As with all extractions, the command uses 638 As with all extractions, the command uses
622 the recipe's <filename>SRC_URI</filename> to locate the 639 the recipe's <filename>SRC_URI</filename>
623 source files. 640 statements to locate the source files and any
624 Once the files are located, the command by default 641 associated patch files.
625 extracts them. 642 Once the files are located, the command by
626 Providing the <replaceable>srctree</replaceable> 643 default extracts them into
627 argument instructs <filename>devtool</filename> where 644 <replaceable>srctree</replaceable>.</para>
628 to place the extracted source.</para> 645
629 646 <para>Within workspace,
630 <para>Within workspace, <filename>devtool</filename> 647 <filename>devtool</filename> creates an append
631 creates an append file for the recipe. 648 file for the recipe.
632 The recipe remains in its original location but 649 The recipe remains in its original location but
633 the source files are extracted to the location you 650 the source files are extracted to the location
634 provided with <replaceable>srctree</replaceable>. 651 you provide with
652 <replaceable>srctree</replaceable>.
635 </para></listitem> 653 </para></listitem>
636 <listitem><para><emphasis>Right</emphasis>: 654 <listitem><para>
637 The right scenario represents a situation 655 <emphasis>Right</emphasis>:
638 where the source tree 656 The right scenario in the figure represents a
639 (<replaceable>srctree</replaceable>) exists as a 657 situation where the source tree
640 previously extracted Git structure outside of 658 (<replaceable>srctree</replaceable>) already
641 the <filename>devtool</filename> workspace. 659 exists locally as a previously extracted Git
660 structure outside of the
661 <filename>devtool</filename> workspace.
642 In this example, the recipe also exists 662 In this example, the recipe also exists
643 elsewhere in its own layer. 663 elsewhere locally in its own layer.
644 </para> 664 </para>
645 665
646 <para>The following command tells 666 <para>The following command tells
647 <filename>devtool</filename> the recipe 667 <filename>devtool</filename> the recipe
648 with which to work, uses the "-n" option to indicate 668 with which to work, uses the "-n" option to
649 source does not need to be extracted, and uses 669 indicate source does not need to be extracted,
650 <replaceable>srctree</replaceable> to point to the 670 and uses <replaceable>srctree</replaceable> to
651 previously extracted source files: 671 point to the previously extracted source files:
652 <literallayout class='monospaced'> 672 <literallayout class='monospaced'>
653 $ devtool modify -n <replaceable>recipe srctree</replaceable> 673 $ devtool modify -n <replaceable>recipe srctree</replaceable>
654 </literallayout> 674 </literallayout>
655 </para> 675 </para>
656 676
657 <para>Once the command finishes, it creates only 677 <para>Once the command finishes, it creates only
658 an append file for the recipe in the workspace. 678 an append file for the recipe in the
679 <filename>devtool</filename> workspace.
659 The recipe and the source code remain in their 680 The recipe and the source code remain in their
660 original locations. 681 original locations.
661 </para></listitem> 682 </para></listitem>
662 </itemizedlist> 683 </itemizedlist>
663 </para></listitem> 684 </para></listitem>
664 <listitem><para><emphasis>Edit the Source</emphasis>: 685 <listitem><para>
665 Once you have used the <filename>devtool modify</filename> 686 <emphasis>Edit the Source</emphasis>:
666 command, you are free to make changes to the source 687 Once you have used the
667 files. 688 <filename>devtool modify</filename> command, you are
689 free to make changes to the source files.
668 You can use any editor you like to make and save 690 You can use any editor you like to make and save
669 your source code modifications. 691 your source code modifications.
670 </para></listitem> 692 </para></listitem>
671 <listitem><para><emphasis>Build the Recipe</emphasis>: 693 <listitem><para>
694 <emphasis>Build the Recipe</emphasis>:
672 Once you have updated the source files, you can build 695 Once you have updated the source files, you can build
673 the recipe. 696 the recipe.
674 </para></listitem> 697 </para></listitem>
675 <listitem><para><emphasis>Deploy the Build Output</emphasis>: 698 <listitem><para>
699 <emphasis>Deploy the Build Output</emphasis>:
676 When you use the <filename>devtool build</filename> 700 When you use the <filename>devtool build</filename>
677 command to build out your recipe, you probably want to see 701 command to build out your recipe, you probably want to
678 if the resulting build output works as expected on target 702 see if the resulting build output works as expected
679 hardware. 703 on target hardware.
680 <note> 704 <note>
681 This step assumes you have a previously built 705 This step assumes you have a previously built
682 image that is already either running in QEMU or 706 image that is already either running in QEMU or
@@ -686,19 +710,22 @@
686 the image is running on real hardware that you have 710 the image is running on real hardware that you have
687 network access to and from your development machine. 711 network access to and from your development machine.
688 </note> 712 </note>
689 You can deploy your build output to that target hardware by 713 You can deploy your build output to that target
690 using the <filename>devtool deploy-target</filename> command: 714 hardware by using the
715 <filename>devtool deploy-target</filename> command:
691 <literallayout class='monospaced'> 716 <literallayout class='monospaced'>
692 $ devtool deploy-target <replaceable>recipe target</replaceable> 717 $ devtool deploy-target <replaceable>recipe target</replaceable>
693 </literallayout> 718 </literallayout>
694 The <replaceable>target</replaceable> is a live target machine 719 The <replaceable>target</replaceable> is a live target
695 running as an SSH server.</para> 720 machine running as an SSH server.</para>
696 721
697 <para>You can, of course, also deploy the image you build 722 <para>You can, of course, use other methods to deploy
698 using the <filename>devtool build-image</filename> command 723 the image you built using the
699 to actual hardware. 724 <filename>devtool build-image</filename> command to
700 However, <filename>devtool</filename> does not provide a 725 actual hardware.
701 specific command that allows you to do this. 726 <filename>devtool</filename> does not provide
727 a specific command to deploy the image to actual
728 hardware.
702 </para></listitem> 729 </para></listitem>
703 <listitem><para> 730 <listitem><para>
704 <emphasis>Finish Your Work With the Recipe</emphasis>: 731 <emphasis>Finish Your Work With the Recipe</emphasis>:
@@ -707,28 +734,30 @@
707 Git repository, updates the recipe to point to them 734 Git repository, updates the recipe to point to them
708 (or creates a <filename>.bbappend</filename> file to do 735 (or creates a <filename>.bbappend</filename> file to do
709 so, depending on the specified destination layer), and 736 so, depending on the specified destination layer), and
710 then resets the recipe so that the recipe is built normally 737 then resets the recipe so that the recipe is built
711 rather than from the workspace. 738 normally rather than from the workspace.
712 <literallayout class='monospaced'> 739 <literallayout class='monospaced'>
713 $ devtool finish <replaceable>recipe layer</replaceable> 740 $ devtool finish <replaceable>recipe layer</replaceable>
714 </literallayout> 741 </literallayout>
715 <note> 742 <note>
716 Any changes you want to turn into patches must be 743 Any changes you want to turn into patches must be
717 committed to the Git repository in the source tree. 744 staged and committed within the local Git
745 repository before you use the
746 <filename>devtool finish</filename> command.
718 </note></para> 747 </note></para>
719 748
720 <para>Because there is no need to move the recipe, 749 <para>Because there is no need to move the recipe,
721 <filename>devtool finish</filename> either updates the 750 <filename>devtool finish</filename> either updates the
722 original recipe in the original layer or the command 751 original recipe in the original layer or the command
723 creates a <filename>.bbappend</filename> in a different 752 creates a <filename>.bbappend</filename> file in a
724 layer as provided by <replaceable>layer</replaceable>. 753 different layer as provided by
725 </para> 754 <replaceable>layer</replaceable>.</para>
726 755
727 <para>As a final process of the 756 <para>As a final process of the
728 <filename>devtool finish</filename> command, the state 757 <filename>devtool finish</filename> command, the state
729 of the standard layers and the upstream source is 758 of the standard layers and the upstream source is
730 restored so that you can build the recipe from those 759 restored so that you can build the recipe from those
731 areas rather than the workspace. 760 areas rather than from the workspace.
732 <note> 761 <note>
733 You can use the <filename>devtool reset</filename> 762 You can use the <filename>devtool reset</filename>
734 command to put things back should you decide you 763 command to put things back should you decide you