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.