summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/migration.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-09-24 12:22:31 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-10-01 22:52:53 +0100
commit7bd3a81ef54b790943577409e30c825fe9d4182c (patch)
tree199b5426f5e5b1cf21fb876a6b944235da1573f9 /documentation/ref-manual/migration.xml
parent155961db71e15356ce5ccd6baf4e57e5f9ad6799 (diff)
downloadpoky-7bd3a81ef54b790943577409e30c825fe9d4182c.tar.gz
ref-manual: New migration section for 1.5 and new variables
1. Created the first draft of the new migration section for moving to the YP 1.5 release. 2. Created new variable glossary descriptions for the SDK_NAME, IMAGE_NAME, and DATETIME variables. (From yocto-docs rev: 26e6a7675183b49a0ee8059d81218dbc5cd14bd4) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/migration.xml')
-rw-r--r--documentation/ref-manual/migration.xml463
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<!--
585vim: expandtab tw=80 ts=4 1048vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-30 18:55:04 +0000