From b1dc0ee121e575f1978cdea409a16bba4040e5b2 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 28 Apr 2017 16:23:48 -0700 Subject: ref-manual, dev-manual: Completed first draft of 2.3 migration section. (From yocto-docs rev: 42ab9e34da640b46d39741c9c83648dc65518ec1) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 19 +- documentation/ref-manual/closer-look.xml | 2 +- documentation/ref-manual/migration.xml | 538 +++++++++++++++++++-- documentation/ref-manual/ref-classes.xml | 12 + documentation/ref-manual/ref-features.xml | 4 + documentation/ref-manual/ref-qa-checks.xml | 39 -- documentation/ref-manual/ref-variables.xml | 19 +- documentation/ref-manual/usingpoky.xml | 14 - 8 files changed, 538 insertions(+), 109 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index e0726df77a..ef1c166265 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -5108,7 +5108,7 @@ Creating image(s)... Info: The new image(s) can be found here: - /var/tmp/wic/build/mkefidisk-201310230946-sda.direct + current_directory/build/mkefidisk-201310230946-sda.direct The following build artifacts were used to create the image(s): ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/rootfs @@ -5133,7 +5133,8 @@ The output specifies the exact image created as well as - where it was created. + where it was created, which is in the current + directory by default. The output also names the artifacts used and the exact .wks script that was used to generate the image. @@ -5152,11 +5153,11 @@ bmaptool or dd: - $ oe-run-native bmaptool copy /var/tmp/wic/build/mkefidisk-201310230946-sda.direct /dev/sdX + $ oe-run-native bmaptool copy build/mkefidisk-201310230946-sda.direct /dev/sdX or - $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdX + $ sudo dd if=build/mkefidisk-201310230946-sda.direct of=/dev/sdX For more information on how to use the @@ -5240,7 +5241,7 @@ Creating image(s)... Info: The new image(s) can be found here: - /var/tmp/wic/build/directdisksdb-201310231131-sdb.direct + current_directory/build/directdisksdb-201310231131-sdb.direct The following build artifacts were used to create the image(s): @@ -5257,7 +5258,7 @@ whatever media for which you built your image, and boot the resulting media: - $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb + $ sudo dd if=build/directdisksdb-201310231131-sdb.direct of=/dev/sdb 86018+0 records in 86018+0 records out 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s @@ -5284,7 +5285,7 @@ Creating image(s)... Info: The new image(s) can be found here: - /var/tmp/wic/build/directdisk-201309252350-sda.direct + current_directory/build/directdisk-201309252350-sda.direct The following build artifacts were used to create the image(s): @@ -5307,8 +5308,8 @@ (runs in Raw Mode) and uses a modified kickstart file. The example also uses the -o option to cause Wic to create the output - somewhere other than the default - /var/tmp/wic directory: + somewhere other than the default output directory, + which is the current directory: $ wic create ~/test.wks -o /home/trz/testwic --rootfs-dir \ /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \ diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml index a6f1b23257..bf48d4197c 100644 --- a/documentation/ref-manual/closer-look.xml +++ b/documentation/ref-manual/closer-look.xml @@ -1411,7 +1411,7 @@ system has a list of tasks that it believes it can "accelerate" and therefore does not need to run. There is a final function call to the function specified by the - BB_SETSCENE_VERIFY_FUNCTION2 + BB_SETSCENE_VERIFY_FUNCTION2 variable that is able to require the tasks to be run that that the OpenEmbedded build system initially was going to skip. diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml index ddd6644240..f46d230577 100644 --- a/documentation/ref-manual/migration.xml +++ b/documentation/ref-manual/migration.xml @@ -3689,7 +3689,7 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. by BB_SETSCENE_VERIFY_FUNCTION needed to change signature. Consequently, a new variable named - BB_SETSCENE_VERIFY_FUNCTION2 + BB_SETSCENE_VERIFY_FUNCTION2 has been added allowing multiple versions of BitBake to work with suitably written metadata, which includes OpenEmbedded-Core and Poky. @@ -3974,20 +3974,100 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. written custom recipes are missing declared dependencies, particularly those dependencies that are incidentally built earlier in a typical build process and thus are already likely - to be present in the shared sysroot in a previous release. + to be present in the shared sysroot in previous releases. - Because of this new feature, you must explicitly declare all - build-time dependencies for your recipe. - If you do not declare these dependencies, they are not - populated into the sysroot for the recipe. - + Consider the following: + + + Declare Build-Time Dependencies: + Because of this new feature, you must explicitly + declare all build-time dependencies for your recipe. + If you do not declare these dependencies, they are not + populated into the sysroot for the recipe. + + + Specify Pre-Installation and Post-Installtion + Native Tool Dependencies: + You must specifically specify any special native tool + dependencies of pkg_preinst and + pkg_postinst scripts by using the + PACKAGE_WRITE_DEPS + variable. + Specifying these dependencies ensures that these tools + are available if these scripts need to be run on the + build host during the + do_rootfs + task. + + As an example, see the dbus + recipe. + You will see that this recipe has a + pkg_postinst that calls + systemctl if "systemd" is in + DISTRO_FEATURES. + In the example, + systemd-systemctl-native is added to + PACKAGE_WRITE_DEPS, which is also + conditional on "systemd" being in + DISTRO_FEATURES. + + + Examine Recipes that Use + SSTATEPOSTINSTFUNCS: + You need to examine any recipe that uses + SSTATEPOSTINSTFUNCS and determine + steps to take. + + Functions added to + SSTATEPOSTINSTFUNCS are still + called as they were in previous Yocto Project releases. + However, since a separate sysroot is now being populated + for every recipe and if existing functions being called + through SSTATEPOSTINSTFUNCS are + doing relocation, then you will need to change these + to use a post-installation script that is installed by a + function added to + SYSROOT_PREPROCESS_FUNCS. + - - You can find information on how this works in the - staging - class. + For an example, see the + pixbufcache class in + meta/classes/ in the Yocto Project + Source Repositories. + + The SSTATEPOSTINSTFUNCS variable + itself is now deprecated in favor of the + do_populate_sysroot[postfuncs] + task. + Consequently, if you do still have any function or + functions that need to be called after the sysroot + component is created for a recipe, then you would be + well advised to take steps to use a post installation + script as described previously. + Taking these steps prepares your code for when + SSTATEPOSTINSTFUNCS is + removed in a future Yocto Project release. + + + + Specify Which + STAGING_DIR_NATIVE is Used: + Because the shared sysroot is now gone, the scripts + oe-find-native-sysroot and + oe-run-native have been changed such + that you need to specify which recipe's + STAGING_DIR_NATIVE + is used. + + + + You can find more information on how recipe-specific sysroots + work in the + "staging.bbclass" + section. + @@ -3997,16 +4077,21 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. Within the environment used to run build tasks, the environment variable PATH is now sanitized such that - symbolic links linking only the binaries from the host mentioned - in the + the normal native binary paths + (/bin, /sbin, + /usr/bin and so forth) are + removed and a directory containing symbolic links linking only + to the binaries from the host mentioned in the HOSTTOOLS and HOSTTOOLS_NONFATAL - variables into - their own directory are added to PATH. - Consequently, any native binaries that you need to call should - either be in one of these two variables at the configuration - level. + variables is added to PATH. + + + + Consequently, any native binaries provided by the host that you + need to call needs to be in one of these two variables at + the configuration level. @@ -4024,6 +4109,60 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. +
+ Changes to Scripts + + + The following changes to scripts took place: + + + oe-find-native-sysroot: + The usage for the + oe-find-native-sysroot script has + changed to the following: + + $ . oe-find-native-sysroot recipe + + You must now supply a recipe for + recipe as part of the command. + Prior to the Yocto Project &DISTRO; release, it was not + necessary to provide the script with the command. + + + oe-run-native: + The usage for the + oe-run-native script has changed + to the following: + + $ oe-run-native native_recipe tool + + You must supply the name of the native recipe and the tool + you want to run as part of the command. + Prior to the Yocto Project &DISTRO; release, it was not + necessary to provide the native recipe with the command. + + + cleanup-workdir: + The cleanup-workdir script has been + removed because the script was found to be deleting + files it should not have, which lead to broken build + trees. + Rather than trying to delete portions of + TMPDIR + and getting it wrong, it is recommended that you + delete TMPDIR and have it restored + from shared state (sstate) on subsequent builds. + + + wipe-sysroot: + The wipe-sysroot script has been + removed as it is no longer needed with recipe-specific + sysroots. + + + +
+
Changes to Functions @@ -4055,7 +4194,7 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. provides a graphical way of exploring the task-depends.dot file. The data presented by Task Explorer is much more - accurate than the data that is presented by + accurate than the data that was presented by depexp. Being able to visualize the data is an often requested feature as standard *.dot file @@ -4063,7 +4202,7 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. the task-depends.dot file. - Dependency Tree Information Removals: + BitBake "-g" Output Changes: The package-depends.dot and pn-depends.dot files as previously generated using the bitbake -g command @@ -4080,6 +4219,48 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. into account task-level dependencies between recipes, which could be misleading. + + Mirror Variable Splitting Changes: + Mirror variables including + MIRRORS, + PREMIRRORS, + and + SSTATE_MIRRORS + can now separate values entirely with spaces. + Consequently, you no longer need "\\n". + BitBake looks for pairs of values, which simplifies usage. + There should be no change required to existing mirror + variable values themselves. + + + The Subversion (SVN) Fetcher Uses an "ssh" Parameter and Not an "rsh" Parameter: + The SVN fetcher now takes an "ssh" parameter instead of an + "rsh" parameter. + This new optional parameter is used when the "protocol" + parameter is set to "svn+ssh". + You can only use the new parameter to specify the + ssh program used by SVN. + The SVN fetcher passes the new parameter through the + SVN_SSH environment variable during + the + do_fetch + task. + + See the + "Subversion (SVN) Fetcher (svn://)" + section in the Yocto Project BitBake User Manual for + additional information. + + + BB_SETSCENE_VERIFY_FUNCTION + and BB_SETSCENE_VERIFY_FUNCTION2 + Removed: + Because the mechanism they were part of is no longer + necessary with recipe-specific sysroots, the + BB_SETSCENE_VERIFY_FUNCTION and + BB_SETSCENE_VERIFY_FUNCTION2 + variables have been removed. +
@@ -4117,8 +4298,8 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. INCOMPATIBLE_LICENSE to exclude GPLv3 or set PREFERRED_VERSION - to select recipes that use GPLv3, then you must add the - meta-gplv2 layer to your configuration. + to substitute a GPLv2 version of a GPLv3 recipe, then you must add + the meta-gplv2 layer to your configuration. You can find meta-gplv2 layer in the OpenEmbedded layer index at @@ -4127,7 +4308,7 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. - These relocated GPLv3 recipes do not receive the same level of + These relocated GPLv2 recipes do not receive the same level of maintenance as other core recipes. The recipes do not get security fixes and upstream no longer maintains them. @@ -4153,11 +4334,11 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. The following package management changes took place: - Smart package manager is replaced by Dnf package manager. + Smart package manager is replaced by DNF package manager. Smart has become unmaintained upstream, is not ported to Python 3.x. Consequently, Smart needed to be replaced. - Dnf is the only feasible candidate. + DNF is the only feasible candidate. The change in functionality is that the on-target runtime package management from remote package feeds is now done with a different tool that has a @@ -4165,14 +4346,14 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. If you have scripts that call the tool directly, or use its API, they need to be fixed. For more information, see the - Dnf Documentation. + DNF Documentation. Rpm 5.x is replaced with Rpm 4.x. This is done for two major reasons: - Dnf is API-incompatible with Rpm 5.x and porting + DNF is API-incompatible with Rpm 5.x and porting it and maintaining the port is non-trivial. @@ -4193,8 +4374,6 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. As a result, most mainstream open source projects that require DB are still developed and tested with DB 5.x. - By extension,all the open source projects are still - developed and tested with DB 5.x In OE-core, the only thing that was requiring @@ -4220,7 +4399,7 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. Architecture-independent RPM packages are "noarch" instead of "all". This change was made because too many places in - dnf/rpm4 stack already make that assumption. + DNF/RPM4 stack already make that assumption. Only the filenames and the architecture tag has changed. Nothing else has changed in OE-core system, particularly in the @@ -4233,16 +4412,307 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. is not currently supported. This issue will be fully addressed in a future Yocto Project release. + See defect 11209 + for more information on a solution to package feed + signing with RPM in the Yocto Project 2.3 release. + + + OPKG now uses the libsolv backend for resolving package + dependencies by default. + This is vastly superior to OPKG's internal ad-hoc solver + that was previously used. + This change does have a small impact on disk (around + 500 KB) and memory footprint. - See the defect - 11209 - for more information on a solution to package feed - signing with RPM in the Yocto Project 2.3 release. + For further details on this change, see the + commit message. + +
+ Removed Recipes + + + The following recipes have been removed: + + + linux-yocto 4.8: + Version 4.8 has been removed. + Versions 4.1 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10 + are now present. + + + python-smartpm: + Functionally replaced by dnf. + + + createrepo: + Replaced by the createrepo-c recipe. + + + rpmresolve: + No longer needed with the move to RPM 4 as RPM itself is + used instead. + + + gstreamer: + Removed the GStreamer Git version recipes as they have + been stale. + 1.10.x + recipes are still present. + + + alsa-conf-base: + Merged into alsa-conf since + libasound depended on both. + Essentially, no way existed to install only one of these. + + + tremor: + Moved to meta-multimedia. + Fixed-integer Vorbis decoding is not + needed by current hardware. + Thus, GStreamer's ivorbis plugin has been disabled + by default eliminating the need for the + tremor recipe in OE-Core. + + + gummiboot: + Replaced by systemd-boot. + + + +
+ +
+ Wic Changes + + + The following changes have been made to Wic: + + For more information on Wic, see the + "Creating Partitioned Images" + section in the Yocto Project Development Manual. + + + + Default Output Directory Changed: + Wic's default output directory is now the current directory + by default instead of the unusual + /var/tmp/wic. + + The "-o" and "--outdir" options remain unchanged + and are used to specify your preferred output directory + if you do not want to use the default directory. + + + fsimage Plug-in Removed: + The Wic fsimage plug-in has been removed as it duplicates + functionality of the rawcopy plug-in. + + + +
+ +
+ QA Changes + + + The following QA checks have changed: + + + unsafe-references-in-binaries: + The unsafe-references-in-binaries + QA check, which was disabled by default, has now been + removed. + This check was intended to detect binaries in + /bin that link to libraries in + /usr/lib and have the case where + the user has /usr on a separate + filesystem to /. + + The removed QA check was buggy. + Additionally, /usr residing on a + separate partition from / is now + a rare configuration. + Consequently, + unsafe-references-in-binaries was + removed. + + + file-rdeps: + The file-rdeps QA check is now an + error by default instead of a warning. + Because it is an error instead of a warning, you need to + address missing runtime dependencies. + + For additional information, see the + insane + class and the + "Errors and Warnings" + section. + + + +
+ +
+ Miscellaneous Changes + + + The following miscellaneous changes have occurred: + + + In this release, a number of recipes have been changed to + ignore the largefile + DISTRO_FEATURES + item, enabling large file support unconditionally. + This feature has always been enabled by default. + Disabling the feature has not been widely tested. + + Future releases of the Yocto Project will remove + entirely the ability to disable the + largefile feature, + which would make it unconditionally enabled everywhere. + + + + If the + DISTRO_VERSION + value contains the value of the + DATE + variable, which is the default between Poky releases, + the DATE value is explicitly excluded + from /etc/issue and + /etc/issue.net, which is displayed at + the login prompt, in order to avoid conflicts with + Multilib enabled. + Regardless, the DATE value is + inaccurate if the base-files + recipe is restored from shared state (sstate) rather + than rebuilt. + + If you need the build date recorded in + /etc/issue* or anywhere else in your + image, a better method is to define a post-processing + function to do it and have the function called from + ROOTFS_POSTPROCESS_COMMAND. + Doing so ensures the value is always up-to-date with the + created image. + + + Dropbear's init script now disables + DSA host keys by default. + This change is in line with the systemd service + file, which supports RSA keys only, and with recent + versions of OpenSSH, which deprecates DSA host keys. + + + The + buildhistory + class now correctly uses tabs as separators between all + columns in installed-package-sizes.txt + in order to aid import into other tools. + + + The USE_LDCONFIG variable has been + replaced with the "ldconfig" + DISTRO_FEATURES + feature. + Distributions that previously set: + + USE_LDCONFIG = "0" + + should now instead use the following: + + DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig" + + + + The default value of + COPYLEFT_LICENSE_INCLUDE + now includes all versions of AGPL licenses in addition + to GPL and LGPL. + + The default list is not intended to be guaranteed + as a complete safe list. + You should seek legal advice based on what you are + distributing if you are unsure. + + + + Kernel module packages are now suffixed with the kernel + version in order to allow module packages from multiple + kernel versions to co-exist on a target system. + If you wish to return to the previous naming scheme + that does not include the version suffix, use the + following: + + KERNEL_MODULE_PACKAGE_SUFFIX to "" + + + + Removal of libtool + *.la files is now enabled by default. + The *.la files are not actually + needed on Linux and relocating them is an unnecessary + burden. + + If you need to preserve these + .la files (e.g. in a custom + distribution), you must change + INHERIT_DISTRO + such that "remove-libtool" is not included in the value. + + + Extensible SDKs built for GCC 5+ now refuse to install on a + distribution where the host GCC version is 4.8 or 4.9. + This change resulted from the fact that the installation + is known to fail due to the way the + uninative shared state (sstate) + package is built. + See the + uninative + class for additional information. + + + All native and nativesdk recipes now use a separate + DISTRO_FEATURES + value instead of sharing the value used by recipes for the + target, in order to avoid unnecessary rebuilds. + + The DISTRO_FEATURES for + native recipes is + DISTRO_FEATURES_NATIVE added to an + intersection of DISTRO_FEATURES and + DISTRO_FEATURES_FILTER_NATIVE. + + For nativesdk recipes, the + corresponding variables are + DISTRO_FEATURES_NATIVESDK and + DISTRO_FEATURES_FILTER_NATIVESDK. + + + The FILESDIR + variable, which was previously deprecated and rarely used, + has now been removed. + You should change any recipes that set + FILESDIR to set + FILESPATH + instead. + + + The MULTIMACH_HOST_SYS + variable has been removed as it is no longer needed + with recipe-specific sysroots. + + + +
unsafe-references-in-scripts: Reports when a script file installed in ${base_libdir}, @@ -3671,6 +3675,14 @@ For an example, see the meta/conf/distro/include/yocto-uninative.inc. + + + The uninative class is also used unconditionally + by the extensible SDK. + When building the extensible SDK, + uninative-tarball is built and the resulting + tarball is included within the SDK. +
diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml index a4516a2665..7e1c5ef2f1 100644 --- a/documentation/ref-manual/ref-features.xml +++ b/documentation/ref-manual/ref-features.xml @@ -195,6 +195,10 @@ keyboard: Include keyboard support (e.g. keymaps will be loaded during boot). + ldconfig: + Include support for ldconfig and + ld.so.conf on the target. + nfs: Include NFS client support (for mounting NFS exports on device). diff --git a/documentation/ref-manual/ref-qa-checks.xml b/documentation/ref-manual/ref-qa-checks.xml index 86456bd429..515106ae68 100644 --- a/documentation/ref-manual/ref-qa-checks.xml +++ b/documentation/ref-manual/ref-qa-checks.xml @@ -1170,45 +1170,6 @@ can be found then it should be implemented. I can't find one at the moment. - -
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index 3258402288..bf34dadcd1 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml @@ -2421,12 +2421,11 @@ - The default value, which is "GPL* LGPL*", for - COPYLEFT_LICENSE_INCLUDE is set - by the + The default value is set by the copyleft_filter class, which is inherited by the archiver class. + The default value includes "GPL*", "LGPL*", and "AGPL*". @@ -8406,13 +8405,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" + + MULTIMACH_TARGET_SYS @@ -8459,9 +8462,6 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" See the STAMP variable for an example. - MULTIMACH_HOST_SYS - is the corresponding variable for the host system in - situations that involve a "HOST" and a "TARGET" system. See the STAGING_DIR_TARGET variable for more information. @@ -13065,12 +13065,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" they make use of host headers and libraries. - - For native SDK - recipes that build for the SDK - (nativesdk), the value is - "${STAGING_DIR}/${MULTIMACH_HOST_SYS}". - + diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml index 9bd435b008..325dbd9593 100644 --- a/documentation/ref-manual/usingpoky.xml +++ b/documentation/ref-manual/usingpoky.xml @@ -791,20 +791,6 @@ which is usually ${BUILDDIR}/tmp, as it includes the staging sysroots. - Another, faster method to empty the staging sysroots is to use the - scripts/wipe-sysroot script, - which removes just the staging sysroots and keeps everything else - in TMPDIR. - - The scripts/ directory appears in - PATH after running the build environment - initialization script (i.e. - oe-init-build-env - or - oe-init-build-env-memres), - which results in the ability to to run - wipe-sysroot immediately. -
-- cgit v1.2.3-54-g00ecf