dev-manual: Updated the "Create Your Own Layer" section

Updated the explanation of the layer.conf file. I am going to use this section as the definitive section that explains the layer.conf file. (From yocto-docs rev: 4c70c7467f0ca5cf2346ef8d10bde437b971d2d2) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
author: Scott Rifenbark <srifenbark@gmail.com> 2018-03-23 16:34:08 -0700
committer: Richard Purdie <richard.purdie@linuxfoundation.org> 2018-05-24 17:16:03 +0100
commit: 6103268a4fe7268079abe5f509a60a10e24b1f25 (patch)
tree: 8270abb76e7c3070dce1db403abc8854820af0e0 /documentation
parent: d6a396b5942c9a9398745f720d1b83e31381c2ba (diff)
download: poky-6103268a4fe7268079abe5f509a60a10e24b1f25.tar.gz
1 files changed, 71 insertions, 88 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 31b46c4435..ccb902bef8 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -94,23 +94,23 @@
                        to several variables used in the configuration.
                        </para></listitem>
                    <listitem><para>
-                       <emphasis>Create a Layer Configuration
+                        <emphasis>Create a Layer Configuration File:</emphasis>
-                       File:</emphasis>
+                        Inside your new layer folder, you need to create a
-                       Inside your new layer folder, you need to create a
+                        <filename>conf/layer.conf</filename> file.
-                       <filename>conf/layer.conf</filename> file.
+                        It is easiest to take an existing layer configuration
-                       It is easiest to take an existing layer configuration
+                        file and copy that to your layer's
-                       file and copy that to your layer's
+                        <filename>conf</filename> directory and then modify the
-                       <filename>conf</filename> directory and then modify the
+                        file as needed.</para>
-                       file as needed.</para>
+                        <para>The
-                       <para>The
+                        <filename>meta-yocto-bsp/conf/layer.conf</filename> file
-                       <filename>meta-yocto-bsp/conf/layer.conf</filename> file
+                        in the Yocto Project
-                       in the Yocto Project
+                        <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf'>Source Repositories</ulink>
-                       <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf'>Source Repositories</ulink>
+                        demonstrates the required syntax.
-                       demonstrates the required syntax.
+                        For your layer, you need to replace "yoctobsp" with
-                       For your layer, you need to replace "yoctobsp" with the
+                        a unique identifier for your layer (e.g. "machinexyz"
-                       root name of your layer:
+                        for a layer named "meta-machinexyz"):
-                       <literallayout class='monospaced'>
+                        <literallayout class='monospaced'>
     # We have a conf and classes directory, add to BBPATH
     BBPATH .= ":${LAYERDIR}"
@@ -123,93 +123,76 @@
     BBFILE_PRIORITY_yoctobsp = "5"
     LAYERVERSION_yoctobsp = "4"
     LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;"
-                        </literallayout></para>
+                        </literallayout>
+                        Following is an explanation of the layer configuration
-                        <para>Here is an explanation of the example:
+                        file:
                        <itemizedlist>
                            <listitem><para>
-                                The configuration and classes directory is
+                                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>:
-                                appended to
+                                Adds the layer's root directory to BitBake's
-                                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>.
+                                search path.
-                                <note>
+                                Through the use of the
-                                    All non-distro layers are expected to
+                                <filename>BBPATH</filename> variable, BitBake
-                                    append the layer directory to
+                                locates class files
-                                    <filename>BBPATH</filename>.
+                                (<filename>.bbclass</filename>),
-                                    On the other hand, distro layers, such as
+                                configuration files, and files that are
-                                    <filename>meta-poky</filename>, can choose
+                                included with <filename>include</filename> and
-                                    to enforce their own precedence over
+                                <filename>require</filename> statements.
-                                    <filename>BBPATH</filename>.
+                                For these cases, BitBake uses the first file
-                                    For an example of that syntax, see the
+                                that matches the name found in
-                                    <filename>meta-poky/conf/layer.conf</filename>
+                                <filename>BBPATH</filename>.
-                                    file for in the
+                                This is similar to the way the
-                                    <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf'>Source Repositories</ulink>.
+                                <filename>PATH</filename> variable is used for
-                                </note>
+                                binaries.
+                                It is recommended, therefore, that you use
+                                unique class and configuration filenames in
+                                your custom layer.
                                </para></listitem>
                            <listitem><para>
