summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml215
1 files changed, 115 insertions, 100 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 1199669ab0..327289b54b 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -748,128 +748,143 @@ so that there are some definite steps on how to do this. I need more detail her
748 748
749 <section id="usingpoky-modifing-packages"> 749 <section id="usingpoky-modifing-packages">
750 <title>Modifying Package Source Code</title> 750 <title>Modifying Package Source Code</title>
751
751 <para> 752 <para>
752 Although the Yocto Project is typically used to build software, you might 753 This section describes how to modify package source code in the
753 find it helpful during development to modify the temporary package source code 754 <link linkend='yocto-project-build-directory'>Yocto Project's Build Directory</link>
754 found within the 755 and also how to then use
755 <link linkend='yocto-project-build-directory'>Yocto Project's Build Directory</link>. 756 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> to manage
756 For example, suppose you are developing a patch and you need to experiment a bit 757 the resulting patches.
757 to figure out your solution.
758 After you have initially built the package, you can iteratively tweak the
759 source code, which is located in the Yocto Project build directory, and then
760 you can force a re-compile and test your altered code.
761 Once you settle on a solution, you can then copy the updated source code
762 to its more permanent location.
763 </para> 758 </para>
764 759
765 <para> 760 <section id='working-with-source-code-in-the-build-directory'>
766 During a build, this temporary source code is available in the Yocto 761 <title>Working with Source Code in the Build Directory</title>
767 Project build directory, which is defined by the 762
768 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-TMPDIR'>TMPDIR</ulink></filename> variable. 763 <para>
769 The actual location within the build directory for the package source code 764 Although the Yocto Project is typically used to build software, you might
770 is defined by the 765 find it helpful during development to modify the temporary package source code
771 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-WORKDIR'>WORKDIR</ulink></filename> 766 found within the Yocto Project's Build Directory.
772 variable and depends on the package name and the architecture of the target device. 767 For example, suppose you are developing a patch and you need to experiment a bit
773 Here is the source code location for packages that are not target device-dependent: 768 to figure out your solution.
774 <literallayout class='monospaced'> 769 After you have initially built the package, you can iteratively tweak the
770 source code, which is located in the Yocto Project build directory, and then
771 you can force a re-compile and test your altered code.
772 Once you settle on a solution, you can then copy the updated source code
773 to its more permanent location.
774 </para>
775
776 <para>
777 During a build, this temporary source code is available in the Yocto
778 Project build directory, which is defined by the
779 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-TMPDIR'>TMPDIR</ulink></filename> variable.
780 The actual location within the build directory for the package source code
781 is defined by the
782 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-WORKDIR'>WORKDIR</ulink></filename>
783 variable and depends on the package name and the architecture of the target device.
784 Here is the source code location for packages that are not target device-dependent:
785 <literallayout class='monospaced'>
775 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} 786 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
776 </literallayout> 787 </literallayout>
777 Assuming a Yocto Project Files top-level directory named <filename>poky</filename> 788 Assuming a Yocto Project Files top-level directory named <filename>poky</filename>
778 and a default Yocto Project build directory of <filename>poky/build</filename>, 789 and a default Yocto Project build directory of <filename>poky/build</filename>,
779 the following is the temporary package source code location for the 790 the following is the temporary package source code location for the
780 <filename>acl</filename> package: 791 <filename>acl</filename> package:
781 <literallayout class='monospaced'> 792 <literallayout class='monospaced'>
782 ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3 793 ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3
783 </literallayout> 794 </literallayout>
784 </para> 795 </para>
785 796
786 <para> 797 <para>
787 If your package is target device-dependent, the source code location varies slightly: 798 If your package is target device-dependent, the source code location varies slightly:
788 <literallayout class='monospaced'> 799 <literallayout class='monospaced'>
789 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} 800 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
790 </literallayout> 801 </literallayout>
791 Again, assuming a Yocto Project Files top-level directory named <filename>poky</filename> 802 Again, assuming a Yocto Project Files top-level directory named <filename>poky</filename>
792 and a default Yocto Project build directory of <filename>poky/build</filename>, the 803 and a default Yocto Project build directory of <filename>poky/build</filename>, the
793 following is the temporary package source code location for the 804 following is the temporary package source code location for the
794 <filename>acl</filename> package that is being built for a MIPS-based device: 805 <filename>acl</filename> package that is being built for a MIPS-based device:
795 <literallayout class='monospaced'> 806 <literallayout class='monospaced'>
796 ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 807 ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2
797 </literallayout> 808 </literallayout>
798 </para> 809 </para>
799 810
800 <para> 811 <para>
801 Once you have modified the package source code, the easiest way to test your changes 812 Once you have modified the package source code, the easiest way to test your changes
802 is by calling the <filename>compile</filename> task as shown in the following example: 813 is by calling the <filename>compile</filename> task as shown in the following example:
803 <literallayout class='monospaced'> 814 <literallayout class='monospaced'>
804 $ bitbake -c compile -f &lt;name_of_package&gt; 815 $ bitbake -c compile -f &lt;name_of_package&gt;
805 </literallayout> 816 </literallayout>
806 </para> 817 </para>
807 818
808 <para> 819 <para>
809 The <filename>-f</filename> or <filename>--force</filename> 820 The <filename>-f</filename> or <filename>--force</filename>
810 option forces re-execution of the specified task. 821 option forces re-execution of the specified task.
811 You can call other tasks this way as well. 822 You can call other tasks this way as well.
812 <note>All the modifications you make to the temporary package source code 823 <note>All the modifications you make to the temporary package source code
813 disappear once you <filename>-c clean</filename> or 824 disappear once you <filename>-c clean</filename> or
814 <filename>-c cleanall</filename> with BitBake for the package. 825 <filename>-c cleanall</filename> with BitBake for the package.
815 Modifications will also disappear if you use the <filename>rm_work</filename> 826 Modifications will also disappear if you use the <filename>rm_work</filename>
816 feature as described in the 827 feature as described in the
817 "<ulink url='http://www.yoctoproject.org/docs/latest/yocto-project-qs/yocto-project-qs.html#building-image'>Building an Image</ulink>" section 828 "<ulink url='http://www.yoctoproject.org/docs/latest/yocto-project-qs/yocto-project-qs.html#building-image'>Building an Image</ulink>" section
818 of the Yocto Project Quick Start. 829 of the Yocto Project Quick Start.
819 </note> 830 </note>
820 </para> 831 </para>
821 </section> 832 </section>
822 833
823 <section id="usingpoky-modifying-packages-quilt"> 834 <section id="usingpoky-modifying-packages-quilt">
824 <title>Modifying Package Source Code with Quilt</title> 835 <title>Modifying Package Source Code with Quilt</title>
825 836
826 <para> 837 <para>
827 By default Poky uses <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> 838 By default, the Yocto Project build system (Poky) uses
828 to manage patches in the <filename>do_patch</filename> task. 839 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
829 This is a powerful tool that you can use to track all modifications to package sources. 840 to manage patches while executing the <filename>do_patch</filename> task.
830 </para> 841 Quilt is a powerful tool that you can use to track all modifications to package sources.
842 </para>
831 843
832 <para> 844 <para>
833 Before modifying source code, it is important to notify Quilt so it can track the changes 845 Before modifying source code, it is important to notify Quilt so it can track the changes
834 into the new patch file: 846 into the new patch file:
835 <literallayout class='monospaced'> 847 <literallayout class='monospaced'>
836 $ quilt new NAME-OF-PATCH.patch 848 $ quilt new NAME-OF-PATCH.patch
837 </literallayout> 849 </literallayout>
838 </para> 850 </para>
839 851
840 <para> 852 <para>
841 After notifying Quilt, add all modified files into that patch: 853 After notifying Quilt, add all modified files into that patch:
842 <literallayout class='monospaced'> 854 <literallayout class='monospaced'>
843 $ quilt add file1 file2 file3 855 $ quilt add file1 file2 file3
844 </literallayout> 856 </literallayout>
845 </para> 857 </para>
846 858
847 <para> 859 <para>
848 You can now start editing. 860 You can now start editing the source code.
849 Once you are done editing, you need to use Quilt to generate the final patch that 861 Once you are done editing, you need to use Quilt to generate the final patch that
850 will contain all your modifications. 862 contains all your modifications.
851 <literallayout class='monospaced'> 863 <literallayout class='monospaced'>
852 $ quilt refresh 864 $ quilt refresh
853 </literallayout> 865 </literallayout>
854 </para> 866 </para>
855 867
856 <para> 868 <para>
857 You can find the resulting patch file in the 869 You can find the resulting patch file in the
858 <filename>patches/</filename> subdirectory of the source 870 <filename>patches/</filename> subdirectory of the source
859 (<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-S'>S</ulink></filename>) directory. 871 (<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-S'>S</ulink></filename>) directory.
860 For future builds, you should copy the patch into the Yocto Project metadata and add it into the 872 For future builds, you should copy the patch into the
861 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-SRC_URI'>SRC_URI</ulink></filename> of a recipe. 873 <link linkend='yocto-project-files'>Yocto Project Files</link> metadata and add it
862 Here is an example: 874 into the
863 <literallayout class='monospaced'> 875 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-SRC_URI'>SRC_URI</ulink></filename> of the recipe.
876 Here is an example:
877 <literallayout class='monospaced'>
864 SRC_URI += "file://NAME-OF-PATCH.patch" 878 SRC_URI += "file://NAME-OF-PATCH.patch"
865 </literallayout> 879 </literallayout>
866 </para> 880 </para>
867 881
868 <para> 882 <para>
869 Finally, don't forget to 'bump' the 883 Finally, don't forget to 'bump' the
870 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PR'>PR</ulink></filename> 884 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PR'>PR</ulink></filename>
871 value in the same recipe since the resulting packages have changed. 885 value in the same recipe since the resulting packages have changed.
872 </para> 886 </para>
887 </section>
873 </section> 888 </section>
874 889
875 <section id="building-multiple-architecture-libraries-into-one-image"> 890 <section id="building-multiple-architecture-libraries-into-one-image">