summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml74
-rw-r--r--documentation/getting-started/getting-started-yp-intro.xml118
2 files changed, 120 insertions, 72 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 8e8b06fba1..f757465935 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -22,78 +22,12 @@
22 multiple layers. 22 multiple layers.
23 Layers allow you to isolate different types of customizations from 23 Layers allow you to isolate different types of customizations from
24 each other. 24 each other.
25 You might find it tempting to keep everything in one layer when 25 For introductory information on the Yocto Project Layer Model,
26 working on a single project. 26 see the
27 However, the more modular your Metadata, the easier 27 "<ulink url='&YOCTO_DOCS_GS_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
28 it is to cope with future changes. 28 section in the Getting Started With Yocto Project Manual.
29 </para>
30
31 <para>
32 To illustrate how layers are used to keep things modular, consider
33 machine customizations.
34 These types of customizations typically reside in a special layer,
35 rather than a general layer, called a Board Support Package (BSP)
36 Layer.
37 Furthermore, the machine customizations should be isolated from
38 recipes and Metadata that support a new GUI environment,
39 for example.
40 This situation gives you a couple of layers: one for the machine
41 configurations, and one for the GUI environment.
42 It is important to understand, however, that the BSP layer can
43 still make machine-specific additions to recipes within the GUI
44 environment layer without polluting the GUI layer itself
45 with those machine-specific changes.
46 You can accomplish this through a recipe that is a BitBake append
47 (<filename>.bbappend</filename>) file, which is described later
48 in this section.
49 <note>
50 For general information on BSP layer structure, see the
51 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp'>Board Support Packages (BSP) - Developer's Guide</ulink>.
52 </note>
53 </para>
54
55 <para>
56 </para> 29 </para>
57 30
58 <section id='yocto-project-layers'>
59 <title>Layers</title>
60
61 <para>
62 The <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
63 contains both general layers and BSP
64 layers right out of the box.
65 You can easily identify layers that ship with a
66 Yocto Project release in the Source Directory by their
67 folder names.
68 Folders that represent layers typically have names that begin with
69 the string <filename>meta-</filename>.
70 <note>
71 It is not a requirement that a layer name begin with the
72 prefix <filename>meta-</filename>, but it is a commonly
73 accepted standard in the Yocto Project community.
74 </note>
75 For example, when you set up the Source Directory structure,
76 you will see several layers:
77 <filename>meta</filename>,
78 <filename>meta-skeleton</filename>,
79 <filename>meta-selftest</filename>,
80 <filename>meta-poky</filename>, and
81 <filename>meta-yocto-bsp</filename>.
82 Each of these folders represents a distinct layer.
83 </para>
84
85 <para>
86 As another example, if you set up a local copy of the
87 <filename>meta-intel</filename> Git repository
88 and then explore the folder of that general layer,
89 you will discover many Intel-specific BSP layers inside.
90 For more information on BSP layers, see the
91 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
92 section in the Yocto Project Board Support Package (BSP)
93 Developer's Guide.
94 </para>
95 </section>
96
97 <section id='creating-your-own-layer'> 31 <section id='creating-your-own-layer'>
98 <title>Creating Your Own Layer</title> 32 <title>Creating Your Own Layer</title>
99 33
diff --git a/documentation/getting-started/getting-started-yp-intro.xml b/documentation/getting-started/getting-started-yp-intro.xml
index 8ea11baa75..c160c1cf62 100644
--- a/documentation/getting-started/getting-started-yp-intro.xml
+++ b/documentation/getting-started/getting-started-yp-intro.xml
@@ -265,9 +265,123 @@
265 </section> 265 </section>
266 </section> 266 </section>
267 267
268 <section id='what-are-layers'> 268 <section id='the-yocto-project-layer-model'>
269 <title>What are Layers?</title> 269 <title>The Yocto Project Layer Model</title>
270 270
271 <para>
272 The Yocto Project's "Layer Model" is a development model for
273 embedded and IoT Linux creation that distinguishes the
274 Yocto Project from other simple build systems.
275 The Layer Model simultaneously supports collaboration and
276 customization.
277 Layers are repositories that contain related sets of instructions
278 that tell the OpenEmbedded build system what to do.
279 You can collaborate, share, and reuse layers.
280 </para>
281
282 <para>
283 Layers can contain changes to previous instructions or settings
284 at any time.
285 This powerful override capability is what allows you to customize
286 previously supplied collaborative or community layers to suit your
287 product requirements.
288 </para>
289
290 <para>
291 You use different layers to logically separate information in your
292 build.
293 As an example, you could have BSP, GUI, distro configuration,
294 middleware, or application layers.
295 Putting your entire build into one layer limits and complicates
296 future customization and reuse.
297 Isolating information into layers, on the other hand, helps
298 simplify future customizations and reuse.
299 You might find it tempting to keep everything in one layer when
300 working on a single project.
301 However, the more modular your Metadata, the easier
302 it is to cope with future changes.
303 <note><title>Notes</title>
304 <itemizedlist>
305 <listitem><para>
306 Use Board Support Package (BSP) layers from silicon
307 vendors when possible.
308 </para></listitem>
309 <listitem><para>
310 Familiarize yourself with the
311 <ulink url='https://caffelli-staging.yoctoproject.org/software-overview/layers/'>Yocto Project curated layer index</ulink>
312 or the
313 <ulink url='http://layers.openembedded.org/layerindex/branch/master/layers/'>OpenEmbedded layer index</ulink>.
314 The latter contains more layers but they are less
315 universally validated.
316 </para></listitem>
317 <listitem><para>
318 Layers support the inclusion of technologies, hardware
319 components, and software components.
320 The Yocto Project Compatible designation provides a
321 minimum level of standardization that contributes to a
322 strong ecosystem.
323 "YP Compatible" is applied to appropriate products and
324 software components such as BSPs, other OE-compatible
325 layers, and related open-source projects, allowing the
326 producer to use Yocto Project badges and branding
327 assets.
328 </para></listitem>
329 </itemizedlist>
330 </note>
331 </para>
332
333 <para>
334 To illustrate how layers are used to keep things modular, consider
335 machine customizations.
336 These types of customizations typically reside in a special layer,
337 rather than a general layer, called a BSP Layer.
338 Furthermore, the machine customizations should be isolated from
339 recipes and Metadata that support a new GUI environment,
340 for example.
341 This situation gives you a couple of layers: one for the machine
342 configurations, and one for the GUI environment.
343 It is important to understand, however, that the BSP layer can
344 still make machine-specific additions to recipes within the GUI
345 environment layer without polluting the GUI layer itself
346 with those machine-specific changes.
347 You can accomplish this through a recipe that is a BitBake append
348 (<filename>.bbappend</filename>) file, which is described later
349 in this section.
350 <note>
351 For general information on BSP layer structure, see the
352 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp'>Board Support Packages (BSP) - Developer's Guide</ulink>.
353 </note>
354 </para>
355
356 <para>
357 The
358 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
359 contains both general layers and BSP layers right out of the box.
360 You can easily identify layers that ship with a Yocto Project
361 release in the Source Directory by their names.
362 Layers typically have names that begin with the string
363 <filename>meta-</filename>.
364 <note>
365 It is not a requirement that a layer name begin with the
366 prefix <filename>meta-</filename>, but it is a commonly
367 accepted standard in the Yocto Project community.
368 </note>
369 For example, if you were to examine the
370 <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/'>tree view</ulink>
371 of the <filename>poky</filename> repository, you will see several
372 layers: <filename>meta</filename>,
373 <filename>meta-skeleton</filename>,
374 <filename>meta-selftest</filename>,
375 <filename>meta-poky</filename>, and
376 <filename>meta-yocto-bsp</filename>.
377 Each of these repositories represents a distinct layer.
378 </para>
379
380 <para>
381 For procedures on how to create layers, see the
382 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
383 section in the Yocto Project Development Tasks Manual.
384 </para>
271 </section> 385 </section>
272 386
273 <section id='components-and-tools'> 387 <section id='components-and-tools'>