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 @@
            multiple layers.
            Layers allow you to isolate different types of customizations from
            each other.
-            You might find it tempting to keep everything in one layer when
+            For introductory information on the Yocto Project Layer Model,
-            working on a single project.
+            see the
-            However, the more modular your Metadata, the easier
+            "<ulink url='&YOCTO_DOCS_GS_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
-            it is to cope with future changes.
+            section in the Getting Started With Yocto Project Manual.
-        </para>
-        <para>
-            To illustrate how layers are used to keep things modular, consider
-            machine customizations.
-            These types of customizations typically reside in a special layer,
-            rather than a general layer, called a Board Support Package (BSP)
-            Layer.
-            Furthermore, the machine customizations should be isolated from
-            recipes and Metadata that support a new GUI environment,
-            for example.
-            This situation gives you a couple of layers: one for the machine
-            configurations, and one for the GUI environment.
-            It is important to understand, however, that the BSP layer can
-            still make machine-specific additions to recipes within the GUI
-            environment layer without polluting the GUI layer itself
-            with those machine-specific changes.
-            You can accomplish this through a recipe that is a BitBake append
-            (<filename>.bbappend</filename>) file, which is described later
-            in this section.
-            <note>
-                For general information on BSP layer structure, see the
-                <ulink url='&YOCTO_DOCS_BSP_URL;#bsp'>Board Support Packages (BSP) - Developer's Guide</ulink>.
-            </note>
-        </para>
-        <para>
        </para>
-        <section id='yocto-project-layers'>
-            <title>Layers</title>
-            <para>
-                The <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
-                contains both general layers and BSP
-                layers right out of the box.
-                You can easily identify layers that ship with a
-                Yocto Project release in the Source Directory by their
-                folder names.
-                Folders that represent layers typically have names that begin with
-                the string <filename>meta-</filename>.
-                <note>
-                    It is not a requirement that a layer name begin with the
-                    prefix <filename>meta-</filename>, but it is a commonly
-                    accepted standard in the Yocto Project community.
-                </note>
-                For example, when you set up the Source Directory structure,
-                you will see several layers:
-                <filename>meta</filename>,
-                <filename>meta-skeleton</filename>,
-                <filename>meta-selftest</filename>,
-                <filename>meta-poky</filename>, and
-                <filename>meta-yocto-bsp</filename>.
-                Each of these folders represents a distinct layer.
-            </para>
-            <para>
-                As another example, if you set up a local copy of the
-                <filename>meta-intel</filename> Git repository
-                and then explore the folder of that general layer,
-                you will discover many Intel-specific BSP layers inside.
-                For more information on BSP layers, see the
-                "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
-                section in the Yocto Project Board Support Package (BSP)
-                Developer's Guide.
-            </para>
-        </section>
        <section id='creating-your-own-layer'>
            <title>Creating Your Own Layer</title>
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 @@
        </section>
    </section>
-    <section id='what-are-layers'>
+    <section id='the-yocto-project-layer-model'>
-        <title>What are Layers?</title>
+        <title>The Yocto Project Layer Model</title>
+        <para>
+            The Yocto Project's "Layer Model" is a development model for
+            embedded and IoT Linux creation that distinguishes the
+            Yocto Project from other simple build systems.
+            The Layer Model simultaneously supports collaboration and
+            customization.
+            Layers are repositories that contain related sets of instructions
+            that tell the OpenEmbedded build system what to do.
+            You can collaborate, share, and reuse layers.
+        </para>
+        <para>
+            Layers can contain changes to previous instructions or settings
+            at any time.
+            This powerful override capability is what allows you to customize
+            previously supplied collaborative or community layers to suit your
+            product requirements.
+        </para>
+        <para>
+            You use different layers to logically separate information in your
+            build.
+            As an example, you could have BSP, GUI, distro configuration,
+            middleware, or application layers.
+            Putting your entire build into one layer limits and complicates
+            future customization and reuse.
+            Isolating information into layers, on the other hand, helps
+            simplify future customizations and reuse.
+            You might find it tempting to keep everything in one layer when
+            working on a single project.
+            However, the more modular your Metadata, the easier
+            it is to cope with future changes.
+            <note><title>Notes</title>
+                <itemizedlist>
+                    <listitem><para>
+                        Use Board Support Package (BSP) layers from silicon
+                        vendors when possible.
+                        </para></listitem>
+                    <listitem><para>
+                        Familiarize yourself with the
+                        <ulink url='https://caffelli-staging.yoctoproject.org/software-overview/layers/'>Yocto Project curated layer index</ulink>
+                        or the
+                        <ulink url='http://layers.openembedded.org/layerindex/branch/master/layers/'>OpenEmbedded layer index</ulink>.
+                        The latter contains more layers but they are less
+                        universally validated.
+                        </para></listitem>
+                    <listitem><para>
+                        Layers support the inclusion of technologies, hardware
+                        components, and software components.
+                        The Yocto Project Compatible designation provides a
+                        minimum level of standardization that contributes to a
+                        strong ecosystem.
+                        "YP Compatible" is applied to appropriate products and
+                        software components such as BSPs, other OE-compatible
+                        layers, and related open-source projects, allowing the
+                        producer to use Yocto Project badges and branding
+                        assets.
+                        </para></listitem>
+                </itemizedlist>
+            </note>
+        </para>
+        <para>
+            To illustrate how layers are used to keep things modular, consider
+            machine customizations.
+            These types of customizations typically reside in a special layer,
+            rather than a general layer, called a BSP Layer.
+            Furthermore, the machine customizations should be isolated from
+            recipes and Metadata that support a new GUI environment,
+            for example.
+            This situation gives you a couple of layers: one for the machine
+            configurations, and one for the GUI environment.
+            It is important to understand, however, that the BSP layer can
+            still make machine-specific additions to recipes within the GUI
+            environment layer without polluting the GUI layer itself
+            with those machine-specific changes.
+            You can accomplish this through a recipe that is a BitBake append
+            (<filename>.bbappend</filename>) file, which is described later
+            in this section.
+            <note>
+                For general information on BSP layer structure, see the
+                <ulink url='&YOCTO_DOCS_BSP_URL;#bsp'>Board Support Packages (BSP) - Developer's Guide</ulink>.
+            </note>
+        </para>
+        <para>
+            The
+            <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+            contains both general layers and BSP layers right out of the box.
+            You can easily identify layers that ship with a Yocto Project
+            release in the Source Directory by their names.
+            Layers typically have names that begin with the string
+            <filename>meta-</filename>.
+            <note>
+                It is not a requirement that a layer name begin with the
+                prefix <filename>meta-</filename>, but it is a commonly
+                accepted standard in the Yocto Project community.
+            </note>
+            For example, if you were to examine the
+            <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/'>tree view</ulink>
+            of the <filename>poky</filename> repository, you will see several
+            layers: <filename>meta</filename>,
+            <filename>meta-skeleton</filename>,
+            <filename>meta-selftest</filename>,
+            <filename>meta-poky</filename>, and
+            <filename>meta-yocto-bsp</filename>.
+            Each of these repositories represents a distinct layer.
+        </para>
+        <para>
+            For procedures on how to create layers, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+            section in the Yocto Project Development Tasks Manual.
+        </para>
    </section>
    <section id='components-and-tools'>

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'>