summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml219
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 @@
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