1 files changed, 218 insertions, 1 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index eda8df21f5..935648b2f9 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -237,7 +237,18 @@
                        <note>In order to be compliant with the Yocto Project,
                            a layer must contain a
                            <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>
-                            </note></para></listitem>
+                        </note>
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Optionally Test for Compatibility:</emphasis>
+                        If you want permission to use the Yocto Project
+                        Compatibility logo with your layer or application that
+                        uses your layer, perform the steps to apply for
+                        compatibility.
+                        See the
+                        "<link linkend='making-sure-your-layer-is-compatible-with-yocto-project'>Making Sure Your Layer is Compatible With Yocto Project</link>"
+                        section for more information.
+                        </para></listitem>
                </orderedlist>
            </para>
        </section>
@@ -412,6 +423,14 @@
                <para>
                    We also recommend the following:
                    <itemizedlist>
+                        <listitem><para>If you want permission to use the
+                            Yocto Project Compatibility logo with your layer
+                            or application that uses your layer, perform the
+                            steps to apply for compatibility.
+                            See the
+                            "<link linkend='making-sure-your-layer-is-compatible-with-yocto-project'>Making Sure Your Layer is Compatible With Yocto Project</link>"
+                            section for more information.
+                            </para></listitem>
                        <listitem><para>Store custom layers in a Git repository
                            that uses the
                            <filename>meta-<replaceable>layer_name</replaceable></filename> format.
@@ -428,6 +447,204 @@
            </section>
        </section>
