summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-07-03 09:32:19 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-07-12 00:28:15 +0100
commit81add6e460ec9802e78e3bcb89637b2cfdd41ce2 (patch)
treec1f02048ccb00b83ed9a894a4d38e2901cb64d8b /documentation
parentb171aea8369c38231c5e9c70f78c9403173e7cb6 (diff)
downloadpoky-81add6e460ec9802e78e3bcb89637b2cfdd41ce2.tar.gz
dev-manual: Moved "Using Quilt in Your Workflow" to tasks
Fixes [YOCTO #11630] The section on useing Quilt can be a stand-alone task. I moved it to the "Common Tasks" chapter. (From yocto-docs rev: bb84b88fc8fc7f82e7bbe580d408ae7880f38d8b) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml134
-rw-r--r--documentation/dev-manual/dev-manual-model.xml110
2 files changed, 134 insertions, 110 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 2510d6e2d4..b01871bfe7 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -4068,6 +4068,140 @@
4068 </para> 4068 </para>
4069 </section> 4069 </section>
4070 4070
4071 <section id="using-a-quilt-workflow">
4072 <title>Using Quilt in Your Workflow</title>
4073
4074 <para>
4075 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
4076 is a powerful tool that allows you to capture source code changes
4077 without having a clean source tree.
4078 This section outlines the typical workflow you can use to modify
4079 source code, test changes, and then preserve the changes in the
4080 form of a patch all using Quilt.
4081 <note><title>Tip</title>
4082 With regard to preserving changes to source files, if you
4083 clean a recipe or have <filename>rm_work</filename> enabled,
4084 the workflow described in the
4085 "<link linkend='using-devtool-in-your-workflow'>Using <filename>devtool</filename> in Your Workflow</link>"
4086 section is a safer development flow than the flow that
4087 uses Quilt.
4088 </note>
4089 </para>
4090
4091 <para>
4092 Follow these general steps:
4093 <orderedlist>
4094 <listitem><para>
4095 <emphasis>Find the Source Code:</emphasis>
4096 Temporary source code used by the OpenEmbedded build system
4097 is kept in the
4098 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
4099 See the
4100 "<link linkend='finding-the-temporary-source-code'>Finding Temporary Source Code</link>"
4101 section to learn how to locate the directory that has the
4102 temporary source code for a particular package.
4103 </para></listitem>
4104 <listitem><para>
4105 <emphasis>Change Your Working Directory:</emphasis>
4106 You need to be in the directory that has the temporary
4107 source code.
4108 That directory is defined by the
4109 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
4110 variable.</para></listitem>
4111 <listitem><para>
4112 <emphasis>Create a New Patch:</emphasis>
4113 Before modifying source code, you need to create a new
4114 patch.
4115 To create a new patch file, use
4116 <filename>quilt new</filename> as below:
4117 <literallayout class='monospaced'>
4118 $ quilt new my_changes.patch
4119 </literallayout>
4120 </para></listitem>
4121 <listitem><para>
4122 <emphasis>Notify Quilt and Add Files:</emphasis>
4123 After creating the patch, you need to notify Quilt about
4124 the files you plan to edit.
4125 You notify Quilt by adding the files to the patch you
4126 just created:
4127 <literallayout class='monospaced'>
4128 $ quilt add file1.c file2.c file3.c
4129 </literallayout>
4130 </para></listitem>
4131 <listitem><para>
4132 <emphasis>Edit the Files:</emphasis>
4133 Make your changes in the source code to the files you added
4134 to the patch.
4135 </para></listitem>
4136 <listitem><para>
4137 <emphasis>Test Your Changes:</emphasis>
4138 Once you have modified the source code, the easiest way to
4139 test your changes is by calling the
4140 <filename>do_compile</filename> task as shown in the
4141 following example:
4142 <literallayout class='monospaced'>
4143 $ bitbake -c compile -f <replaceable>package</replaceable>
4144 </literallayout>
4145 The <filename>-f</filename> or <filename>--force</filename>
4146 option forces the specified task to execute.
4147 If you find problems with your code, you can just keep
4148 editing and re-testing iteratively until things work
4149 as expected.
4150 <note>
4151 All the modifications you make to the temporary
4152 source code disappear once you run the
4153 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>
4154 or
4155 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>
4156 tasks using BitBake (i.e.
4157 <filename>bitbake -c clean <replaceable>package</replaceable></filename>
4158 and
4159 <filename>bitbake -c cleanall <replaceable>package</replaceable></filename>).
4160 Modifications will also disappear if you use the
4161 <filename>rm_work</filename> feature as described
4162 in the
4163 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
4164 section of the Yocto Project Quick Start.
4165 </note>
4166 </para></listitem>
4167 <listitem><para>
4168 <emphasis>Generate the Patch:</emphasis>
4169 Once your changes work as expected, you need to use Quilt
4170 to generate the final patch that contains all your
4171 modifications.
4172 <literallayout class='monospaced'>
4173 $ quilt refresh
4174 </literallayout>
4175 At this point, the <filename>my_changes.patch</filename>
4176 file has all your edits made to the
4177 <filename>file1.c</filename>, <filename>file2.c</filename>,
4178 and <filename>file3.c</filename> files.</para>
4179
4180 <para>You can find the resulting patch file in the
4181 <filename>patches/</filename> subdirectory of the source
4182 (<filename>S</filename>) directory.
4183 </para></listitem>
4184 <listitem><para>
4185 <emphasis>Copy the Patch File:</emphasis>
4186 For simplicity, copy the patch file into a directory
4187 named <filename>files</filename>, which you can create
4188 in the same directory that holds the recipe
4189 (<filename>.bb</filename>) file or the append
4190 (<filename>.bbappend</filename>) file.
4191 Placing the patch here guarantees that the OpenEmbedded
4192 build system will find the patch.
4193 Next, add the patch into the
4194 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
4195 of the recipe.
4196 Here is an example:
4197 <literallayout class='monospaced'>
4198 SRC_URI += "file://my_changes.patch"
4199 </literallayout>
4200 </para></listitem>
4201 </orderedlist>
4202 </para>
4203 </section>
4204
4071 <section id='platdev-building-targets-with-multiple-configurations'> 4205 <section id='platdev-building-targets-with-multiple-configurations'>
4072 <title>Building Targets with Multiple Configurations</title> 4206 <title>Building Targets with Multiple Configurations</title>
4073 4207
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 8f0e5b1d9b..173871a843 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -716,116 +716,6 @@
716 </para> 716 </para>
717 </section> 717 </section>
718 </section> 718 </section>
719
720 <section id="using-a-quilt-workflow">
721 <title>Using Quilt in Your Workflow</title>
722
723 <para>
724 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
725 is a powerful tool that allows you to capture source code changes
726 without having a clean source tree.
727 This section outlines the typical workflow you can use to modify
728 source code, test changes, and then preserve the changes in the
729 form of a patch all using Quilt.
730 <note><title>Tip</title>
731 With regard to preserving changes to source files if you
732 clean a recipe or have <filename>rm_work</filename> enabled,
733 the workflow described in the
734 "<link linkend='using-devtool-in-your-workflow'>Using <filename>devtool</filename> in Your Workflow</link>"
735 section is a safer development flow than the flow that
736 uses Quilt.
737 </note>
738 </para>
739
740 <para>
741 Follow these general steps:
742 <orderedlist>
743 <listitem><para><emphasis>Find the Source Code:</emphasis>
744 Temporary source code used by the OpenEmbedded build system
745 is kept in the
746 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
747 See the
748 "<link linkend='finding-the-temporary-source-code'>Finding Temporary Source Code</link>"
749 section to learn how to locate the directory that has the
750 temporary source code for a particular package.
751 </para></listitem>
752 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
753 You need to be in the directory that has the temporary source code.
754 That directory is defined by the
755 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
756 variable.</para></listitem>
757 <listitem><para><emphasis>Create a New Patch:</emphasis>
758 Before modifying source code, you need to create a new patch.
759 To create a new patch file, use <filename>quilt new</filename> as below:
760 <literallayout class='monospaced'>
761 $ quilt new my_changes.patch
762 </literallayout></para></listitem>
763 <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis>
764 After creating the patch, you need to notify Quilt about the files
765 you plan to edit.
766 You notify Quilt by adding the files to the patch you just created:
767 <literallayout class='monospaced'>
768 $ quilt add file1.c file2.c file3.c
769 </literallayout>
770 </para></listitem>
771 <listitem><para><emphasis>Edit the Files:</emphasis>
772 Make your changes in the source code to the files you added
773 to the patch.
774 </para></listitem>
775 <listitem><para><emphasis>Test Your Changes:</emphasis>
776 Once you have modified the source code, the easiest way to
777 test your changes is by calling the
778 <filename>do_compile</filename> task as shown in the
779 following example:
780 <literallayout class='monospaced'>
781 $ bitbake -c compile -f <replaceable>package</replaceable>
782 </literallayout>
783 The <filename>-f</filename> or <filename>--force</filename>
784 option forces the specified task to execute.
785 If you find problems with your code, you can just keep editing and
786 re-testing iteratively until things work as expected.
787 <note>All the modifications you make to the temporary source code
788 disappear once you run the
789 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink>
790 or
791 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink>
792 tasks using BitBake (i.e.
793 <filename>bitbake -c clean <replaceable>package</replaceable></filename>
794 and
795 <filename>bitbake -c cleanall <replaceable>package</replaceable></filename>).
796 Modifications will also disappear if you use the <filename>rm_work</filename>
797 feature as described in the
798 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
799 section of the Yocto Project Quick Start.
800 </note></para></listitem>
801 <listitem><para><emphasis>Generate the Patch:</emphasis>
802 Once your changes work as expected, you need to use Quilt to generate the final patch that
803 contains all your modifications.
804 <literallayout class='monospaced'>
805 $ quilt refresh
806 </literallayout>
807 At this point, the <filename>my_changes.patch</filename> file has all your edits made
808 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
809 <filename>file3.c</filename> files.</para>
810 <para>You can find the resulting patch file in the <filename>patches/</filename>
811 subdirectory of the source (<filename>S</filename>) directory.</para></listitem>
812 <listitem><para><emphasis>Copy the Patch File:</emphasis>
813 For simplicity, copy the patch file into a directory named <filename>files</filename>,
814 which you can create in the same directory that holds the recipe
815 (<filename>.bb</filename>) file or the
816 append (<filename>.bbappend</filename>) file.
817 Placing the patch here guarantees that the OpenEmbedded build system will find
818 the patch.
819 Next, add the patch into the
820 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
821 of the recipe.
822 Here is an example:
823 <literallayout class='monospaced'>
824 SRC_URI += "file://my_changes.patch"
825 </literallayout></para></listitem>
826 </orderedlist>
827 </para>
828 </section>
829</section> 719</section>
830 720
831<section id="platdev-appdev-devshell"> 721<section id="platdev-appdev-devshell">
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-02 09:35:10 +0000