mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-06-02 01:19:52 +00:00
Code Issues Projects Releases Wiki Activity

dev-manual: Changes to the read-only root filesystem section.

Browse Source 
Applied the review comments from Paul Eggleton to augment this
section with more information.

Performed a spell check on the entire chapter.

Made the term "postinstall" consistent by defining its first
use in sections a "post-installation (postinstall) script".

(From yocto-docs rev: 179f478777fd02e3fa56d80951ce3eab350fc189)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2013-04-05 06:13:13 -07:00
committed by Richard Purdie
parent 46a05ed934
commit 3ccd6fde21
1 changed files with 118 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/dev-manual/dev-manual-common-tasks.xml
+118 -30
View File
@@ -1022,10 +1022,11 @@
</section> </section>
<section id='usingpoky-extend-addpkg-postinstalls'> <section id='usingpoky-extend-addpkg-postinstalls'>
<title>Post Install Scripts</title> <title>Post-Installation Scripts</title>
<para> <para>
To add a post-installation script to a package, add a <filename>pkg_postinst_PACKAGENAME() To add a post-installation (postinstall) script to a package,
add a <filename>pkg_postinst_PACKAGENAME()
</filename> function to the <filename>.bb</filename> file and use </filename> function to the <filename>.bb</filename> file and use
<filename>PACKAGENAME</filename> as the name of the package you want to attach to the <filename>PACKAGENAME</filename> as the name of the package you want to attach to the
<filename>postinst</filename> script. <filename>postinst</filename> script.
@@ -1488,7 +1489,7 @@
These situations almost always exist when a library API These situations almost always exist when a library API
changes and you have multiple pieces of software that changes and you have multiple pieces of software that
depend on the separate versions of the library. 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. versions of the same library in parallel on the same system.
</para> </para>
@@ -2297,7 +2298,7 @@
your own distribution. your own distribution.
You can use the Yocto Project out-of-the-box to create the You can use the Yocto Project out-of-the-box to create the
<filename>poky-tiny</filename> distribution. <filename>poky-tiny</filename> 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 distribution that are likely modeled after
<filename>poky-tiny</filename>. <filename>poky-tiny</filename>.
<note> <note>
@@ -2870,7 +2871,7 @@
<para> <para>
If you have more than one distribution alias, separate them with a space. If you have more than one distribution alias, separate them with a space.
Note that the build system currently automatically checks the 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 and Mandriva distributions for source package recipes without having to specify them
using the <filename>DISTRO_PN_ALIAS</filename> variable. using the <filename>DISTRO_PN_ALIAS</filename> variable.
For example, the following command generates a report that lists the Linux distributions For example, the following command generates a report that lists the Linux distributions
@@ -3447,8 +3448,8 @@
<title>Creating a Read-Only Root Filesystem</title> <title>Creating a Read-Only Root Filesystem</title>
<para> <para>
Suppose, for security reasons, you need to disable the Suppose, for security reasons, you need to disable
your target device's root filesystem's write permisions your target device's root filesystem's write permissions
(i.e. you need a read-only root filesystem). (i.e. you need a read-only root filesystem).
Or, perhaps you are running the device's operating system Or, perhaps you are running the device's operating system
from a read-only storage device. from a read-only storage device.
@@ -3456,34 +3457,121 @@
that behavior. that behavior.
</para> </para>
<para> <note>
To create a read-only root filesystem, simply add the Supporting a read-only root filesystem requires that the system and
"read-only-rootfs" feature to your image. applications do not try to write to the root filesystem.
Using either of the following statements in your If writes are attempted, they need to gracefully fail.
image recipe or from within the </note>
<filename>local.conf</filename> file found in the Build
Directory causes the build system to create a <section id='post-installation-scripts'>
read-only root filesystem: <title>Post-Installation Scripts</title>
<literallayout class='monospaced'>
<para>
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.
</para>
<para>
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.
</para>
<para>
Here are some common problems that prevent postinstall
scripts from running during root filesystem creation:
<itemizedlist>
<listitem><para>Not using
<filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
in front of absolute paths.
The build system defines <filename>$D</filename>, and
it is blank when run on the target device.
This implies two purposes for <filename>$D</filename>:
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.
</para></listitem>
<listitem><para>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 <filename>qemu_run_binary</filename>
function.
For more information, see the
<filename>meta/classes/qemu.bbclass</filename>
class in the
<link linkend='source-directory'>Source Directory</link>.
</para></listitem>
<listitem><para>Using hardware features specific to the machine.
</para></listitem>
</itemizedlist>
</para>
</section>
<section id='areas-with-write-access'>
<title>Areas With Write Access</title>
<para>
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.
<filename>/tmp</filename> or <filename>/var/run</filename>).
</para>
</section>
<section id='creating-the-root-filesystem'>
<title>Creating the Root Filesystem</title>
<para>
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
<filename>local.conf</filename> file found in the
<link linkend='build-directory'>Build Directory</link>
causes the build system to create a read-only root filesystem:
<literallayout class='monospaced'>
IMAGE_FEATURES = "read-only-rootfs" IMAGE_FEATURES = "read-only-rootfs"
</literallayout> </literallayout>
or or
<literallayout class='monospaced'> <literallayout class='monospaced'>
EXTRA_IMAGE_FEATURES = "read-only-rootfs" EXTRA_IMAGE_FEATURES = "read-only-rootfs"
</literallayout> </literallayout>
</para> </para>
<para> <para>
For more information on how to use these variables, see the For more information on how to use these variables, see the
"<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>" "<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
section. section.
For information on the variables, see For information on the variables, see
<ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>. and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
</para> </para>
</section>
</section> </section>
<section id="platdev-gdb-remotedebug"> <section id="platdev-gdb-remotedebug">
<title>Debugging With the GNU Project Debugger (GDB) Remotely</title> <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>