summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-04-28 16:13:17 (GMT)
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-05-10 11:13:32 (GMT)
commit7fdd0ac087328524f27ae42d503898dbd113f417 (patch)
tree5a7c2f2183e18ad9863055618e7bc8869e748de5
parent744cd8cfd7a3c3467a16465522183adc52518e73 (diff)
downloadpoky-7fdd0ac087328524f27ae42d503898dbd113f417.tar.gz
ref-manual: Applied 2.3 Migration review comments.
(From yocto-docs rev: 08a077adea37d5b3eb3ac119b1a5981a6fef21a3) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/ref-manual/migration.xml169
1 files changed, 120 insertions, 49 deletions
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 5b6409d..ddd6644 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -3963,15 +3963,23 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.
3963 Yocto Project 2.3 Release from the prior release. 3963 Yocto Project 2.3 Release from the prior release.
3964 </para> 3964 </para>
3965 3965
3966 <section id='migration-2.3-sysroots'> 3966 <section id='migration-2.3-recipe-specific-sysroots'>
3967 <title>Sysroots</title> 3967 <title>Recipe-specific Sysroots</title>
3968 3968
3969 <para> 3969 <para>
3970 The Open-Embedded build system now uses one sysroot per 3970 The Open-Embedded build system now uses one sysroot per
3971 recipe to resolve long-standing issues with configuration 3971 recipe to resolve long-standing issues with configuration
3972 script auto-detection of undeclared dependencies. 3972 script auto-detection of undeclared dependencies.
3973 Consequently, you must explicitly declare all build-time 3973 Consequently, you might find that some of your previously
3974 dependencies for your recipe. 3974 written custom recipes are missing declared dependencies,
3975 particularly those dependencies that are incidentally built
3976 earlier in a typical build process and thus are already likely
3977 to be present in the shared sysroot in a previous release.
3978 </para>
3979
3980 <para>
3981 Because of this new feature, you must explicitly declare all
3982 build-time dependencies for your recipe.
3975 If you do not declare these dependencies, they are not 3983 If you do not declare these dependencies, they are not
3976 populated into the sysroot for the recipe. 3984 populated into the sysroot for the recipe.
3977 </para> 3985 </para>
@@ -3987,11 +3995,14 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.
3987 <title><filename>PATH</filename> Variable</title> 3995 <title><filename>PATH</filename> Variable</title>
3988 3996
3989 <para> 3997 <para>
3990 The environment variable <filename>PATH</filename> is now 3998 Within the environment used to run build tasks, the environment
3991 sanitized such that symbolic links linking only the binaries 3999 variable <filename>PATH</filename> is now sanitized such that
3992 from the host mentioned in the 4000 symbolic links linking only the binaries from the host mentioned
3993 <filename>HOSTTOOLS</filename> and 4001 in the
3994 <filename>HOSTTOOLS_NONFATAL</filename> variables into 4002 <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link>
4003 and
4004 <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link>
4005 variables into
3995 their own directory are added to <filename>PATH</filename>. 4006 their own directory are added to <filename>PATH</filename>.
3996 Consequently, any native binaries that you need to call should 4007 Consequently, any native binaries that you need to call should
3997 either be in one of these two variables at the configuration 4008 either be in one of these two variables at the configuration
@@ -3999,10 +4010,17 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.
3999 </para> 4010 </para>
4000 4011
4001 <para> 4012 <para>
4002 Alternatively, you can use a native recipe (i.e. 4013 Alternatively, you can add a native recipe (i.e.
4003 <filename>-native</filename>) that includes the recipe's 4014 <filename>-native</filename>) that provides the
4015 binary to the recipe's
4004 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> 4016 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
4005 value. 4017 value.
4018 <note>
4019 <filename>PATH</filename> is not sanitized in the same way
4020 within <filename>devshell</filename>.
4021 If it were, you would have difficulty running host tools for
4022 development and debugging within the shell.
4023 </note>
4006 </para> 4024 </para>
4007 </section> 4025 </section>
4008 4026
@@ -4023,29 +4041,6 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.
4023 </para> 4041 </para>
4024 </section> 4042 </section>
4025 4043
4026 <section id='migration-2.3-dependency-tree-information'>
4027 <title>Dependency Tree Information</title>
4028
4029 <para>
4030 The <filename>package-depends.dot</filename> and
4031 <filename>pn-depends.dot</filename> files as previously generated
4032 using the <filename>bitbake -g</filename> command have been
4033 removed.
4034 A <filename>recipe-depends.dot</filename> file
4035 is now generated as a collapsed version of
4036 <filename>task-depends.dot</filename> instead.
4037 </para>
4038
4039 <para>
4040 The reason for this change is because
4041 <filename>package-depends.dot</filename> and
4042 <filename>pn-depends.dot</filename> largely date back to a time
4043 before task-based execution and do not take into account
4044 task-level dependencies between recipes, which could be
4045 misleading.
4046 </para>
4047 </section>
4048
4049 <section id='migration-2.3-bitbake-changes'> 4044 <section id='migration-2.3-bitbake-changes'>
4050 <title>BitBake Changes</title> 4045 <title>BitBake Changes</title>
4051 4046
@@ -4053,9 +4048,37 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.
4053 The following changes took place for BitBake: 4048 The following changes took place for BitBake:
4054 <itemizedlist> 4049 <itemizedlist>
4055 <listitem><para> 4050 <listitem><para>
4051 <emphasis>BitBake's Graphical Dependency Explorer UI Replaced:</emphasis>
4056 BitBake's graphical dependency explorer UI 4052 BitBake's graphical dependency explorer UI
4057 <filename>depexp</filename> was replaced by 4053 <filename>depexp</filename> was replaced by
4058 <filename>taskexp</filename>. 4054 <filename>taskexp</filename> ("Task Explorer"), which
4055 provides a graphical way of exploring the
4056 <filename>task-depends.dot</filename> file.
4057 The data presented by Task Explorer is much more
4058 accurate than the data that is presented by
4059 <filename>depexp</filename>.
4060 Being able to visualize the data is an often requested
4061 feature as standard <filename>*.dot</filename> file
4062 viewers cannot usual cope with the size of
4063 the <filename>task-depends.dot</filename> file.
4064 </para></listitem>
4065 <listitem><para>
4066 <emphasis>Dependency Tree Information Removals:</emphasis>
4067 The <filename>package-depends.dot</filename> and
4068 <filename>pn-depends.dot</filename> files as previously
4069 generated using the <filename>bitbake -g</filename> command
4070 have been removed.
4071 A <filename>recipe-depends.dot</filename> file
4072 is now generated as a collapsed version of
4073 <filename>task-depends.dot</filename> instead.
4074 </para>
4075
4076 <para>The reason for this change is because
4077 <filename>package-depends.dot</filename> and
4078 <filename>pn-depends.dot</filename> largely date back
4079 to a time before task-based execution and do not take
4080 into account task-level dependencies between recipes,
4081 which could be misleading.
4059 </para></listitem> 4082 </para></listitem>
4060 </itemizedlist> 4083 </itemizedlist>
4061 </para> 4084 </para>
@@ -4067,6 +4090,17 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.
4067 <para> 4090 <para>
4068 Absolute symbolic links (symlinks) within staged files are no 4091 Absolute symbolic links (symlinks) within staged files are no
4069 longer permitted and now trigger an error. 4092 longer permitted and now trigger an error.
4093 Any explicit creation of symlinks can use the
4094 <filename>lnr</filename> script, which is a replacement for
4095 <filename>ln -r</filename>.
4096 </para>
4097
4098 <para>
4099 If the build scripts in the software that the recipe is building
4100 are creating a number of absolute symlinks that need to be
4101 corrected, you can inherit
4102 <filename>relative_symlinks</filename> within the recipe to turn
4103 those absolute symlinks into relative symlinks.
4070 </para> 4104 </para>
4071 </section> 4105 </section>
4072 4106
@@ -4077,6 +4111,39 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.
4077 Older GPLv2 versions of GPLv3 recipes have moved to a 4111 Older GPLv2 versions of GPLv3 recipes have moved to a
4078 separate <filename>meta-gplv2</filename> layer. 4112 separate <filename>meta-gplv2</filename> layer.
4079 </para> 4113 </para>
4114
4115 <para>
4116 If you use
4117 <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>
4118 to exclude GPLv3 or set
4119 <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link>
4120 to select recipes that use GPLv3, then you must add the
4121 <filename>meta-gplv2</filename> layer to your configuration.
4122 <note>
4123 You can find <filename>meta-gplv2</filename> layer in the
4124 OpenEmbedded layer index at
4125 <ulink url='https://layers.openembedded.org/layerindex/branch/master/layer/meta-gplv2/'></ulink>.
4126 </note>
4127 </para>
4128
4129 <para>
4130 These relocated GPLv3 recipes do not receive the same level of
4131 maintenance as other core recipes.
4132 The recipes do not get security fixes and upstream no longer
4133 maintains them.
4134 In fact, the upstream community is actively hostile towards people
4135 that use the old versions of the recipes.
4136 Moving these recipes into a separate layer both makes the different
4137 needs of the recipes clearer and clearly identifies the number of
4138 these recipes.
4139 <note>
4140 The long-term solution might be to move to BSD-licensed
4141 replacements of the GPLv3 components for those that need to
4142 exclude GPLv3-licensed components from the target system.
4143 This solution will be investigated for future Yocto
4144 Project releases.
4145 </note>
4146 </para>
4080 </section> 4147 </section>
4081 4148
4082 <section id='migration-2.3-package-management-changes'> 4149 <section id='migration-2.3-package-management-changes'>
@@ -4109,30 +4176,30 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.
4109 it and maintaining the port is non-trivial. 4176 it and maintaining the port is non-trivial.
4110 </para></listitem> 4177 </para></listitem>
4111 <listitem><para> 4178 <listitem><para>
4112 Rpm 5.x itself is more or less unmaintained both 4179 Rpm 5.x itself has limited maintenance upstream,
4113 in the upstream and in Yocto Project. 4180 and the Yocto Project is one of the very few
4114 Community support does not exist around it and 4181 remaining users.
4115 the Yocto Project is the sole remaining user.
4116 </para></listitem> 4182 </para></listitem>
4117 </itemizedlist> 4183 </itemizedlist>
4118 </para></listitem> 4184 </para></listitem>
4119 <listitem><para> 4185 <listitem><para>
4120 Berkeley db 6.x is removed and Berkeley db 5.x becomes 4186 Berkeley DB 6.x is removed and Berkeley DB 5.x becomes
4121 the default: 4187 the default:
4122 <itemizedlist> 4188 <itemizedlist>
4123 <listitem><para> 4189 <listitem><para>
4124 Version 6.x of Berkeley DB has been rejected 4190 Version 6.x of Berkeley DB has largely been
4125 by the open source community due to its hostile 4191 rejected by the open source community due to its
4126 AGPLv3 license. 4192 AGPLv3 license.
4127 Both Fedora and Debian are sticking 4193 As a result, most mainstream open source projects
4128 with db 5.x. 4194 that require DB are still developed and tested with
4195 DB 5.x.
4129 By extension,all the open source projects are still 4196 By extension,all the open source projects are still
4130 developed and tested with db 5.x 4197 developed and tested with DB 5.x
4131 </para></listitem> 4198 </para></listitem>
4132 <listitem><para> 4199 <listitem><para>
4133 In OE-core, the only thing that was requiring 4200 In OE-core, the only thing that was requiring
4134 db 6.x was Rpm 5.x. 4201 DB 6.x was Rpm 5.x.
4135 Thus, no reason exists to continue carrying db 6.x 4202 Thus, no reason exists to continue carrying DB 6.x
4136 in OE-core. 4203 in OE-core.
4137 </para></listitem> 4204 </para></listitem>
4138 </itemizedlist> 4205 </itemizedlist>
@@ -4162,11 +4229,15 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.
4162 </para></listitem> 4229 </para></listitem>
4163 <listitem><para> 4230 <listitem><para>
4164 Signing of remote package feeds using 4231 Signing of remote package feeds using
4165 <filename>PACKAGE_FEED_SIGN</filename> is not supported. 4232 <filename>PACKAGE_FEED_SIGN</filename>
4233 is not currently supported.
4234 This issue will be fully addressed in a future
4235 Yocto Project release.
4166 <note> 4236 <note>
4167 See the defect 4237 See the defect
4168 <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=11209'>11209</ulink> 4238 <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=11209'>11209</ulink>
4169 for more information on a solution. 4239 for more information on a solution to package feed
4240 signing with RPM in the Yocto Project 2.3 release.
4170 </note> 4241 </note>
4171 </para></listitem> 4242 </para></listitem>
4172 </itemizedlist> 4243 </itemizedlist>