-                                The recipes for the layers are appended to
+                                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>:
-                                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>.
+                                Defines the location for all recipes in the
+                                layer.
                                </para></listitem>
                            <listitem><para>
-                                The
+                                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></ulink>:
-                                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></ulink>
+                                Establishes the current layer through a
-                                variable is appended with the layer's root name,
+                                unique identifier that is used throughout the
-                                which is "yoctobsp" in this example.
+                                OpenEmbedded build system to refer to the layer.
+                                In this example, the identifier "yoctobsp" is
+                                the representation for the container layer
+                                named "meta-yocto-bsp".
                                </para></listitem>
                            <listitem><para>
-                                The
+                                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'><filename>BBFILE_PATTERN</filename></ulink>:
-                                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'><filename>BBFILE_PATTERN</filename></ulink>
+                                Expands immediately during parsing to
-                                variable is set to a regular expression and is
+                                provide the directory of the layer.
-                                used to match files from
-                                <filename>BBFILES</filename> into a particular
-                                layer.
-                                In this case,
-                                <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'><filename>LAYERDIR</filename></ulink>
-                                is used to make
-                                <filename>BBFILE_PATTERN</filename> match
-                                within the layer's path.
                                </para></listitem>
                            <listitem><para>
-                                The
+                                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>:
-                                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
+                                Establishes a priority to use for
-                                variable assigns a priority to the layer.
+                                recipes in the layer when the OpenEmbedded build
-                                Applying priorities is useful in situations
+                                finds recipes of the same name in different
-                                where the same recipe might appear in multiple
                                layers.
-                                A priority allows you to choose the layer
-                                that takes precedence.
                                </para></listitem>
                            <listitem><para>
-                                The
+                                <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'><filename>LAYERVERSION</filename></ulink>:
-                                <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'><filename>LAYERDIR</filename></ulink>
+                                Establishes a version number for the layer.
-                                variable expands to the directory of the
+                                You can use this version number to specify this
-                                current layer
+                                exact version of the layer as a dependency when
+                                using the
+                                <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></ulink>
+                                variable.
                                </para></listitem>
                            <listitem><para>
-                                The
+                                <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERSERIES_COMPAT'><filename>LAYERSERIES_COMPAT</filename></ulink>:
-                                <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'><filename>LAYERVERSION</filename></ulink>
+                                Lists the
-                                variable optionally specifies the version of a
+                                <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Yocto Project</ulink>
-                                layer as a single number.
+                                releases for which the current version is
+                                compatible.
+                                This variable is a good way to indicate how
+                                up-to-date your particular layer is.
                                </para></listitem>
-                            <listitem><para>
+                        </itemizedlist>
-                                The
-                                <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERSERIES_COMPAT'><filename>LAYERSERIES_COMPAT</filename></ulink>
-                                lists the Yocto Project releases for which the
-                                layer is compatible.
-                                </para></listitem>
-                        </itemizedlist></para>
-                        <para>Through the use of the <filename>BBPATH</filename>
-                        variable, BitBake locates class files
-                        (<filename>.bbclass</filename>),
-                        configuration files, and files that are included
-                        with <filename>include</filename> and
-                        <filename>require</filename> statements.
-                        For these cases, BitBake uses the first file that
-                        matches the name found in <filename>BBPATH</filename>.
-                        This is similar to the way the <filename>PATH</filename>
-                        variable is used for binaries.
-                        It is recommended, therefore, that you use unique
-                        class and configuration filenames in your custom layer.
                        </para></listitem>
                    <listitem><para>
                        <emphasis>Add Content:</emphasis>
