summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml444
1 files changed, 222 insertions, 222 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 189a4ffe01..f55e99122b 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -445,6 +445,228 @@
445 </section> 445 </section>
446 </section> 446 </section>
447 447
448 <section id='usingpoky-extend-customimage'>
449 <title>Customizing Images</title>
450
451 <para>
452 You can customize Yocto Project images to satisfy particular requirements.
453 This section describes several methods and provides guidelines for each.
454 </para>
455
456 <section id='usingpoky-extend-customimage-custombb'>
457 <title>Customizing Images Using Custom .bb Files</title>
458
459 <para>
460 One way to get additional software into an image is to create a custom image.
461 The following example shows the form for the two lines you need:
462 <literallayout class='monospaced'>
463 IMAGE_INSTALL = "task-core-x11-base package1 package2"
464
465 inherit core-image
466 </literallayout>
467 </para>
468
469 <para>
470 By creating a custom image, a developer has total control
471 over the contents of the image.
472 It is important to use the correct names of packages in the
473 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
474 variable.
475 You must use the OpenEmbedded notation and not the Debian notation for the names
476 (e.g. <filename>eglibc-dev</filename> instead of <filename>libc6-dev</filename>).
477 </para>
478
479 <para>
480 The other method for creating a custom image is to modify an existing image.
481 For example, if a developer wants to add <filename>strace</filename> into
482 the <filename>core-image-sato</filename> image, they can use the following recipe:
483 <literallayout class='monospaced'>
484 require core-image-sato.bb
485
486 IMAGE_INSTALL += "strace"
487 </literallayout>
488 </para>
489 </section>
490
491 <section id='usingpoky-extend-customimage-customtasks'>
492 <title>Customizing Images Using Custom Tasks</title>
493
494 <para>
495 For complex custom images, the best approach is to create a custom task package
496 that is used to build the image or images.
497 A good example of a tasks package is
498 <filename>meta/recipes-sato/tasks/task-poky.bb</filename>.
499 The
500 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename>
501 variable lists the task packages to build along with the complementary
502 <filename>-dbg</filename> and <filename>-dev</filename> packages.
503 For each package added, you can use
504 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename>
505 and
506 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename>
507 entries to provide a list of packages the parent task package should contain.
508 Following is an example:
509 <literallayout class='monospaced'>
510 DESCRIPTION = "My Custom Tasks"
511
512 PACKAGES = "\
513 task-custom-apps \
514 task-custom-apps-dbg \
515 task-custom-apps-dev \
516 task-custom-tools \
517 task-custom-tools-dbg \
518 task-custom-tools-dev \
519 "
520
521 RDEPENDS_task-custom-apps = "\
522 dropbear \
523 portmap \
524 psplash"
525
526 RDEPENDS_task-custom-tools = "\
527 oprofile \
528 oprofileui-server \
529 lttng-control \
530 lttng-viewer"
531
532 RRECOMMENDS_task-custom-tools = "\
533 kernel-module-oprofile"
534 </literallayout>
535 </para>
536
537 <para>
538 In the previous example, two task packages are created with their dependencies and their
539 recommended package dependencies listed: <filename>task-custom-apps</filename>, and
540 <filename>task-custom-tools</filename>.
541 To build an image using these task packages, you need to add
542 <filename>task-custom-apps</filename> and/or
543 <filename>task-custom-tools</filename> to
544 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>.
545 For other forms of image dependencies see the other areas of this section.
546 </para>
547 </section>
548
549 <section id='usingpoky-extend-customimage-imagefeatures'>
550 <title>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and
551 <filename>EXTRA_IMAGE_FEATURES</filename></title>
552
553 <para>
554 Ultimately users might want to add extra image features to the set used by
555 Yocto Project with the
556 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename>
557 variable.
558 To create these features, the best reference is
559 <filename>meta/classes/core-image.bbclass</filename>, which shows how the
560 Yocto Project achieves this.
561 In summary, the file looks at the contents of the
562 <filename>IMAGE_FEATURES</filename>
563 variable and then maps that into a set of tasks or packages.
564 Based on this information the
565 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'> IMAGE_INSTALL</ulink></filename>
566 variable is generated automatically.
567 Users can add extra features by extending the class or creating a custom class for use
568 with specialized image <filename>.bb</filename> files.
569 You can also add more features by configuring the
570 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</ulink></filename>
571 variable in the <filename>local.conf</filename> file found in the Yocto Project
572 files located in the build directory.
573 </para>
574
575 <para>
576 The Yocto Project ships with two SSH servers you can use in your images:
577 Dropbear and OpenSSH.
578 Dropbear is a minimal SSH server appropriate for resource-constrained environments,
579 while OpenSSH is a well-known standard SSH server implementation.
580 By default, the <filename>core-image-sato</filename> image is configured to use Dropbear.
581 The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename>
582 images both include OpenSSH.
583 To change these defaults, edit the <filename>IMAGE_FEATURES</filename> variable
584 so that it sets the image you are working with to include
585 <filename>ssh-server-dropbear</filename> or <filename>ssh-server-openssh</filename>.
586 </para>
587 </section>
588
589 <section id='usingpoky-extend-customimage-localconf'>
590 <title>Customizing Images Using <filename>local.conf</filename></title>
591
592 <para>
593 It is possible to customize image contents by using variables from your
594 local configuration in your <filename>conf/local.conf</filename> file.
595 Because it is limited to local use, this method generally only allows you to
596 add packages and is not as flexible as creating your own customized image.
597 When you add packages using local variables this way, you need to realize that
598 these variable changes affect all images at the same time and might not be
599 what you require.
600 </para>
601
602 <section id='adding-packages'>
603 <title>Adding Packages</title>
604
605 <para>
606 The simplest way to add extra packages to all images is by using the
607 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
608 variable with the <filename>_append</filename> operator:
609 <literallayout class='monospaced'>
610 IMAGE_INSTALL_append = " strace"
611 </literallayout>
612 Use of the syntax is important.
613 Specifically, the space between the quote and the package name, which is
614 <filename>strace</filename> in this example.
615 This space is required since the <filename>_append</filename>
616 operator does not add the space.
617 </para>
618
619 <para>
620 Furthermore, you must use <filename>_append</filename> instead of the <filename>+=</filename>
621 operator if you want to avoid ordering issues.
622 The reason for this is because doing so unconditionally appends to the variable and
623 avoids ordering problems due to the variable being set in image recipes and
624 <filename>.bbclass</filename> files with operators like <filename>?=</filename>.
625 Using <filename>_append</filename> ensures the operation takes affect.
626 </para>
627
628 <para>
629 As shown in its simplest use, <filename>IMAGE_INSTALL_append</filename> affects
630 all images.
631 It is possible to extend the syntax so that the variable applies to a specific image only.
632 Here is an example:
633 <literallayout class='monospaced'>
634 IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
635 </literallayout>
636 This example adds <filename>strace</filename> to <filename>core-image-minimal</filename>
637 only.
638 </para>
639
640 <para>
641 You can add packages using a similar approach through the
642 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'>CORE_IMAGE_EXTRA_INSTALL</ulink></filename>
643 variable.
644 If you use this variable, only <filename>core-image-*</filename> images are affected.
645 </para>
646 </section>
647
648 <section id='excluding-packages'>
649 <title>Excluding Packages</title>
650
651 <para>
652 It is possible to filter or mask out <filename>.bb</filename> and
653 <filename>.bbappend</filename> files such that BitBake ignores them during
654 the build.
655 You can do this by providing an expression with the
656 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBMASK'>BBMASK</ulink></filename>
657 variable.
658 Here is an example:
659 <literallayout class='monospaced'>
660 BBMASK = ".*/meta-mymachine/recipes-maybe/"
661 </literallayout>
662 Here, all <filename>.bb</filename> and <filename>.bbappend</filename> files
663 in the directory that matches the expression are ignored during the build
664 process.
665 </para>
666 </section>
667 </section>
668 </section>
669
448 <section id='usingpoky-extend-addpkg'> 670 <section id='usingpoky-extend-addpkg'>
449 <title>Adding a Package</title> 671 <title>Adding a Package</title>
450 672
@@ -774,228 +996,6 @@
774 </section> 996 </section>
775 </section> 997 </section>
776 998
777 <section id='usingpoky-extend-customimage'>
778 <title>Customizing Images</title>
779
780 <para>
781 You can customize Yocto Project images to satisfy particular requirements.
782 This section describes several methods and provides guidelines for each.
783 </para>
784
785 <section id='usingpoky-extend-customimage-custombb'>
786 <title>Customizing Images Using Custom .bb Files</title>
787
788 <para>
789 One way to get additional software into an image is to create a custom image.
790 The following example shows the form for the two lines you need:
791 <literallayout class='monospaced'>
792 IMAGE_INSTALL = "task-core-x11-base package1 package2"
793
794 inherit core-image
795 </literallayout>
796 </para>
797
798 <para>
799 By creating a custom image, a developer has total control
800 over the contents of the image.
801 It is important to use the correct names of packages in the
802 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
803 variable.
804 You must use the OpenEmbedded notation and not the Debian notation for the names
805 (e.g. <filename>eglibc-dev</filename> instead of <filename>libc6-dev</filename>).
806 </para>
807
808 <para>
809 The other method for creating a custom image is to modify an existing image.
810 For example, if a developer wants to add <filename>strace</filename> into
811 the <filename>core-image-sato</filename> image, they can use the following recipe:
812 <literallayout class='monospaced'>
813 require core-image-sato.bb
814
815 IMAGE_INSTALL += "strace"
816 </literallayout>
817 </para>
818 </section>
819
820 <section id='usingpoky-extend-customimage-customtasks'>
821 <title>Customizing Images Using Custom Tasks</title>
822
823 <para>
824 For complex custom images, the best approach is to create a custom task package
825 that is used to build the image or images.
826 A good example of a tasks package is
827 <filename>meta/recipes-sato/tasks/task-poky.bb</filename>.
828 The
829 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename>
830 variable lists the task packages to build along with the complementary
831 <filename>-dbg</filename> and <filename>-dev</filename> packages.
832 For each package added, you can use
833 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename>
834 and
835 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename>
836 entries to provide a list of packages the parent task package should contain.
837 Following is an example:
838 <literallayout class='monospaced'>
839 DESCRIPTION = "My Custom Tasks"
840
841 PACKAGES = "\
842 task-custom-apps \
843 task-custom-apps-dbg \
844 task-custom-apps-dev \
845 task-custom-tools \
846 task-custom-tools-dbg \
847 task-custom-tools-dev \
848 "
849
850 RDEPENDS_task-custom-apps = "\
851 dropbear \
852 portmap \
853 psplash"
854
855 RDEPENDS_task-custom-tools = "\
856 oprofile \
857 oprofileui-server \
858 lttng-control \
859 lttng-viewer"
860
861 RRECOMMENDS_task-custom-tools = "\
862 kernel-module-oprofile"
863 </literallayout>
864 </para>
865
866 <para>
867 In the previous example, two task packages are created with their dependencies and their
868 recommended package dependencies listed: <filename>task-custom-apps</filename>, and
869 <filename>task-custom-tools</filename>.
870 To build an image using these task packages, you need to add
871 <filename>task-custom-apps</filename> and/or
872 <filename>task-custom-tools</filename> to
873 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>.
874 For other forms of image dependencies see the other areas of this section.
875 </para>
876 </section>
877
878 <section id='usingpoky-extend-customimage-imagefeatures'>
879 <title>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and
880 <filename>EXTRA_IMAGE_FEATURES</filename></title>
881
882 <para>
883 Ultimately users might want to add extra image features to the set used by
884 Yocto Project with the
885 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename>
886 variable.
887 To create these features, the best reference is
888 <filename>meta/classes/core-image.bbclass</filename>, which shows how the
889 Yocto Project achieves this.
890 In summary, the file looks at the contents of the
891 <filename>IMAGE_FEATURES</filename>
892 variable and then maps that into a set of tasks or packages.
893 Based on this information the
894 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'> IMAGE_INSTALL</ulink></filename>
895 variable is generated automatically.
896 Users can add extra features by extending the class or creating a custom class for use
897 with specialized image <filename>.bb</filename> files.
898 You can also add more features by configuring the
899 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</ulink></filename>
900 variable in the <filename>local.conf</filename> file found in the Yocto Project
901 files located in the build directory.
902 </para>
903
904 <para>
905 The Yocto Project ships with two SSH servers you can use in your images:
906 Dropbear and OpenSSH.
907 Dropbear is a minimal SSH server appropriate for resource-constrained environments,
908 while OpenSSH is a well-known standard SSH server implementation.
909 By default, the <filename>core-image-sato</filename> image is configured to use Dropbear.
910 The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename>
911 images both include OpenSSH.
912 To change these defaults, edit the <filename>IMAGE_FEATURES</filename> variable
913 so that it sets the image you are working with to include
914 <filename>ssh-server-dropbear</filename> or <filename>ssh-server-openssh</filename>.
915 </para>
916 </section>
917
918 <section id='usingpoky-extend-customimage-localconf'>
919 <title>Customizing Images Using <filename>local.conf</filename></title>
920
921 <para>
922 It is possible to customize image contents by using variables from your
923 local configuration in your <filename>conf/local.conf</filename> file.
924 Because it is limited to local use, this method generally only allows you to
925 add packages and is not as flexible as creating your own customized image.
926 When you add packages using local variables this way, you need to realize that
927 these variable changes affect all images at the same time and might not be
928 what you require.
929 </para>
930
931 <section id='adding-packages'>
932 <title>Adding Packages</title>
933
934 <para>
935 The simplest way to add extra packages to all images is by using the
936 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
937 variable with the <filename>_append</filename> operator:
938 <literallayout class='monospaced'>
939 IMAGE_INSTALL_append = " strace"
940 </literallayout>
941 Use of the syntax is important.
942 Specifically, the space between the quote and the package name, which is
943 <filename>strace</filename> in this example.
944 This space is required since the <filename>_append</filename>
945 operator does not add the space.
946 </para>
947
948 <para>
949 Furthermore, you must use <filename>_append</filename> instead of the <filename>+=</filename>
950 operator if you want to avoid ordering issues.
951 The reason for this is because doing so unconditionally appends to the variable and
952 avoids ordering problems due to the variable being set in image recipes and
953 <filename>.bbclass</filename> files with operators like <filename>?=</filename>.
954 Using <filename>_append</filename> ensures the operation takes affect.
955 </para>
956
957 <para>
958 As shown in its simplest use, <filename>IMAGE_INSTALL_append</filename> affects
959 all images.
960 It is possible to extend the syntax so that the variable applies to a specific image only.
961 Here is an example:
962 <literallayout class='monospaced'>
963 IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
964 </literallayout>
965 This example adds <filename>strace</filename> to <filename>core-image-minimal</filename>
966 only.
967 </para>
968
969 <para>
970 You can add packages using a similar approach through the
971 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'>CORE_IMAGE_EXTRA_INSTALL</ulink></filename>
972 variable.
973 If you use this variable, only <filename>core-image-*</filename> images are affected.
974 </para>
975 </section>
976
977 <section id='excluding-packages'>
978 <title>Excluding Packages</title>
979
980 <para>
981 It is possible to filter or mask out <filename>.bb</filename> and
982 <filename>.bbappend</filename> files such that BitBake ignores them during
983 the build.
984 You can do this by providing an expression with the
985 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBMASK'>BBMASK</ulink></filename>
986 variable.
987 Here is an example:
988 <literallayout class='monospaced'>
989 BBMASK = ".*/meta-mymachine/recipes-maybe/"
990 </literallayout>
991 Here, all <filename>.bb</filename> and <filename>.bbappend</filename> files
992 in the directory that matches the expression are ignored during the build
993 process.
994 </para>
995 </section>
996 </section>
997 </section>
998
999 <section id="platdev-newmachine"> 999 <section id="platdev-newmachine">
1000 <title>Porting the Yocto Project to a New Machine</title> 1000 <title>Porting the Yocto Project to a New Machine</title>
1001 1001
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-15 16:53:26 +0000