summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-08-07 15:30:38 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-08-09 09:25:24 +0100
commit7d7eb04b9c0cf5d8460f67f2d1c44f2c242bd755 (patch)
treed920c717909d36c03305adc592e66a3b93935587 /documentation/dev-manual/dev-manual-common-tasks.xml
parent2155745fff5db5c1b165d7f0c1f5b3e3bb6cab4d (diff)
downloadpoky-7d7eb04b9c0cf5d8460f67f2d1c44f2c242bd755.tar.gz
dev-manual: Updates to "Using .bbappend Files in Your Layer"
I did some rewriting for clarity in the "Using .bbappend Files in Your Layer" section. The section needed to be retitled so focus on the layer aspect of .bbappend files. Also, while I was in there, I did more work on the prose in general. Also had to fix some links in the bsp, kernel, and ref manuals that linked into the section whose name I changes. (From yocto-docs rev: a82bcc9fe0f909135434ee1bd36b4414f6c046c9) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml71
1 files changed, 36 insertions, 35 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 3fc76b2ee1..7464172fc6 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -686,37 +686,46 @@
686 </section> 686 </section>
687 687
688 <section id='using-bbappend-files'> 688 <section id='using-bbappend-files'>
689 <title>Using .bbappend Files</title> 689 <title>Using .bbappend Files in Your Layer</title>
690 690
691 <para> 691 <para>
692 Recipes used to append Metadata to other recipes are called 692 A recipe that appends Metadata to another recipe is called a
693 BitBake append files. 693 BitBake append file.
694 BitBake append files use the <filename>.bbappend</filename> file 694 A BitBake append file uses the <filename>.bbappend</filename>
695 type suffix, while the corresponding recipes to which Metadata 695 file type suffix, while the corresponding recipe to which
696 is being appended use the <filename>.bb</filename> file type 696 Metadata is being appended uses the <filename>.bb</filename>
697 suffix. 697 file type suffix.
698 </para> 698 </para>
699 699
700 <para> 700 <para>
701 A <filename>.bbappend</filename> file allows your layer to make 701 You can use a <filename>.bbappend</filename> file in your
702 additions or changes to the content of another layer's recipe 702 layer to make additions or changes to the content of another
703 without having to copy the other recipe into your layer. 703 layer's recipe without having to copy the other layer's
704 recipe into your layer.
704 Your <filename>.bbappend</filename> file resides in your layer, 705 Your <filename>.bbappend</filename> file resides in your layer,
705 while the main <filename>.bb</filename> recipe file to 706 while the main <filename>.bb</filename> recipe file to
706 which you are appending Metadata resides in a different layer. 707 which you are appending Metadata resides in a different layer.
707 </para> 708 </para>
708 709
709 <para> 710 <para>
710 Append files must have the same root names as their corresponding 711 Being able to append information to an existing recipe not only
711 recipes. 712 avoids duplication, but also automatically applies recipe
713 changes from a different layer into your layer.
714 If you were copying recipes, you would have to manually merge
715 changes as they occur.
716 </para>
717
718 <para>
719 When you create an append file, you must use the same root
720 name as the corresponding recipe file.
712 For example, the append file 721 For example, the append file
713 <filename>someapp_&DISTRO;.bbappend</filename> must apply to 722 <filename>someapp_&DISTRO;.bbappend</filename> must apply to
714 <filename>someapp_&DISTRO;.bb</filename>. 723 <filename>someapp_&DISTRO;.bb</filename>.
715 This means the original recipe and append file names are version 724 This means the original recipe and append file names are
716 number-specific. 725 version number-specific.
717 If the corresponding recipe is renamed to update to a newer 726 If the corresponding recipe is renamed to update to a newer
718 version, the corresponding <filename>.bbappend</filename> file must 727 version, you must also rename and possibly update
719 be renamed (and possibly updated) as well. 728 the corresponding <filename>.bbappend</filename> as well.
720 During the build process, BitBake displays an error on starting 729 During the build process, BitBake displays an error on starting
721 if it detects a <filename>.bbappend</filename> file that does 730 if it detects a <filename>.bbappend</filename> file that does
722 not have a corresponding recipe with a matching name. 731 not have a corresponding recipe with a matching name.
@@ -726,14 +735,6 @@
726 </para> 735 </para>
727 736
728 <para> 737 <para>
729 Being able to append information to an existing recipe not only
730 avoids duplication, but also automatically applies recipe
731 changes in a different layer to your layer.
732 If you were copying recipes, you would have to manually merge
733 changes as they occur.
734 </para>
735
736 <para>
737 As an example, consider the main formfactor recipe and a 738 As an example, consider the main formfactor recipe and a
738 corresponding formfactor append file both from the 739 corresponding formfactor append file both from the
739 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. 740 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
@@ -745,8 +746,7 @@
745 SUMMARY = "Device formfactor information" 746 SUMMARY = "Device formfactor information"
746 SECTION = "base" 747 SECTION = "base"
747 LICENSE = "MIT" 748 LICENSE = "MIT"
748 LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=4d92cd373abda3937c2bc47fbc49d690 \ 749 LIC_FILES_CHKSUM = "file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
749 file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
750 PR = "r45" 750 PR = "r45"
751 751
752 SRC_URI = "file://config file://machconfig" 752 SRC_URI = "file://config file://machconfig"
@@ -762,8 +762,7 @@
762 if [ -s "${S}/machconfig" ]; then 762 if [ -s "${S}/machconfig" ]; then
763 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/ 763 install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
764 fi 764 fi
765 } 765 } </literallayout>
766 </literallayout>
767 In the main recipe, note the 766 In the main recipe, note the
768 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 767 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
769 variable, which tells the OpenEmbedded build system where to 768 variable, which tells the OpenEmbedded build system where to
@@ -775,7 +774,8 @@
775 <filename>formfactor_0.0.bbappend</filename> and is from the 774 <filename>formfactor_0.0.bbappend</filename> and is from the
776 Raspberry Pi BSP Layer named 775 Raspberry Pi BSP Layer named
777 <filename>meta-raspberrypi</filename>. 776 <filename>meta-raspberrypi</filename>.
778 The file is in <filename>recipes-bsp/formfactor</filename>: 777 The file is in the layer at
778 <filename>recipes-bsp/formfactor</filename>:
779 <literallayout class='monospaced'> 779 <literallayout class='monospaced'>
780 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 780 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
781 </literallayout> 781 </literallayout>
@@ -795,12 +795,13 @@
795 </para> 795 </para>
796 796
797 <para> 797 <para>
798 The statement in this example extends the directories to include 798 The statement in this example extends the directories to
799 include
799 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>, 800 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>,
800 which resolves to a directory named 801 which resolves to a directory named
801 <filename>formfactor</filename> in the same directory 802 <filename>formfactor</filename> in the same directory
802 in which the append file resides (i.e. 803 in which the append file resides (i.e.
803 <filename>meta-raspberrypi/recipes-bsp/formfactor/formfactor</filename>. 804 <filename>meta-raspberrypi/recipes-bsp/formfactor</filename>.
804 This implies that you must have the supporting directory 805 This implies that you must have the supporting directory
805 structure set up that will contain any files or patches you 806 structure set up that will contain any files or patches you
806 will be including from the layer. 807 will be including from the layer.
@@ -808,8 +809,8 @@
808 809
809 <para> 810 <para>
810 Using the immediate expansion assignment operator 811 Using the immediate expansion assignment operator
811 <filename>:=</filename> is important because of the reference to 812 <filename>:=</filename> is important because of the reference
812 <filename>THISDIR</filename>. 813 to <filename>THISDIR</filename>.
813 The trailing colon character is important as it ensures that 814 The trailing colon character is important as it ensures that
814 items in the list remain colon-separated. 815 items in the list remain colon-separated.
815 <note> 816 <note>
@@ -7144,7 +7145,7 @@ Some notes from Cal:
7144 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 7145 and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
7145 statements enable the OpenEmbedded build system to find the patch file. 7146 statements enable the OpenEmbedded build system to find the patch file.
7146 For more information on using append files, see the 7147 For more information on using append files, see the
7147 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" 7148 "<link linkend='using-bbappend-files'>Using .bbappend Files in Your Layer</link>"
7148 section. 7149 section.
7149 </para></listitem> 7150 </para></listitem>
7150 <listitem><para><emphasis>Put the patch file in your layer</emphasis>: 7151 <listitem><para><emphasis>Put the patch file in your layer</emphasis>:
@@ -7623,7 +7624,7 @@ Some notes from Cal:
7623 <listitem><para>Add a <filename>psplash</filename> 7624 <listitem><para>Add a <filename>psplash</filename>
7624 append file for a branded splash screen. 7625 append file for a branded splash screen.
7625 For information on append files, see the 7626 For information on append files, see the
7626 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" 7627 "<link linkend='using-bbappend-files'>Using .bbappend Files in Your Layer</link>"
7627 section.</para></listitem> 7628 section.</para></listitem>
7628 <listitem><para>Add any other append files to make 7629 <listitem><para>Add any other append files to make
7629 custom changes that are specific to individual 7630 custom changes that are specific to individual