author	Scott Rifenbark <srifenbark@gmail.com>	2018-03-23 16:34:08 -0700
committer	Richard Purdie <richard.purdie@linuxfoundation.org>	2018-05-24 17:16:03 +0100
commit	6103268a4fe7268079abe5f509a60a10e24b1f25 (patch)
tree	8270abb76e7c3070dce1db403abc8854820af0e0 /documentation
parent	d6a396b5942c9a9398745f720d1b83e31381c2ba (diff)
download	poky-6103268a4fe7268079abe5f509a60a10e24b1f25.tar.gz

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 31b46c4435..ccb902bef8 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -94,23 +94,23 @@
94	to several variables used in the configuration.	94	to several variables used in the configuration.
95	</para></listitem>	95	</para></listitem>
96	<listitem><para>	96	<listitem><para>
97	<emphasis>Create a Layer Configuration	97	<emphasis>Create a Layer Configuration File:</emphasis>
98	File:</emphasis>	98	Inside your new layer folder, you need to create a
99	Inside your new layer folder, you need to create a	99	<filename>conf/layer.conf</filename> file.
100	<filename>conf/layer.conf</filename> file.	100	It is easiest to take an existing layer configuration
101	It is easiest to take an existing layer configuration	101	file and copy that to your layer's
102	file and copy that to your layer's	102	<filename>conf</filename> directory and then modify the
103	<filename>conf</filename> directory and then modify the	103	file as needed.</para>
104	file as needed.</para>	104
105		105	<para>The
106	<para>The	106	<filename>meta-yocto-bsp/conf/layer.conf</filename> file
107	<filename>meta-yocto-bsp/conf/layer.conf</filename> file	107	in the Yocto Project
108	in the Yocto Project	108	<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf'>Source Repositories</ulink>
109	<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf'>Source Repositories</ulink>	109	demonstrates the required syntax.
110	demonstrates the required syntax.	110	For your layer, you need to replace "yoctobsp" with
111	For your layer, you need to replace "yoctobsp" with the	111	a unique identifier for your layer (e.g. "machinexyz"
112	root name of your layer:	112	for a layer named "meta-machinexyz"):
113	<literallayout class='monospaced'>	113	<literallayout class='monospaced'>
114	# We have a conf and classes directory, add to BBPATH	114	# We have a conf and classes directory, add to BBPATH
115	BBPATH .= ":${LAYERDIR}"	115	BBPATH .= ":${LAYERDIR}"
116		116
@@ -123,93 +123,76 @@
123	BBFILE_PRIORITY_yoctobsp = "5"	123	BBFILE_PRIORITY_yoctobsp = "5"
124	LAYERVERSION_yoctobsp = "4"	124	LAYERVERSION_yoctobsp = "4"
125	LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;"	125	LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;"
126	</literallayout></para>	126	</literallayout>
127		127	Following is an explanation of the layer configuration
128	<para>Here is an explanation of the example:	128	file:
129	<itemizedlist>	129	<itemizedlist>
130	<listitem><para>	130	<listitem><para>
131	The configuration and classes directory is	131	<ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>:
132	appended to	132	Adds the layer's root directory to BitBake's
133	<ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>.	133	search path.
134	<note>	134	Through the use of the
135	All non-distro layers are expected to	135	<filename>BBPATH</filename> variable, BitBake
136	append the layer directory to	136	locates class files
137	<filename>BBPATH</filename>.	137	(<filename>.bbclass</filename>),
138	On the other hand, distro layers, such as	138	configuration files, and files that are
139	<filename>meta-poky</filename>, can choose	139	included with <filename>include</filename> and
140	to enforce their own precedence over	140	<filename>require</filename> statements.
141	<filename>BBPATH</filename>.	141	For these cases, BitBake uses the first file
142	For an example of that syntax, see the	142	that matches the name found in
143	<filename>meta-poky/conf/layer.conf</filename>	143	<filename>BBPATH</filename>.
144	file for in the	144	This is similar to the way the
145	<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf'>Source Repositories</ulink>.	145	<filename>PATH</filename> variable is used for
146	</note>	146	binaries.
		147	It is recommended, therefore, that you use
		148	unique class and configuration filenames in
		149	your custom layer.
