summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml318
1 files changed, 231 insertions, 87 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index be639f76b8..5fcc69cbd0 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -746,48 +746,51 @@ so that there are some definite steps on how to do this. I need more detail her
746 </section> 746 </section>
747 </section> 747 </section>
748 748
749 <section id="usingpoky-modifing-packages"> 749 <section id="modifying-temporary-source-code">
750 <title>Modifying Package Source Code</title> 750 <title>Modifying Temporary Source Code</title>
751 751
752 <para> 752 <para>
753 This section describes how to modify package source code in the 753 Although the Yocto Project is typically used to build software, you might
754 <link linkend='yocto-project-build-directory'>Yocto Project's Build Directory</link> 754 find it helpful during development to modify the temporary source code used by recipes
755 and also how to then use 755 to build packages.
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
760 <link linkend='yocto-project-build-directory'>Yocto Project's Build Directory</link>, and then
761 you can force a re-compile and quickly test your altered code.
762 Once you settle on a solution, you can then preserve your changes in the form of
763 patches.
764 You can accomplish these steps all within either a
765 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or
766 <link linkend='git'>Git</link> workflow.
758 </para> 767 </para>
759 768
760 <section id='working-with-source-code-in-the-build-directory'> 769 <section id='finding-the-temporary-source-code'>
761 <title>Working with Source Code in the Build Directory</title> 770 <title>Finding the Temporary Source Code</title>
762 771
763 <para> 772 <para>
764 Although the Yocto Project is typically used to build software, you might 773 During a build, the unpacked temporary source code used by recipes
765 find it helpful during development to modify the temporary package source code 774 to build packages is available in the Yocto Project build directory as
766 found within the Yocto Project's Build Directory. 775 defined by the
767 For example, suppose you are developing a patch and you need to experiment a bit 776 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-S'>S</ulink></filename> variable:
768 to figure out your solution. 777 <literallayout class='monospaced'>
769 After you have initially built the package, you can iteratively tweak the 778 S = ${WORKDIR}/${PN}-${PV}
770 source code, which is located in the Yocto Project build directory, and then 779 </literallayout>
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> 780 </para>
775 781
776 <para> 782 <para>
777 During a build, this temporary source code is available in the Yocto 783 The actual location within the build directory for the temporary source code
778 Project build directory, which is defined by the 784 depends on the package name and the architecture of the target device.
779 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-TMPDIR'>TMPDIR</ulink></filename> variable. 785 Here is the temporary source code location for packages whose targets are not
780 The actual location within the build directory for the package source code 786 device-dependent:
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'> 787 <literallayout class='monospaced'>
786 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} 788 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
787 </literallayout> 789 </literallayout>
790 Let's look at an example.
788 Assuming a Yocto Project Files top-level directory named <filename>poky</filename> 791 Assuming a Yocto Project Files top-level directory named <filename>poky</filename>
789 and a default Yocto Project build directory of <filename>poky/build</filename>, 792 and a default Yocto Project build directory of <filename>poky/build</filename>,
790 the following is the temporary package source code location for the 793 the following is the temporary source code location for the
791 <filename>acl</filename> package: 794 <filename>acl</filename> package:
792 <literallayout class='monospaced'> 795 <literallayout class='monospaced'>
793 ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3 796 ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3
@@ -795,96 +798,237 @@ so that there are some definite steps on how to do this. I need more detail her
795 </para> 798 </para>
796 799
797 <para> 800 <para>
798 If your package is target device-dependent, the source code location varies slightly: 801 If your package is dependent on the target device, the temporary
802 source code location varies slightly:
799 <literallayout class='monospaced'> 803 <literallayout class='monospaced'>
800 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} 804 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
801 </literallayout> 805 </literallayout>
802 Again, assuming a Yocto Project Files top-level directory named <filename>poky</filename> 806 Again, assuming a Yocto Project Files top-level directory named <filename>poky</filename>
803 and a default Yocto Project build directory of <filename>poky/build</filename>, the 807 and a default Yocto Project build directory of <filename>poky/build</filename>, the
804 following is the temporary package source code location for the 808 following is the temporary source code location for the
805 <filename>acl</filename> package that is being built for a MIPS-based device: 809 <filename>acl</filename> package that is being built for a MIPS-based device:
806 <literallayout class='monospaced'> 810 <literallayout class='monospaced'>
807 ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 811 ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2
808 </literallayout> 812 </literallayout>
809 </para> 813 </para>
810 814
811 <para> 815 <note>
812 Once you have modified the package source code, the easiest way to test your changes 816 To better understand how the Yocto Project build system resolves directories during the
813 is by calling the <filename>compile</filename> task as shown in the following example: 817 build process, see the glossary entries for the
814 <literallayout class='monospaced'> 818 <ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-WORKDIR'>WORKDIR</ulink>,
815 $ bitbake -c compile -f &lt;name_of_package&gt; 819 <ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-TMPDIR'>TMPDIR</ulink>,
816 </literallayout> 820 <ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-TOPDIR'>TOPDIR</ulink>,
817 </para> 821 <ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PACKAGE_ARCH'>PACKAGE_ARCH</ulink>,
822 <ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-TARGET_OS'>TARGET_OS</ulink>,
823 <ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PN'>PN</ulink>,
824 <ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PV'>PV</ulink>,
825 and
826 <ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PR'>PR</ulink>
827 variables in the Yocto Project Reference Manual.
828 </note>
818 829
819 <para> 830 <para>
820 The <filename>-f</filename> or <filename>--force</filename> 831 Now that you know where to locate the temporary source files, you can use a
821 option forces re-execution of the specified task. 832 Quilt or Git workflow to make your edits, test the changes, and preserve the
822 You can call other tasks this way as well. 833 changes in the form of patches.
823 <note>All the modifications you make to the temporary package source code
824 disappear once you <filename>-c clean</filename> or
825 <filename>-c cleanall</filename> with BitBake for the package.
826 Modifications will also disappear if you use the <filename>rm_work</filename>
827 feature as described in the
828 "<ulink url='http://www.yoctoproject.org/docs/latest/yocto-project-qs/yocto-project-qs.html#building-image'>Building an Image</ulink>" section
829 of the Yocto Project Quick Start.
830 </note>
831 </para> 834 </para>
832 </section> 835 </section>
833 836
834 <section id="usingpoky-modifying-packages-quilt"> 837 <section id="using-a-quilt-workflow">
835 <title>Modifying Package Source Code with Quilt</title> 838 <title>Using a Quilt Workflow</title>
836 839
837 <para> 840 <para>
838 By default, the Yocto Project build system (Poky) uses
839 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> 841 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
840 to manage patches while executing the <filename>do_patch</filename> task. 842 is a powerful tool that allows you to capture source code changes without having
841 Quilt is a powerful tool that you can use to track all modifications to package sources. 843 a clean source tree.
842 </para> 844 This section outlines the typical workflow you can use to modify temporary source code,
843 845 test changes, and then preserve the changes in the form of a patch all using Quilt.
844 <para>
845 Before modifying source code, it is important to notify Quilt so it can track the changes
846 into a new patch file.
847 To create a new patch, use <filename>quilt new</filename> as below:
848 <literallayout class='monospaced'>
849 $ quilt new NAME-OF-PATCH.patch
850 </literallayout>
851 </para> 846 </para>
852 847
853 <para> 848 <para>
854 After creating the patch, add all the files you will be modifying into that patch 849 Follow these general steps:
855 as follows: 850 <orderedlist>
856 <literallayout class='monospaced'> 851 <listitem><para><emphasis>Find the Source Code:</emphasis>
857 $ quilt add file1 file2 file3 852 The temporary source code used by the Yocto Project build system is kept in the
858 </literallayout> 853 Yocto Project build directory.
854 See the
855 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
856 section to learn how to locate temporary source code for a
857 particular package.</para></listitem>
858 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
859 You need to be in the directory that has the temporary source code.
860 That directory is defined by the
861 <ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-S'>S</ulink>
862 variable.</para></listitem>
863 <listitem><para><emphasis>Notify Quilt:</emphasis>
864 Before modifying source code, it is important to notify Quilt so it can track changes
865 into a new patch file.
866 To create a new patch file, use <filename>quilt new</filename> as below:
867 <literallayout class='monospaced'>
868 $ quilt new my_changes.patch
869 </literallayout></para></listitem>
870 <listitem><para><emphasis>Add Files:</emphasis>
871 After creating the patch, add the files you will be modifying into that patch
872 as follows:
873 <literallayout class='monospaced'>
874 $ quilt add file1.c file2.c file3.c
875 </literallayout></para></listitem>
876 <listitem><para><emphasis>Edit the Files:</emphasis>
877 Make the changes to the temporary source code.</para></listitem>
878 <listitem><para><emphasis>Test Your Changes:</emphasis>
879 Once you have modified the source code, the easiest way to test your changes
880 is by calling the <filename>compile</filename> task as shown in the following example:
881 <literallayout class='monospaced'>
882 $ bitbake -c compile -f &lt;name_of_package&gt;
883 </literallayout>
884 The <filename>-f</filename> or <filename>--force</filename>
885 option forces re-execution of the specified task.
886 If you find problems with your code, you can just keep editing and
887 re-testing iteratively until things work as expected.
888 <note>All the modifications you make to the temporary source code
889 disappear once you <filename>-c clean</filename> or
890 <filename>-c cleanall</filename> with BitBake for the package.
891 Modifications will also disappear if you use the <filename>rm_work</filename>
892 feature as described in the
893 "<ulink url='http://www.yoctoproject.org/docs/latest/yocto-project-qs/yocto-project-qs.html#building-image'>Building an Image</ulink>"
894 section of the Yocto Project Quick Start.
895 </note></para></listitem>
896 <listitem><para><emphasis>Generate the Patch:</emphasis>
897 Once your changes work as expected, you need to use Quilt to generate the final patch that
898 contains all your modifications.
899 <literallayout class='monospaced'>
900 $ quilt refresh
901 </literallayout>
902 At this point the <filename>my_changes.patch</filename> file has all your edits made
903 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
904 <filename>file3.c</filename> files.</para>
905 <para>You can find the resulting patch file in the <filename>patches/</filename>
906 subdirectory of the source (<filename>S</filename>) directory.</para></listitem>
907 <listitem><para><emphasis>Copy the Patch File:</emphasis>
908 For future builds, you should copy the patch file into the
909 <link linkend='yocto-project-files'>Yocto Project Files</link> metadata and add it
910 into the
911 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-SRC_URI'>SRC_URI</ulink></filename>
912 of the recipe.
913 Here is an example:
914 <literallayout class='monospaced'>
915 SRC_URI += "file://my_changes.patch"
916 </literallayout></para></listitem>
917 <listitem><para><emphasis>Increment the Package Revision Number:</emphasis>
918 Finally, don't forget to 'bump' the
919 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PR'>PR</ulink></filename>
920 value in the same recipe since the resulting packages have changed.</para></listitem>
921 </orderedlist>
859 </para> 922 </para>
923 </section>
860 924
925 <section id='using-a-git-workflow'>
926 <title>Using a Git Workflow</title>
861 <para> 927 <para>
862 You can now start editing the source code. 928 Git is an even more powerful tool that allows you to capture source code changes without having
863 Once you are done editing, you need to use Quilt to generate the final patch that 929 a clean source tree.
864 contains all your modifications. 930 This section outlines the typical workflow you can use to modify temporary source code,
865 <literallayout class='monospaced'> 931 test changes, and then preserve the changes in the form of a patch all using Git.
866 $ quilt refresh 932 For general information on Git as it is used in the Yocto Project, see the
867 </literallayout> 933 "<link linkend='git'>Git</link>" section.
868 </para> 934 </para>
869 935
870 <para> 936 <para>
871 You can find the resulting patch file in the 937 The steps in this section assume that you have already created a local Git repository of
872 <filename>patches/</filename> subdirectory of the source 938 the <link linkend='yocto-project-files'>Yocto Project Files</link> and have checked them
873 (<filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-S'>S</ulink></filename>) directory. 939 out into an appropriate local working branch.
874 For future builds, you should copy the patch into the 940 If you need more explanation on setting up the Yocto Project Files, see the
875 <link linkend='yocto-project-files'>Yocto Project Files</link> metadata and add it 941 "<link linkend='getting-setup'>Getting Setup</link>" section.
876 into the 942 Also, if you need information on Git workflows in general, see the
877 <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. 943 <link linkend='workflows'>Workflows</link> section.
878 Here is an example:
879 <literallayout class='monospaced'>
880 SRC_URI += "file://NAME-OF-PATCH.patch"
881 </literallayout>
882 </para> 944 </para>
883 945
884 <para> 946 <para>
885 Finally, don't forget to 'bump' the 947 Follow these general steps:
886 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PR'>PR</ulink></filename> 948 <orderedlist>
887 value in the same recipe since the resulting packages have changed. 949 <listitem><para><emphasis>Find the Source Code:</emphasis>
950 The temporary source code used by the Yocto Project build system is kept in the
951 Yocto Project build directory.
952 See the
953 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
954 section to learn how to locate temporary source code for a
955 particular package.</para></listitem>
956 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
957 You need to be in the directory that has the temporary source code.
958 That directory is defined by the
959 <ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-S'>S</ulink>
960 variable.</para></listitem>
961 <listitem><para><emphasis>Edit the Files:</emphasis>
962 Make the changes to the temporary source code.</para></listitem>
963 <listitem><para><emphasis>Test Your Changes:</emphasis>
964 Once you have modified the source code, the easiest way to test your changes
965 is by calling the <filename>compile</filename> task as shown in the following example:
966 <literallayout class='monospaced'>
967 $ bitbake -c compile -f &lt;name_of_package&gt;
968 </literallayout>
969 The <filename>-f</filename> or <filename>--force</filename>
970 option forces re-execution of the specified task.
971 If you find problems with your code, you can just keep editing and
972 re-testing iteratively until things work as expected.
973 <note>All the modifications you make to the temporary source code
974 disappear once you <filename>-c clean</filename> or
975 <filename>-c cleanall</filename> with BitBake for the package.
976 Modifications will also disappear if you use the <filename>rm_work</filename>
977 feature as described in the
978 "<ulink url='http://www.yoctoproject.org/docs/latest/yocto-project-qs/yocto-project-qs.html#building-image'>Building an Image</ulink>"
979 section of the Yocto Project Quick Start.
980 </note></para></listitem>
981 <listitem><para><emphasis>See the List of Files You Changed:</emphasis>
982 Use the Git <filename>status</filename> command to see what files you have actually edited.
983 The ability to have Git track the files you have changed is an advantage that this
984 workflow has over the Quilt workflow.
985 Here is the Git command to list your changed files:
986 <literallayout class='monospaced'>
987 $ git status
988 </literallayout></para></listitem>
989 <listitem><para><emphasis>Stage the Modified Files:</emphasis>
990 Use the Git <filename>add</filename> command to stage the changed files so they
991 can be committed as follows:
992 <literallayout class='monospaced'>
993 $ git add file1.c file2.c file3.c
994 </literallayout></para></listitem>
995 <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
996 Use the Git <filename>commit</filename> command to commit the changes to the
997 local repository.
998 Once you have committed the files, you can use the Git <filename>log</filename>
999 command to see your changes:
1000 <literallayout class='monospaced'>
1001 $ git commit
1002 $ git log
1003 </literallayout></para></listitem>
1004 <listitem><para><emphasis>Generate the Patch:</emphasis>
1005 Once the changes are committed, you use the Git <filename>format-patch</filename>
1006 command to generate a patch file:
1007 <literallayout class='monospaced'>
1008 $ git format-patch HEAD~1
1009 </literallayout>
1010 The <filename>HEAD~1</filename> part of the command causes Git to generate the
1011 patch file for the most recent commit.</para>
1012 <para>At this point, the patch file has all your edits made
1013 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
1014 <filename>file3.c</filename> files.
1015 You can find the resulting patch file in the <filename>patches/</filename>
1016 subdirectory of the source (<filename>S</filename>) directory.</para></listitem>
1017 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1018 For future builds, you should copy the patch file into the
1019 <link linkend='yocto-project-files'>Yocto Project Files</link> metadata and add it
1020 into the
1021 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-SRC_URI'>SRC_URI</ulink></filename>
1022 of the recipe.
1023 Here is an example:
1024 <literallayout class='monospaced'>
1025 SRC_URI += "file://my_changes.patch"
1026 </literallayout></para></listitem>
1027 <listitem><para><emphasis>Increment the Package Revision Number:</emphasis>
1028 Finally, don't forget to 'bump' the
1029 <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PR'>PR</ulink></filename>
1030 value in the same recipe since the resulting packages have changed.</para></listitem>
1031 </orderedlist>
888 </para> 1032 </para>
889 </section> 1033 </section>
890 </section> 1034 </section>