diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 70ecc2276a..f8b41bf54d 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1022,10 +1022,11 @@
- Post Install Scripts
+ Post-Installation Scripts
- To add a post-installation script to a package, add a pkg_postinst_PACKAGENAME()
+ To add a post-installation (postinstall) 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.
@@ -1488,7 +1489,7 @@
These situations almost always exist when a library API
changes and you have multiple pieces of software that
depend on the separate versions of the library.
- To accomodate these situations, you can install multiple
+ To accommodate these situations, you can install multiple
versions of the same library in parallel on the same system.
@@ -2297,7 +2298,7 @@
your own distribution.
You can use the Yocto Project out-of-the-box to create the
poky-tiny distribution.
- Ulitmately, you will want to make changes in your own
+ Ultimately, you will want to make changes in your own
distribution that are likely modeled after
poky-tiny.
@@ -2870,7 +2871,7 @@
If you have more than one distribution alias, separate them with a space.
Note that the build system currently automatically checks the
- Fedora, OpenSuSE, Debian, Ubuntu,
+ Fedora, OpenSUSE, Debian, Ubuntu,
and Mandriva distributions for source package recipes without having to specify them
using the DISTRO_PN_ALIAS variable.
For example, the following command generates a report that lists the Linux distributions
@@ -3447,8 +3448,8 @@
Creating a Read-Only Root Filesystem
- Suppose, for security reasons, you need to disable the
- your target device's root filesystem's write permisions
+ Suppose, for security reasons, you need to disable
+ your target device's root filesystem's write permissions
(i.e. you need a read-only root filesystem).
Or, perhaps you are running the device's operating system
from a read-only storage device.
@@ -3456,34 +3457,121 @@
that behavior.
-
- To create a read-only root filesystem, simply add the
- "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 Build
- Directory causes the build system to create a
- read-only root filesystem:
-
+
+ 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.
+
+
+
+ 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.
+ Using either of the following statements in your
+ image recipe or from within the
+ local.conf file found in the
+ Build Directory
+ causes the build system to create a read-only root filesystem:
+
IMAGE_FEATURES = "read-only-rootfs"
-
- or
-
+
+ or
+
EXTRA_IMAGE_FEATURES = "read-only-rootfs"
-
-
+
+
-
- For more information on how to use these variables, see the
- "Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES"
- section.
- For information on the variables, see
- IMAGE_FEATURES
- and EXTRA_IMAGE_FEATURES.
-
+
+ For more information on how to use these variables, see the
+ "Customizing Images Using Custom IMAGE_FEATURES and EXTRA_IMAGE_FEATURES"
+ section.
+ For information on the variables, see
+ IMAGE_FEATURES
+ and EXTRA_IMAGE_FEATURES.
+
+
-
Debugging With the GNU Project Debugger (GDB) Remotely