147	</para></listitem>	150	</para></listitem>
148	<listitem><para>	151	<listitem><para>
149	The recipes for the layers are appended to	152	<ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>:
150	<ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>.	153	Defines the location for all recipes in the
		154	layer.
151	</para></listitem>	155	</para></listitem>
152	<listitem><para>	156	<listitem><para>
153	The	157	<ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></ulink>:
154	<ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></ulink>	158	Establishes the current layer through a
155	variable is appended with the layer's root name,	159	unique identifier that is used throughout the
156	which is "yoctobsp" in this example.	160	OpenEmbedded build system to refer to the layer.
		161	In this example, the identifier "yoctobsp" is
		162	the representation for the container layer
		163	named "meta-yocto-bsp".
157	</para></listitem>	164	</para></listitem>
158	<listitem><para>	165	<listitem><para>
159	The	166	<ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'><filename>BBFILE_PATTERN</filename></ulink>:
160	<ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'><filename>BBFILE_PATTERN</filename></ulink>	167	Expands immediately during parsing to
161	variable is set to a regular expression and is	168	provide the directory of the layer.
162	used to match files from
163	<filename>BBFILES</filename> into a particular
164	layer.
165	In this case,
166	<ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'><filename>LAYERDIR</filename></ulink>
167	is used to make
168	<filename>BBFILE_PATTERN</filename> match
169	within the layer's path.
170	</para></listitem>	169	</para></listitem>
171	<listitem><para>	170	<listitem><para>
172	The	171	<ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>:
173	<ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>	172	Establishes a priority to use for
174	variable assigns a priority to the layer.	173	recipes in the layer when the OpenEmbedded build
175	Applying priorities is useful in situations	174	finds recipes of the same name in different
176	where the same recipe might appear in multiple
177	layers.	175	layers.
178	A priority allows you to choose the layer
179	that takes precedence.
180	</para></listitem>	176	</para></listitem>
181	<listitem><para>	177	<listitem><para>
182	The	178	<ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'><filename>LAYERVERSION</filename></ulink>:
183	<ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'><filename>LAYERDIR</filename></ulink>	179	Establishes a version number for the layer.
184	variable expands to the directory of the	180	You can use this version number to specify this
185	current layer	181	exact version of the layer as a dependency when
		182	using the
		183	<ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></ulink>
		184	variable.
186	</para></listitem>	185	</para></listitem>
187	<listitem><para>	186	<listitem><para>
188	The	187	<ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERSERIES_COMPAT'><filename>LAYERSERIES_COMPAT</filename></ulink>:
189	<ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'><filename>LAYERVERSION</filename></ulink>	188	Lists the
190	variable optionally specifies the version of a	189	<ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Yocto Project</ulink>
191	layer as a single number.	190	releases for which the current version is
		191	compatible.
		192	This variable is a good way to indicate how
		193	up-to-date your particular layer is.
192	</para></listitem>	194	</para></listitem>
193	<listitem><para>	195	</itemizedlist>
194	The
195	<ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERSERIES_COMPAT'><filename>LAYERSERIES_COMPAT</filename></ulink>
196	lists the Yocto Project releases for which the
197	layer is compatible.
198	</para></listitem>
199	</itemizedlist></para>
200
201	<para>Through the use of the <filename>BBPATH</filename>
202	variable, BitBake locates class files
203	(<filename>.bbclass</filename>),
204	configuration files, and files that are included
205	with <filename>include</filename> and
206	<filename>require</filename> statements.
207	For these cases, BitBake uses the first file that
208	matches the name found in <filename>BBPATH</filename>.
209	This is similar to the way the <filename>PATH</filename>
210	variable is used for binaries.
211	It is recommended, therefore, that you use unique
212	class and configuration filenames in your custom layer.
213	</para></listitem>	196	</para></listitem>
214	<listitem><para>	197	<listitem><para>
215	<emphasis>Add Content:</emphasis>	198	<emphasis>Add Content:</emphasis>