summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-03-21 12:52:09 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-03-24 23:44:03 +0000
commitd9f293892174ffb8a7c3e3dc23e58f4ba1b09ee4 (patch)
treedb312c54c479e59cedd612dd1bc4d481aed9e0ee /documentation
parent3f06074a0d7d576399ba65364ca71378602c8138 (diff)
downloadpoky-d9f293892174ffb8a7c3e3dc23e58f4ba1b09ee4.tar.gz
kernel-dev: Reorganized Kernel Metadata Location and Syntax sections
It seems that the two sections "Kernel Metadata Location" and "Kernel Metadata Syntax" were flipped regarding their order of apperance in the kernel-dev manual. I belive that syntax should be first and then followed by a discussion on the location. I have swapped these section's ordering in the manual. (From yocto-docs rev: 167b088f459c7128bdc1abddd0b948be8f3bf5fe) 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/kernel-dev/kernel-dev-advanced.xml338
1 files changed, 169 insertions, 169 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index 266ef3aba8..1c1b6366db 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -170,175 +170,6 @@
170 </para> 170 </para>
171</section> 171</section>
172 172
173<section id='kernel-metadata-location'>
174 <title>Kernel Metadata Location</title>
175
176 <para>
177 Kernel Metadata always exists outside of the kernel tree either
178 defined in a kernel recipe (recipe-space) or outside of the recipe.
179 Where you choose to define the Metadata depends on what you want
180 to do and how you intend to work.
181 Regardless of where you define the kernel Metadata, the syntax used
182 applies equally.
183 </para>
184
185 <para>
186 If you are unfamiliar with the Linux kernel and only wish
187 to apply a configuration and possibly a couple of patches provided to
188 you by others, the recipe-space method is recommended.
189 This method is also a good approach if you are working with Linux kernel
190 sources you do not control or if you just do not want to maintain a
191 Linux kernel Git repository on your own.
192 For partial information on how you can define kernel Metadata in
193 the recipe-space, see the
194 "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
195 section.
196 </para>
197
198 <para>
199 Conversely, if you are actively developing a kernel and are already
200 maintaining a Linux kernel Git repository of your own, you might find
201 it more convenient to work with kernel Metadata kept outside the
202 recipe-space.
203 Working with Metadata in this area can make iterative development of
204 the Linux kernel more efficient outside of the BitBake environment.
205 </para>
206
207 <section id='recipe-space-metadata'>
208 <title>Recipe-Space Metadata</title>
209
210 <para>
211 When stored in recipe-space, the kernel Metadata files reside in a
212 directory hierarchy below
213 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>.
214 For a linux-yocto recipe or for a Linux kernel recipe derived
215 by copying and modifying
216 <filename>oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb</filename>
217 to a recipe in your layer, <filename>FILESEXTRAPATHS</filename>
218 is typically set to
219 <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>.
220 See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
221 section for more information.
222 </para>
223
224 <para>
225 Here is an example that shows a trivial tree of kernel Metadata
226 stored in recipe-space within a BSP layer:
227 <literallayout class='monospaced'>
228 meta-<replaceable>my_bsp_layer</replaceable>/
229 `-- recipes-kernel
230 `-- linux
231 `-- linux-yocto
232 |-- bsp-standard.scc
233 |-- bsp.cfg
234 `-- standard.cfg
235 </literallayout>
236 </para>
237
238 <para>
239 When the Metadata is stored in recipe-space, you must take
240 steps to ensure BitBake has the necessary information to decide
241 what files to fetch and when they need to be fetched again.
242 It is only necessary to specify the <filename>.scc</filename>
243 files on the
244 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
245 BitBake parses them and fetches any files referenced in the
246 <filename>.scc</filename> files by the <filename>include</filename>,
247 <filename>patch</filename>, or <filename>kconf</filename> commands.
248 Because of this, it is necessary to bump the recipe
249 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
250 value when changing the content of files not explicitly listed
251 in the <filename>SRC_URI</filename>.
252 </para>
253 </section>
254
255 <section id='metadata-outside-the-recipe-space'>
256 <title>Metadata Outside the Recipe-Space</title>
257
258 <para>
259 When stored outside of the recipe-space, the kernel Metadata
260 files reside in a separate repository.
261 The OpenEmbedded build system adds the Metadata to the build as
262 a "ktype=meta" repository through the
263 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
264 variable.
265 As an example, consider the following <filename>SRC_URI</filename>
266 statement from the <filename>linux-yocto_4.4.bb</filename>
267 kernel recipe:
268 <literallayout class='monospaced'>
269 SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.4.git;name=machine;branch=${KBRANCH}; \
270 git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.4;destsuffix=${KMETA}"
271 </literallayout>
272 <filename>${KMETA}</filename>, in this context, is simply used to
273 name the directory into which the Git fetcher places the Metadata.
274 This behavior is no different than any multi-repository
275 <filename>SRC_URI</filename> statement used in a recipe.
276 </para>
277
278 <para>
279 You can keep kernel Metadata in a "kernel-cache", which is a
280 directory containing configuration fragments.
281 As with any Metadata kept outside the recipe-space, you simply
282 need to use the <filename>SRC_URI</filename> statement with the
283 "type=kmeta" attribute.
284 Doing so makes the kernel Metadata available during the
285 configuration phase.
286 </para>
287
288<!--
289
290
291 <para>
292 Following is an example that shows how a trivial tree of Metadata
293 is stored in a custom Linux kernel Git repository:
294 <literallayout class='monospaced'>
295 meta/
296 `&dash;&dash; cfg
297 `&dash;&dash; kernel-cache
298 |&dash;&dash; bsp-standard.scc
299 |&dash;&dash; bsp.cfg
300 `&dash;&dash; standard.cfg
301 </literallayout>
302 </para>
303
304 <para>
305 To use a branch different from where the sources reside,
306 specify the branch in the <filename>KMETA</filename> variable
307 in your Linux kernel recipe.
308 Here is an example:
309 <literallayout class='monospaced'>
310 KMETA = "meta"
311 </literallayout>
312 To use the same branch as the sources, set
313 <filename>KMETA</filename> to an empty string:
314 <literallayout class='monospaced'>
315 KMETA = ""
316 </literallayout>
317 If you are working with your own sources and want to create an
318 orphan <filename>meta</filename> branch, use these commands
319 from within your Linux kernel Git repository:
320 <literallayout class='monospaced'>
321 $ git checkout &dash;&dash;orphan meta
322 $ git rm -rf .
323 $ git commit &dash;&dash;allow-empty -m "Create orphan meta branch"
324 </literallayout>
325 </para>
326-->
327
328 <para>
329 If you modify the Metadata, you must not forget to update the
330 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
331 statements in the kernel's recipe.
332 In particular, you need to update the
333 <filename>SRCREV_meta</filename> variable to match the commit in
334 the <filename>KMETA</filename> branch you wish to use.
335 Changing the data in these branches and not updating the
336 <filename>SRCREV</filename> statements to match will cause the
337 build to fetch an older commit.
338 </para>
339 </section>
340</section>
341
342<section id='kernel-metadata-syntax'> 173<section id='kernel-metadata-syntax'>
343 <title>Kernel Metadata Syntax</title> 174 <title>Kernel Metadata Syntax</title>
344 175
@@ -884,6 +715,175 @@
884 </section> 715 </section>
885</section> 716</section>
886 717
718<section id='kernel-metadata-location'>
719 <title>Kernel Metadata Location</title>
720
721 <para>
722 Kernel Metadata always exists outside of the kernel tree either
723 defined in a kernel recipe (recipe-space) or outside of the recipe.
724 Where you choose to define the Metadata depends on what you want
725 to do and how you intend to work.
726 Regardless of where you define the kernel Metadata, the syntax used
727 applies equally.
728 </para>
729
730 <para>
731 If you are unfamiliar with the Linux kernel and only wish
732 to apply a configuration and possibly a couple of patches provided to
733 you by others, the recipe-space method is recommended.
734 This method is also a good approach if you are working with Linux kernel
735 sources you do not control or if you just do not want to maintain a
736 Linux kernel Git repository on your own.
737 For partial information on how you can define kernel Metadata in
738 the recipe-space, see the
739 "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
740 section.
741 </para>
742
743 <para>
744 Conversely, if you are actively developing a kernel and are already
745 maintaining a Linux kernel Git repository of your own, you might find
746 it more convenient to work with kernel Metadata kept outside the
747 recipe-space.
748 Working with Metadata in this area can make iterative development of
749 the Linux kernel more efficient outside of the BitBake environment.
750 </para>
751
752 <section id='recipe-space-metadata'>
753 <title>Recipe-Space Metadata</title>
754
755 <para>
756 When stored in recipe-space, the kernel Metadata files reside in a
757 directory hierarchy below
758 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>.
759 For a linux-yocto recipe or for a Linux kernel recipe derived
760 by copying and modifying
761 <filename>oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb</filename>
762 to a recipe in your layer, <filename>FILESEXTRAPATHS</filename>
763 is typically set to
764 <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>.
765 See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
766 section for more information.
767 </para>
768
769 <para>
770 Here is an example that shows a trivial tree of kernel Metadata
771 stored in recipe-space within a BSP layer:
772 <literallayout class='monospaced'>
773 meta-<replaceable>my_bsp_layer</replaceable>/
774 `-- recipes-kernel
775 `-- linux
776 `-- linux-yocto
777 |-- bsp-standard.scc
778 |-- bsp.cfg
779 `-- standard.cfg
780 </literallayout>
781 </para>
782
783 <para>
784 When the Metadata is stored in recipe-space, you must take
785 steps to ensure BitBake has the necessary information to decide
786 what files to fetch and when they need to be fetched again.
787 It is only necessary to specify the <filename>.scc</filename>
788 files on the
789 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
790 BitBake parses them and fetches any files referenced in the
791 <filename>.scc</filename> files by the <filename>include</filename>,
792 <filename>patch</filename>, or <filename>kconf</filename> commands.
793 Because of this, it is necessary to bump the recipe
794 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
795 value when changing the content of files not explicitly listed
796 in the <filename>SRC_URI</filename>.
797 </para>
798 </section>
799
800 <section id='metadata-outside-the-recipe-space'>
801 <title>Metadata Outside the Recipe-Space</title>
802
803 <para>
804 When stored outside of the recipe-space, the kernel Metadata
805 files reside in a separate repository.
806 The OpenEmbedded build system adds the Metadata to the build as
807 a "ktype=meta" repository through the
808 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
809 variable.
810 As an example, consider the following <filename>SRC_URI</filename>
811 statement from the <filename>linux-yocto_4.4.bb</filename>
812 kernel recipe:
813 <literallayout class='monospaced'>
814 SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.4.git;name=machine;branch=${KBRANCH}; \
815 git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.4;destsuffix=${KMETA}"
816 </literallayout>
817 <filename>${KMETA}</filename>, in this context, is simply used to
818 name the directory into which the Git fetcher places the Metadata.
819 This behavior is no different than any multi-repository
820 <filename>SRC_URI</filename> statement used in a recipe.
821 </para>
822
823 <para>
824 You can keep kernel Metadata in a "kernel-cache", which is a
825 directory containing configuration fragments.
826 As with any Metadata kept outside the recipe-space, you simply
827 need to use the <filename>SRC_URI</filename> statement with the
828 "type=kmeta" attribute.
829 Doing so makes the kernel Metadata available during the
830 configuration phase.
831 </para>
832
833<!--
834
835
836 <para>
837 Following is an example that shows how a trivial tree of Metadata
838 is stored in a custom Linux kernel Git repository:
839 <literallayout class='monospaced'>
840 meta/
841 `&dash;&dash; cfg
842 `&dash;&dash; kernel-cache
843 |&dash;&dash; bsp-standard.scc
844 |&dash;&dash; bsp.cfg
845 `&dash;&dash; standard.cfg
846 </literallayout>
847 </para>
848
849 <para>
850 To use a branch different from where the sources reside,
851 specify the branch in the <filename>KMETA</filename> variable
852 in your Linux kernel recipe.
853 Here is an example:
854 <literallayout class='monospaced'>
855 KMETA = "meta"
856 </literallayout>
857 To use the same branch as the sources, set
858 <filename>KMETA</filename> to an empty string:
859 <literallayout class='monospaced'>
860 KMETA = ""
861 </literallayout>
862 If you are working with your own sources and want to create an
863 orphan <filename>meta</filename> branch, use these commands
864 from within your Linux kernel Git repository:
865 <literallayout class='monospaced'>
866 $ git checkout &dash;&dash;orphan meta
867 $ git rm -rf .
868 $ git commit &dash;&dash;allow-empty -m "Create orphan meta branch"
869 </literallayout>
870 </para>
871-->
872
873 <para>
874 If you modify the Metadata, you must not forget to update the
875 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
876 statements in the kernel's recipe.
877 In particular, you need to update the
878 <filename>SRCREV_meta</filename> variable to match the commit in
879 the <filename>KMETA</filename> branch you wish to use.
880 Changing the data in these branches and not updating the
881 <filename>SRCREV</filename> statements to match will cause the
882 build to fetch an older commit.
883 </para>
884 </section>
885</section>
886
887<section id='organizing-your-source'> 887<section id='organizing-your-source'>
888 <title>Organizing Your Source</title> 888 <title>Organizing Your Source</title>
889 889
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-27 19:40:58 +0000