diff options
Diffstat (limited to 'documentation/ref-manual/migration.xml')
-rw-r--r-- | documentation/ref-manual/migration.xml | 463 |
1 files changed, 463 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml index 302ce4cea8..af7eed3892 100644 --- a/documentation/ref-manual/migration.xml +++ b/documentation/ref-manual/migration.xml | |||
@@ -580,6 +580,469 @@ | |||
580 | </para> | 580 | </para> |
581 | </section> | 581 | </section> |
582 | </section> | 582 | </section> |
583 | |||
584 | <section id='moving-to-the-yocto-project-1.5-release'> | ||
585 | <title>Moving to the Yocto Project 1.5 Release</title> | ||
586 | |||
587 | <para> | ||
588 | This section provides migration information for moving to the | ||
589 | Yocto Project 1.5 Release from the prior release. | ||
590 | </para> | ||
591 | |||
592 | <section id='migration-1.5-host-dependency-changes'> | ||
593 | <title>Host Dependency Changes</title> | ||
594 | |||
595 | <para> | ||
596 | The OpenEmbedded build system now has some additional requirements | ||
597 | on the host system: | ||
598 | <literallayout class='monospaced'> | ||
599 | Python 2.7.3+ | ||
600 | |||
601 | tar 1.24+ | ||
602 | |||
603 | git 1.7.5+ | ||
604 | |||
605 | Patched version of make if you are using make version 3.82. Most | ||
606 | distributions that provide make 3.82 have now done this. | ||
607 | </literallayout> | ||
608 | If the Linux distribution you are using on your build host | ||
609 | does not provide packages for these, you can install and use | ||
610 | the Buildtools tarball, which provides an SDK-like environment | ||
611 | containing them. | ||
612 | </para> | ||
613 | |||
614 | <para> | ||
615 | For more information on this requirement, see the | ||
616 | "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>" | ||
617 | section. | ||
618 | </para> | ||
619 | </section> | ||
620 | |||
621 | <section id='migration-1.5-atom-pc-bsp'> | ||
622 | <title><filename>atom-pc</filename> Board Support Package (BSP)</title> | ||
623 | |||
624 | <para> | ||
625 | The <filename>atom-pc</filename> hardware reference BSP has been | ||
626 | replaced by a <filename>genericx86</filename> BSP. | ||
627 | This BSP is not necessarily guaranteed to work on all x86 | ||
628 | hardware, but it will run on a wider range of systems than the | ||
629 | <filename>atom-pc</filename> did. | ||
630 | <note> | ||
631 | Additionally, a <filename>genericx86-64</filename> BSP has been | ||
632 | added for 64-bit systems. | ||
633 | </note> | ||
634 | </para> | ||
635 | </section> | ||
636 | |||
637 | <section id='migration-1.5-remove-operator'> | ||
638 | <title>BitBake <filename>_remove</filename> Operator</title> | ||
639 | |||
640 | <para> | ||
641 | BitBake now supports a <filename>_remove</filename> operator. | ||
642 | The addition of this operator means you will have to rename any | ||
643 | items in recipe space (functions, variables) whose names currently | ||
644 | contain <filename>_remove_</filename> or end with | ||
645 | <filename>_remove</filename> to avoid unexpected behavior. | ||
646 | </para> | ||
647 | </section> | ||
648 | |||
649 | <section id='migration-1.5-qa-warnings'> | ||
650 | <title>QA Warnings</title> | ||
651 | |||
652 | <para> | ||
653 | The following QA warnings exist: | ||
654 | <itemizedlist> | ||
655 | <listitem><para> | ||
656 | If you have customized | ||
657 | <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link> | ||
658 | or <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> | ||
659 | values in your configuration, check that they contain all of | ||
660 | the issues that you wish to be reported. | ||
661 | Previous Yocto Project versions contained a bug that meant | ||
662 | that any item not mentioned in <filename>ERROR_QA</filename> | ||
663 | or <filename>WARN_QA</filename> would be treated as a | ||
664 | warning. | ||
665 | Consequently, several important items were not already in | ||
666 | the default value of <filename>WARN_QA</filename>. | ||
667 | All of the possible QA checks are now documented in the | ||
668 | "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>" | ||
669 | section.</para></listitem> | ||
670 | <listitem><para> | ||
671 | An additional QA check has been added to check if | ||
672 | <filename>/usr/share/info/dir</filename> is being installed. | ||
673 | Your recipe should delete this file within | ||
674 | <filename>do_install</filename> if "make install" is | ||
675 | installing it.</para></listitem> | ||
676 | <listitem><para> | ||
677 | If you are using the buildhistory class, the check for the | ||
678 | package version going backwards is now controlled using a | ||
679 | standard QA check. | ||
680 | Thus, if you have customized your | ||
681 | <filename>ERROR_QA</filename> or | ||
682 | <filename>WARN_QA</filename> values and still wish to have | ||
683 | this check performed, you should add | ||
684 | "version-going-backwards" to your value for one or the | ||
685 | other variables depending on how you wish it to be handled. | ||
686 | </para></listitem> | ||
687 | </itemizedlist> | ||
688 | </para> | ||
689 | </section> | ||
690 | |||
691 | <section id='migration-1.5-directory-layout-changes'> | ||
692 | <title>Directory Layout Changes</title> | ||
693 | |||
694 | <para> | ||
695 | The following directory changes exist: | ||
696 | <itemizedlist> | ||
697 | <listitem><para> | ||
698 | Output SDK installer files are now named to include the | ||
699 | image name and tuning architecture through the | ||
700 | <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link> | ||
701 | variable.</para></listitem> | ||
702 | <listitem><para> | ||
703 | Images and related files are now installed into a directory | ||
704 | that is specific to the machine, instead of a parent | ||
705 | directory containing output files for multiple machines. | ||
706 | The | ||
707 | <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link> | ||
708 | variable continues to point to the directory containing | ||
709 | images for the current | ||
710 | <link linkend='var-MACHINE'><filename>MACHINE</filename></link> | ||
711 | and should be used anywhere there is a need to refer to | ||
712 | this directory. | ||
713 | The <filename>runqemu</filename> script now uses this | ||
714 | variable to find images and kernel binaries and will use | ||
715 | BitBake to determine the directory. | ||
716 | Alternatively, you can set the | ||
717 | <filename>DEPLOY_DIR_IMAGE</filename> variable in the | ||
718 | external environment.</para></listitem> | ||
719 | <listitem><para> | ||
720 | When buildhistory is enabled, its output is now written | ||
721 | under the | ||
722 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> | ||
723 | rather than | ||
724 | <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>. | ||
725 | Doing so makes it a easier to delete | ||
726 | <filename>TMPDIR</filename> and preserve the build history. | ||
727 | Additionally, data for produced SDKs is now split by | ||
728 | <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>. | ||
729 | </para></listitem> | ||
730 | <listitem><para> | ||
731 | The <filename>pkgdata</filename> directory produced as | ||
732 | part of the packaging process has been collapsed into a | ||
733 | single machine-specific directory.</para></listitem> | ||
734 | </itemizedlist> | ||
735 | </para> | ||
736 | </section> | ||
737 | |||
738 | <section id='migration-1.5-shortened-git-srcrev-values'> | ||
739 | <title>Shortened Git <filename>SRCREV</filename> Values</title> | ||
740 | |||
741 | <para> | ||
742 | BitBake will now shorten revisions from Git repositories from the | ||
743 | normal 40 characters down to 10 characters within | ||
744 | <link linkend='var-SRCPV'><filename>SRCPV</filename></link> | ||
745 | for improved usability in path and file names. | ||
746 | This change should be safe within contexts where these revisions | ||
747 | are used because the chances of spatially close collisions | ||
748 | is very low. | ||
749 | <note> | ||
750 | Distant collisions are not a major issue in the way | ||
751 | the values are used. | ||
752 | </note> | ||
753 | </para> | ||
754 | </section> | ||
755 | |||
756 | <section id='migration-1.5-image-features'> | ||
757 | <title><filename>IMAGE_FEATURES</filename></title> | ||
758 | |||
759 | <para> | ||
760 | These | ||
761 | <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> | ||
762 | exist: | ||
763 | <itemizedlist> | ||
764 | <listitem><para> | ||
765 | The value of | ||
766 | <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> | ||
767 | is now validated to ensure invalid feature items are not | ||
768 | added. | ||
769 | Some users mistakenly add package names to this variable | ||
770 | instead of using | ||
771 | <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link> | ||
772 | in order to have the package added to the image, which does | ||
773 | not work. | ||
774 | This change is intended to catch those kinds of situations. | ||
775 | Valid <filename>IMAGE_FEATURES</filename> are drawn from | ||
776 | <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link> | ||
777 | definitions, | ||
778 | <link linkend='var-COMPLEMENTARY_GLOBS'><filename>COMPLEMENTARY_GLOBS</filename></link> | ||
779 | and a new 'validitems' varflag on | ||
780 | <filename>IMAGE_FEATURES</filename>. | ||
781 | This change allows additional features to be added if they | ||
782 | are not provided using the previous two mechanisms. | ||
783 | </para></listitem> | ||
784 | <listitem><para> | ||
785 | The previously deprecated "apps-console-core" | ||
786 | <filename>IMAGE_FEATURES</filename> item is no longer | ||
787 | supported. | ||
788 | Add "splash" to <filename>IMAGE_FEATURES</filename> if you | ||
789 | wish to have the splash screen enabled, since this is | ||
790 | all that apps-console-core was doing.</para></listitem> | ||
791 | </itemizedlist> | ||
792 | </para> | ||
793 | </section> | ||
794 | |||
795 | <section id='migration-1.5-run'> | ||
796 | <title><filename>/run</filename></title> | ||
797 | |||
798 | <para> | ||
799 | The <filename>/run</filename> directory from the Filesystem | ||
800 | Hierarchy Standard 3.0 has been introduced. | ||
801 | You can find some of the implications for this change | ||
802 | <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873'>here</ulink>. | ||
803 | The change also means that recipes that install files to | ||
804 | <filename>/var/run</filename> must be changed. | ||
805 | You can find a guide on how to make these changes | ||
806 | <ulink url='http://permalink.gmane.org/gmane.comp.handhelds.openembedded/58530'>here</ulink>. | ||
807 | </para> | ||
808 | </section> | ||
809 | |||
810 | <section id='migration-1.5-removal-of-package-manager-database-within-image-recipes'> | ||
811 | <title>Removal of Package Manager Database Within Image Recipes</title> | ||
812 | |||
813 | <para> | ||
814 | The image <filename>core-image-minimal</filename> no longer adds | ||
815 | <filename>remove_packaging_data_files</filename> to | ||
816 | <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>. | ||
817 | This addition is now handled automatically when "package-management" | ||
818 | is not in | ||
819 | <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>. | ||
820 | If you have custom image recipes that makes this addition, | ||
821 | you should remove the lines, as it is not needed and may interfere | ||
822 | with correct operation of postinstall scripts. | ||
823 | </para> | ||
824 | </section> | ||
825 | |||
826 | <section id='migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time'> | ||
827 | <title>Images Now Rebuild Only on Changes Instead of Every Time</title> | ||
828 | |||
829 | <para> | ||
830 | The <filename>do_rootfs</filename> and other related image | ||
831 | construction tasks are no longer marked as "nostamp". | ||
832 | Consequently, they will only be re-executed when their inputs have | ||
833 | changed. | ||
834 | Previous versions of the OpenEmbedded build system always rebuilt | ||
835 | the image when requested rather when necessary. | ||
836 | </para> | ||
837 | </section> | ||
838 | |||
839 | <section id='migration-1.5-task-recipes'> | ||
840 | <title>Task Recipes</title> | ||
841 | |||
842 | <para> | ||
843 | The previously deprecated <filename>task.bbclass</filename> has | ||
844 | now been dropped. | ||
845 | You should remove recipes that previously inherited from this task | ||
846 | and rename from <filename>task-*</filename> to | ||
847 | <filename>packagegroup-*</filename> and inherit packagegroup | ||
848 | instead. | ||
849 | </para> | ||
850 | |||
851 | <para> | ||
852 | For more information, see the | ||
853 | "<link linkend='ref-classes-packagegroup'>Package Groups - <filename>packagegroup.bbclass</filename></link>" | ||
854 | section. | ||
855 | </para> | ||
856 | </section> | ||
857 | |||
858 | <section id='migration-1.5-busybox'> | ||
859 | <title>BusyBox</title> | ||
860 | |||
861 | <para> | ||
862 | By default, we now split BusyBox into two binaries: | ||
863 | one that is suid root for those components that need it, and | ||
864 | another for the rest of the components. | ||
865 | Splitting BusyBox allows for optimization that eliminates the | ||
866 | <filename>tinylogin</filename> recipe as recommended by upstream. | ||
867 | You can disable this split by setting | ||
868 | <link linkend='var-BUSYBOX_SPLIT_SUID'><filename>BUSYBOX_SPLIT_SUID</filename></link> | ||
869 | to "0". | ||
870 | </para> | ||
871 | </section> | ||
872 | |||
873 | <section id='migration-1.5-automated-image-testing'> | ||
874 | <title>Automated Image Testing</title> | ||
875 | |||
876 | <para> | ||
877 | A new automated image testing framework has been added | ||
878 | through the | ||
879 | <link linkend='ref-classes-testimage'><filename>testimage*.bbclass</filename></link> | ||
880 | class. | ||
881 | This framework replaces the older | ||
882 | <filename>imagetest-qemu</filename> framework. | ||
883 | </para> | ||
884 | |||
885 | <para> | ||
886 | You can learn more about performing automated image tests in the | ||
887 | "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>" | ||
888 | section. | ||
889 | </para> | ||
890 | </section> | ||
891 | |||
892 | <section id='removed-renamed-recipes'> | ||
893 | <title>Removed and Renamed Recipes</title> | ||
894 | |||
895 | <itemizedlist> | ||
896 | <listitem><para> | ||
897 | The <filename>linux-yocto</filename> 3.2 kernel has been | ||
898 | removed.</para></listitem> | ||
899 | <listitem><para> | ||
900 | <filename>libtool-nativesdk</filename> has been renamed to | ||
901 | <filename>nativesdk-libtool</filename>.</para></listitem> | ||
902 | <listitem><para> | ||
903 | <filename>tinylogin</filename> has been removed. | ||
904 | It has been replaced by a suid portion of Busybox. | ||
905 | See the | ||
906 | "<link linkend='migration-1.5-busybox'>BusyBox</link>" section | ||
907 | for more information.</para></listitem> | ||
908 | <listitem><para> | ||
909 | <filename>external-python-tarball</filename> has been renamed | ||
910 | to <filename>buildtools-tarball</filename>. | ||
911 | </para></listitem> | ||
912 | <listitem><para> | ||
913 | <filename>web-webkit</filename> has been removed. | ||
914 | It has been functionally replaced by | ||
915 | <filename>midori</filename>.</para></listitem> | ||
916 | <listitem><para> | ||
917 | <filename>imake</filename> has been removed. | ||
918 | It is no longer needed by any other recipe. | ||
919 | </para></listitem> | ||
920 | <listitem><para> | ||
921 | <filename>transfig-native</filename> has been removed. | ||
922 | It is no longer needed by any other recipe. | ||
923 | </para></listitem> | ||
924 | <listitem><para> | ||
925 | <filename>anjuta-remote-run</filename> has been removed. | ||
926 | Support for Anjuta IDE integration has not existed for some | ||
927 | several releases.</para></listitem> | ||
928 | </itemizedlist> | ||
929 | </section> | ||
930 | |||
931 | <section id='migration-1.5-other-changes'> | ||
932 | <title>Other Changes</title> | ||
933 | |||
934 | <para> | ||
935 | Following is a list of short entries describing other changes: | ||
936 | <itemizedlist> | ||
937 | <listitem><para> | ||
938 | BitBake: <filename>methodpool</filename>: Retire this. | ||
939 | Remove global method scope.</para></listitem> | ||
940 | <listitem><para> | ||
941 | BitBake: server: Remove none server.</para></listitem> | ||
942 | <listitem><para> | ||
943 | BitBake: Drop <filename>bitbake-runtask</filename>. | ||
944 | </para></listitem> | ||
945 | <listitem><para> | ||
946 | Do not recommend <filename>udev-extraconf</filename> | ||
947 | for <filename>udev</filename>.</para></listitem> | ||
948 | <listitem><para> | ||
949 | <filename>udev</filename>: Do not recommend | ||
950 | <filename>pciutils/usbutils ids</filename> | ||
951 | </para></listitem> | ||
952 | <listitem><para> | ||
953 | <filename>run-postinsts</filename>: Make this generic. | ||
954 | </para></listitem> | ||
955 | <listitem><para> | ||
956 | <filename>classes/externalsrc</filename>: Enable global | ||
957 | inherit and simplify usage.</para></listitem> | ||
958 | <listitem><para> | ||
959 | BusyBox: Enable to list suid and non-suid app configs. | ||
960 | </para></listitem> | ||
961 | <listitem><para> | ||
962 | <filename>base-files</filename>: Remove the unnecessary | ||
963 | <filename>/media/xxx</filename> directories. | ||
964 | </para></listitem> | ||
965 | <listitem><para> | ||
966 | <filename>classes/testimage.bbclass</filename>: New class | ||
967 | for image tests. | ||
968 | See the | ||
969 | "<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>" | ||
970 | section for more information.</para></listitem> | ||
971 | <listitem><para> | ||
972 | <filename>alsa-state</filename>: Provide an empty | ||
973 | <filename>asound.conf</filename> by default. | ||
974 | </para></listitem> | ||
975 | <listitem><para> | ||
976 | <filename>classes/image</filename>: Ensure | ||
977 | <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link> | ||
978 | supports pre-renamed package names.</para></listitem> | ||
979 | <listitem><para> | ||
980 | <filename>classes/rootfs_rpm</filename>: Implement | ||
981 | <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link> | ||
982 | for RPM.</para></listitem> | ||
983 | <listitem><para> | ||
984 | <filename>systemd</filename>: Remove | ||
985 | <filename>systemd_unitdir</filename> if | ||
986 | <filename>systemd</filename> is not in distro features. | ||
987 | </para></listitem> | ||
988 | <listitem><para> | ||
989 | <filename>systemd</filename>: Remove | ||
990 | <filename>init.d</filename> dir if | ||
991 | <filename>systemd</filename> unit file is present and | ||
992 | <filename>sysvinit</filename> is not a distro feature. | ||
993 | </para></listitem> | ||
994 | <listitem><para> | ||
995 | <filename>libpam</filename>: Deny all services for the | ||
996 | <filename>OTHER</filename> entries. | ||
997 | </para></listitem> | ||
998 | <listitem><para> | ||
999 | Add <filename>libav</filename> and use it in | ||
1000 | <filename>gst-ffmpeg</filename> by default. | ||
1001 | </para></listitem> | ||
1002 | <listitem><para> | ||
1003 | <filename>image.bbclass</filename>: Move | ||
1004 | <filename>runtime_mapping_rename</filename> to avoid | ||
1005 | conflict with <filename>multilib</filename>. | ||
1006 | See | ||
1007 | <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993'><filename>YOCTO #4993</filename></ulink> | ||
1008 | in Bugzilla for more information. | ||
1009 | </para></listitem> | ||
1010 | <listitem><para> | ||
1011 | <filename>linux-dtb</filename>: Use kernel build system | ||
1012 | to generate the <filename>dtb</filename> files. | ||
1013 | </para></listitem> | ||
1014 | <listitem><para> | ||
1015 | <filename>classes/buildhistory</filename>: Record the | ||
1016 | size of the installed package not the compressed archive. | ||
1017 | </para></listitem> | ||
1018 | <listitem><para> | ||
1019 | <filename>classes/buildhistory</filename>: Avoid mangling | ||
1020 | names in dot graphs for images. | ||
1021 | </para></listitem> | ||
1022 | <listitem><para> | ||
1023 | <filename>buildhistory-diff/buildhistory-collect-srcrevs</filename>: | ||
1024 | Improved command-line handling. | ||
1025 | </para></listitem> | ||
1026 | <listitem><para> | ||
1027 | <filename>kern-tools</filename>: Switch from guilt to | ||
1028 | new <filename>kgit-s2q</filename> tool. | ||
1029 | </para></listitem> | ||
1030 | <listitem><para> | ||
1031 | <filename>poky.conf</filename>: Do not force the addition | ||
1032 | of extra | ||
1033 | <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. | ||
1034 | </para></listitem> | ||
1035 | <listitem><para> | ||
1036 | <filename>bitbake.conf</filename>: Stop providing | ||
1037 | <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename> | ||
1038 | and | ||
1039 | <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename> | ||
1040 | by default. | ||
1041 | </para></listitem> | ||
1042 | </itemizedlist> | ||
1043 | </para> | ||
1044 | </section> | ||
1045 | </section> | ||
583 | </chapter> | 1046 | </chapter> |
584 | <!-- | 1047 | <!-- |
585 | vim: expandtab tw=80 ts=4 | 1048 | vim: expandtab tw=80 ts=4 |