From 482c6a71208410ab12fc528694d57248b972adfc Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 5 Apr 2013 11:14:12 -0700 Subject: [PATCH] dev-manual, ref-manual: Applied review comments for read-only-rootfs, etc. 1. Applied changes from Paul to the read-only-rootfs section. 2. Applied changes form Paul to the customizing images by using IMAGE_FEATURES and EXTRA_IMAGE_FEATURES variables. This was a simple rewrite of a sentence. 3. Updated the note in both the IMAGE_FEATURES and EXTRA_IMAGE_FEATURES glossary entries to specify inside of an image recipe (more specific). (From yocto-docs rev: 762b9e4d3b45a9602284cf4dd1ac281dcbbed7f5) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 172 +++++++++--------- documentation/ref-manual/ref-variables.xml | 6 +- 2 files changed, 90 insertions(+), 88 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 1b57e60d05..2d13038f41 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -611,11 +611,11 @@ IMAGE_FEATURES and EXTRA_IMAGE_FEATURES variables. - Although both variables function nearly equivalent, best - practices dictate using IMAGE_FEATURES + Although the functions for both variables are nearly equivalent, + best practices dictate using IMAGE_FEATURES from within a recipe and using EXTRA_IMAGE_FEATURES from within - your local.conf, which is found in the + your local.conf file, which is found in the Build Directory. @@ -1026,8 +1026,8 @@ Post-Installation Scripts - To add a post-installation (postinstall) script to a package, - add a pkg_postinst_PACKAGENAME() + To add a post-installation script to a package, add a + pkg_postinst_PACKAGENAME() function to the .bb file and use PACKAGENAME as the name of the package you want to attach to the postinst script. @@ -3461,93 +3461,17 @@ Supporting a read-only root filesystem requires that the system and applications do not try to write to the root filesystem. - If writes are attempted, they need to gracefully fail. + You must configure all parts of the target system to write + elsewhere, or gracefully fail in the event of failing to + write to the root filesystem. -
- Post-Installation Scripts - - - It is very important that you make sure all - Post-Installation (postinstall) scripts - for packages that are installed into the image can be run - at the time when the root filesystem is created during the - build on the host system. - These scripts cannot attempt to run during first-boot on the - target device. - With the read-only root filesystem feature enabled, - the build system checks during root filesystem creation to make - sure all postinstall scripts succeed. - If any of these scripts still need to be run after the root - filesystem is created, the build immediately fails. - These checks during build time ensure that the build fails - rather than the target device fails later during its - initial boot operation. - - - - Most of the common postinstall scripts generated by the build - system for the out-of-the-box Yocto Project are engineered - so that they can run during root filesystem creation - (e.g. postinstall scripts for caching fonts). - However, if you create and add custom scripts, you need - to be sure they can be run during file system creation. - - - - Here are some common problems that prevent postinstall - scripts from running during root filesystem creation: - - Not using - $D - in front of absolute paths. - The build system defines $D, and - it is blank when run on the target device. - This implies two purposes for $D: - ensuring paths are valid in both the host and target - environments, and checking to determine which - environment is being used as a method for taking - appropriate actions. - - Attempting to run processes that are - specific to or dependent on the target - architecture. - You can work around these attempts by using native - tools to accomplish the same processes (tasks), or - by alternatively running the processes under QEMU, - which has the qemu_run_binary - function. - For more information, see the - meta/classes/qemu.bbclass - class in the - Source Directory. - - Using hardware features specific to the machine. - - - -
- -
- Areas With Write Access - - - With the read-only root filesystem feature enabled, any - attempt by the target to write to the root filesystem at - runtime fails. - Consequently, you must make sure that you configure processes - and applications that attempt these types of writes do so - to directories with write access (i.e. - /tmp or /var/run). - -
-
Creating the Root Filesystem To create the read-only root filesystem, simply add the - "read-only-rootfs" feature to your image. + read-only-rootfs feature to your image. Using either of the following statements in your image recipe or from within the local.conf file found in the @@ -3571,6 +3495,84 @@ and EXTRA_IMAGE_FEATURES.
+ +
+ Post-Installation Scripts + + + It is very important that you make sure all + post-Installation (pkg_postinst) scripts + for packages that are installed into the image can be run + at the time when the root filesystem is created during the + build on the host system. + These scripts cannot attempt to run during first-boot on the + target device. + With the read-only-rootfs feature enabled, + the build system checks during root filesystem creation to make + sure all post-installation scripts succeed. + If any of these scripts still need to be run after the root + filesystem is created, the build immediately fails. + These checks during build time ensure that the build fails + rather than the target device fails later during its + initial boot operation. + + + + Most of the common post-installation scripts generated by the + build system for the out-of-the-box Yocto Project are engineered + so that they can run during root filesystem creation + (e.g. post-installation scripts for caching fonts). + However, if you create and add custom scripts, you need + to be sure they can be run during file system creation. + + + + Here are some common problems that prevent + post-installation scripts from running during root filesystem + creation: + + Not using + $D + in front of absolute paths: + The build system defines $D + at root filesystem creation time, and + it is blank when run on the target device. + This implies two purposes for $D: + ensuring paths are valid in both the host and target + environments, and checking to determine which + environment is being used as a method for taking + appropriate actions. + + Attempting to run processes that are + specific to or dependent on the target + architecture: + You can work around these attempts by using native + tools to accomplish the same tasks, or + by alternatively running the processes under QEMU, + which has the qemu_run_binary + function. + For more information, see the + meta/classes/qemu.bbclass + class in the + Source Directory. + + + +
+ +
+ Areas With Write Access + + + With the read-only-rootfs feature enabled, + any attempt by the target to write to the root filesystem at + runtime fails. + Consequently, you must make sure that you configure processes + and applications that attempt these types of writes do so + to directories with write access (e.g. + /tmp or /var/run). + +
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index ccb48e438b..d54b5bcdfc 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml @@ -954,8 +954,8 @@ Core layer for images cannot be removed Although you can use this variable from within a recipe, best practices dictate that you do not. - To enable primary features from within the image, use - the + To enable primary features from within the image + recipe, use the IMAGE_FEATURES variable. @@ -1243,7 +1243,7 @@ Core layer for images cannot be removed Build Directory, best practices dictate that you do not. - To enable extra features from outside the image, + To enable extra features from outside the image recipe, use the EXTRA_IMAGE_FEATURES variable.