+        <section id='making-sure-your-layer-is-compatible-with-yocto-project'>
+            <title>Making Sure Your Layer is Compatible With Yocto Project</title>
+            <para>
+                When you create a layer used with the Yocto Project, it is
+                advantageous to make sure that the layer interacts well with
+                existing Yocto Project layers (i.e. the layer is compatible
+                with the Yocto Project).
+                Ensuring compatibility makes the layer easy to be consumed
+                by others in the Yocto Project community and allows you
+                permission to use the Yocto Project Compatibility logo.
+            </para>
+            <para>
+                Version 1.0 of the Yocto Project Compatibility Program has
+                been in existence for a number of releases.
+                This version of the program consists of the layer application
+                process that requests permission to use the Yocto Project
+                Compatibility logo for your layer and application.
+                You can find version 1.0 of the form at
+                <ulink url='https://www.yoctoproject.org/webform/yocto-project-compatible-registration'></ulink>.
+                To be granted permission to use the logo, you need to be able
+                to answer "Yes" to the questions or have an acceptable
+                explanation for any questions answered "No".
+            </para>
+            <para>
+                A second version (2.0) of the Yocto Project Compatibility
+                Program is currently under development.
+                Included as part of version 2.0 (and currently available) is
+                the <filename>yocto-compat-layer.py</filename> script.
+                When run against a layer, this script tests the layer against
+                tighter constraints based on experiences of how layers have
+                worked in the real world and where pitfalls have been found.
+            </para>
+            <para>
+                Part of the 2.0 version of the program that is not currently
+                available but is in development is an updated compatibility
+                application form.
+                This updated form, among other questions, specifically
+                asks if your layer has passed the test using the
+                <filename>yocto-compat-layer.py</filename> script.
+                <note><title>Tip</title>
+                    Even though the updated application form is currently
+                    unavailable for version 2.0 of the Yocto Project
+                    Compatibility Program, the
+                    <filename>yocto-compat-layer.py</filename> script is
+                    available in OE-Core.
+                    You can use the script to assess the status of your
+                    layers in advance of the 2.0 release of the program.
+                </note>
+            </para>
+            <para>
+                The remainder of this section presents information on the
+                version 1.0 registration form and on the
+                <filename>yocto-compat-layer.py</filename> script.
+            </para>
+            <section id='yocto-project-compatibility-program-application'>
+                <title>Yocto Project Compatibility Program Application</title>
+                <para>
+                    Use the 1.0 version of the form to apply for your
+                    layer's compatibility approval.
+                    Upon successful application, you can use the Yocto
+                    Project Compatibility logo with your layer and the
+                    application that uses your layer.
+                </para>
+                <para>
+                    To access the form, use this link:
+                    <ulink url='https://www.yoctoproject.org/webform/yocto-project-compatible-registration'></ulink>.
+                    Follow the instructions on the form to complete your
+                    application.
+                </para>
+                <para>
+                    The application consists of the following sections:
+                    <itemizedlist>
+                        <listitem><para>
+                            <emphasis>Contact Information:</emphasis>
+                            Provide your contact information as the fields
+                            require.
+                            Along with your information, provide the
+                            released versions of the Yocto Project for which
+                            your layer is compatible.
+                            </para></listitem>
+                        <listitem><para>
+                            <emphasis>Acceptance Criteria:</emphasis>
+                            Provide "Yes" or "No" answers for each of the
+                            items in the checklist.
+                            Space exists at the bottom of the form for any
+                            explanations for items for which you answered "No".
+                            </para></listitem>
+                        <listitem><para>
+                            <emphasis>Recommendations:</emphasis>
+                            Provide answers for the questions regarding Linux
+                            kernel use and build success.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+            </section>
+            <section id='yocto-compat-layer-py-script'>
+                <title><filename>yocto-compat-layer.py</filename> Script</title>
+                <para>
+                    The <filename>yocto-compat-layer.py</filename> script,
+                    which is currently available, provides you a way to
+                    assess how compatible your layer is with the Yocto
+                    Project.
+                    You should run this script prior to using the form to
+                    apply for compatibility as described in the previous
+                    section.
+                    <note>
+                        Because the script is part of the 2.0 release of the
+                        Yocto Project Compatibility Program, you are not
+                        required to successfully run your layer against it
+                        in order to be granted compatibility status.
+                        However, it is a good idea as it promotes
+                        well-behaved layers and gives you an idea of where your
+                        layer stands regarding compatibility.
+                    </note>
+                </para>
+                <para>
+                    The script divides tests into three areas: COMMON, BSD,
+                    and DISTRO.
+                    For example, given a distribution layer (DISTRO), the
+                    layer must pass both the COMMON and DISTRO related tests.
+                    Furthermore, if your layer is a BSP layer, the layer must
+                    pass the COMMON and BSP set of tests.
+                </para>
+                <para>
+                    To execute the script, enter the following commands from
+                    your build directory:
+                    <literallayout class='monospaced'>
+     $ source oe-init-build-env
+     $ yocto-compat-layer.py <replaceable>your_layer_directory</replaceable>
+                    </literallayout>
+                    Be sure to provide the actual directory for your layer
+                    as part of the command.
+                </para>
+                <para>
+                    Entering the command causes the script to determine the
+                    type of layer and then to execute a set of specific
+                    tests against the layer.
+                    The following list overviews the test:
+                    <itemizedlist>
+                        <listitem><para>
+                            <filename>common.test_readme</filename>:
+                            Tests if a <filename>README</filename> file
+                            exists in the layer and the file is not empty.
+                            </para></listitem>
+                        <listitem><para>
+                            <filename>common.test_parse</filename>:
+                            Tests to make sure that BitBake can parse the
+                            files without error (i.e.
+                            <filename>bitbake -p</filename>).
+                            </para></listitem>
+                        <listitem><para>
+                            <filename>common.test_show_environment</filename>:
+                            Tests that the global or per-recipe environment
+                            is in order without errors (i.e.
+                            <filename>bitbake -e</filename>).
+                            </para></listitem>
+                        <listitem><para>
+                            <filename>common.test_signatures</filename>:
+                            Tests to be sure that BSP and DISTRO layers do not
+                            come with recipes that change signatures.
+                            </para></listitem>
+                        <listitem><para>
+                            <filename>bsp.test_bsp_defines_machines</filename>:
+                            Tests if a BSP layer has machine configurations.
+                            </para></listitem>
+                        <listitem><para>
+                            <filename>bsp.test_bsp_no_set_machine</filename>:
+                            Tests to ensure a BSP layer does not set the
+                            machine when the layer is added.
+                            </para></listitem>
+                        <listitem><para>
+                            <filename>distro.test_distro_defines_distros</filename>:
+                            Tests if a DISTRO layer has distro configurations.
+                            </para></listitem>
+                        <listitem><para>
+                            <filename>distro.test_distro_no_set_distro</filename>:
+                            Tests to ensure a DISTRO layer does not set the
+                            distribution when the layer is added.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+            </section>
+        </section>
        <section id='enabling-your-layer'>
            <title>Enabling Your Layer</title>

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index eda8df21f5..935648b2f9 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -237,7 +237,18 @@
237	<note>In order to be compliant with the Yocto Project,	237	<note>In order to be compliant with the Yocto Project,
238	a layer must contain a	238	a layer must contain a
239	<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>	239	<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>
240	</note></para></listitem>	240	</note>
		241	</para></listitem>
		242	<listitem><para>
		243	<emphasis>Optionally Test for Compatibility:</emphasis>
		244	If you want permission to use the Yocto Project
		245	Compatibility logo with your layer or application that
		246	uses your layer, perform the steps to apply for
		247	compatibility.
		248	See the
		249	"<link linkend='making-sure-your-layer-is-compatible-with-yocto-project'>Making Sure Your Layer is Compatible With Yocto Project</link>"
		250	section for more information.
		251	</para></listitem>
241	</orderedlist>	252	</orderedlist>
242	</para>	253	</para>
243	</section>	254	</section>
@@ -412,6 +423,14 @@
412	<para>	423	<para>
413	We also recommend the following:	424	We also recommend the following:
414	<itemizedlist>	425	<itemizedlist>
		426	<listitem><para>If you want permission to use the
		427	Yocto Project Compatibility logo with your layer
		428	or application that uses your layer, perform the
		429	steps to apply for compatibility.
		430	See the
		431	"<link linkend='making-sure-your-layer-is-compatible-with-yocto-project'>Making Sure Your Layer is Compatible With Yocto Project</link>"
		432	section for more information.
		433	</para></listitem>
415	<listitem><para>Store custom layers in a Git repository	434	<listitem><para>Store custom layers in a Git repository
416	that uses the	435	that uses the
417	<filename>meta-<replaceable>layer_name</replaceable></filename> format.	436	<filename>meta-<replaceable>layer_name</replaceable></filename> format.
@@ -428,6 +447,204 @@
428	</section>	447	</section>
429	</section>	448	</section>
430		449
		450	<section id='making-sure-your-layer-is-compatible-with-yocto-project'>
		451	<title>Making Sure Your Layer is Compatible With Yocto Project</title>
		452
		453	<para>
		454	When you create a layer used with the Yocto Project, it is
		455	advantageous to make sure that the layer interacts well with
		456	existing Yocto Project layers (i.e. the layer is compatible
		457	with the Yocto Project).
		458	Ensuring compatibility makes the layer easy to be consumed
		459	by others in the Yocto Project community and allows you
		460	permission to use the Yocto Project Compatibility logo.
		461	</para>
		462
		463	<para>
		464	Version 1.0 of the Yocto Project Compatibility Program has
		465	been in existence for a number of releases.
		466	This version of the program consists of the layer application
		467	process that requests permission to use the Yocto Project
		468	Compatibility logo for your layer and application.
		469	You can find version 1.0 of the form at
		470	<ulink url='https://www.yoctoproject.org/webform/yocto-project-compatible-registration'></ulink>.
		471	To be granted permission to use the logo, you need to be able
		472	to answer "Yes" to the questions or have an acceptable
		473	explanation for any questions answered "No".
		474	</para>
		475
		476	<para>
		477	A second version (2.0) of the Yocto Project Compatibility
		478	Program is currently under development.
		479	Included as part of version 2.0 (and currently available) is
		480	the <filename>yocto-compat-layer.py</filename> script.
		481	When run against a layer, this script tests the layer against
		482	tighter constraints based on experiences of how layers have
		483	worked in the real world and where pitfalls have been found.
		484	</para>
		485
		486	<para>
		487	Part of the 2.0 version of the program that is not currently
		488	available but is in development is an updated compatibility
		489	application form.
		490	This updated form, among other questions, specifically
		491	asks if your layer has passed the test using the
		492	<filename>yocto-compat-layer.py</filename> script.
		493	<note><title>Tip</title>
		494	Even though the updated application form is currently
		495	unavailable for version 2.0 of the Yocto Project
		496	Compatibility Program, the
		497	<filename>yocto-compat-layer.py</filename> script is
		498	available in OE-Core.
		499	You can use the script to assess the status of your
		500	layers in advance of the 2.0 release of the program.
		501	</note>
		502	</para>
		503
		504	<para>
		505	The remainder of this section presents information on the
		506	version 1.0 registration form and on the
		507	<filename>yocto-compat-layer.py</filename> script.
		508	</para>
		509
		510	<section id='yocto-project-compatibility-program-application'>
		511	<title>Yocto Project Compatibility Program Application</title>
		512
		513	<para>
		514	Use the 1.0 version of the form to apply for your
		515	layer's compatibility approval.
		516	Upon successful application, you can use the Yocto
		517	Project Compatibility logo with your layer and the
		518	application that uses your layer.
		519	</para>
		520
		521	<para>
		522	To access the form, use this link:
		523	<ulink url='https://www.yoctoproject.org/webform/yocto-project-compatible-registration'></ulink>.
		524	Follow the instructions on the form to complete your
		525	application.
		526	</para>
		527
		528	<para>
		529	The application consists of the following sections:
		530	<itemizedlist>
		531	<listitem><para>
		532	<emphasis>Contact Information:</emphasis>
		533	Provide your contact information as the fields
		534	require.
		535	Along with your information, provide the
		536	released versions of the Yocto Project for which
		537	your layer is compatible.
		538	</para></listitem>
		539	<listitem><para>
		540	<emphasis>Acceptance Criteria:</emphasis>
		541	Provide "Yes" or "No" answers for each of the
		542	items in the checklist.
		543	Space exists at the bottom of the form for any
		544	explanations for items for which you answered "No".
		545	</para></listitem>
		546	<listitem><para>
		547	<emphasis>Recommendations:</emphasis>
		548	Provide answers for the questions regarding Linux
		549	kernel use and build success.
		550	</para></listitem>
		551	</itemizedlist>
		552	</para>
		553	</section>
		554
		555	<section id='yocto-compat-layer-py-script'>
		556	<title><filename>yocto-compat-layer.py</filename> Script</title>
		557
		558	<para>
		559	The <filename>yocto-compat-layer.py</filename> script,
		560	which is currently available, provides you a way to
		561	assess how compatible your layer is with the Yocto
		562	Project.
		563	You should run this script prior to using the form to
		564	apply for compatibility as described in the previous
		565	section.
		566	<note>
		567	Because the script is part of the 2.0 release of the
		568	Yocto Project Compatibility Program, you are not
		569	required to successfully run your layer against it
		570	in order to be granted compatibility status.
		571	However, it is a good idea as it promotes
		572	well-behaved layers and gives you an idea of where your
		573	layer stands regarding compatibility.
		574	</note>
		575	</para>
		576
		577	<para>
		578	The script divides tests into three areas: COMMON, BSD,
		579	and DISTRO.
		580	For example, given a distribution layer (DISTRO), the
		581	layer must pass both the COMMON and DISTRO related tests.
		582	Furthermore, if your layer is a BSP layer, the layer must
		583	pass the COMMON and BSP set of tests.
		584	</para>
		585
		586	<para>
		587	To execute the script, enter the following commands from
		588	your build directory:
		589	<literallayout class='monospaced'>
		590	$ source oe-init-build-env
		591	$ yocto-compat-layer.py <replaceable>your_layer_directory</replaceable>
		592	</literallayout>
		593	Be sure to provide the actual directory for your layer
		594	as part of the command.
		595	</para>
		596
		597	<para>
		598	Entering the command causes the script to determine the
		599	type of layer and then to execute a set of specific
		600	tests against the layer.
		601	The following list overviews the test:
		602	<itemizedlist>
		603	<listitem><para>
		604	<filename>common.test_readme</filename>:
		605	Tests if a <filename>README</filename> file
		606	exists in the layer and the file is not empty.
		607	</para></listitem>
		608	<listitem><para>
		609	<filename>common.test_parse</filename>:
		610	Tests to make sure that BitBake can parse the
		611	files without error (i.e.
		612	<filename>bitbake -p</filename>).
		613	</para></listitem>
		614	<listitem><para>
		615	<filename>common.test_show_environment</filename>:
		616	Tests that the global or per-recipe environment
		617	is in order without errors (i.e.
		618	<filename>bitbake -e</filename>).
		619	</para></listitem>
		620	<listitem><para>
		621	<filename>common.test_signatures</filename>:
		622	Tests to be sure that BSP and DISTRO layers do not
		623	come with recipes that change signatures.
		624	</para></listitem>
		625	<listitem><para>
		626	<filename>bsp.test_bsp_defines_machines</filename>:
		627	Tests if a BSP layer has machine configurations.
		628	</para></listitem>
		629	<listitem><para>
		630	<filename>bsp.test_bsp_no_set_machine</filename>:
		631	Tests to ensure a BSP layer does not set the
		632	machine when the layer is added.
		633	</para></listitem>
		634	<listitem><para>
		635	<filename>distro.test_distro_defines_distros</filename>:
		636	Tests if a DISTRO layer has distro configurations.
		637	</para></listitem>
		638	<listitem><para>
		639	<filename>distro.test_distro_no_set_distro</filename>:
		640	Tests to ensure a DISTRO layer does not set the
		641	distribution when the layer is added.
		642	</para></listitem>
		643	</itemizedlist>
		644	</para>
		645	</section>
		646	</section>
		647
431	<section id='enabling-your-layer'>	648	<section id='enabling-your-layer'>
432	<title>Enabling Your Layer</title>	649	<title>Enabling Your Layer</title>
433		650