sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

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 <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2013-04-05 11:14:12 -07:00 committed by Richard Purdie
parent 4be429fea5
commit 482c6a7120
2 changed files with 90 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

172
documentation/dev-manual/dev-manual-common-tasks.xml
View File

@ -611,11 +611,11 @@
<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>
variables.
Although both variables function nearly equivalent, best
practices dictate using <filename>IMAGE_FEATURES</filename>
Although the functions for both variables are nearly equivalent,
best practices dictate using <filename>IMAGE_FEATURES</filename>
from within a recipe and using
<filename>EXTRA_IMAGE_FEATURES</filename> from within
your <filename>local.conf</filename>, which is found in the
your <filename>local.conf</filename> file, which is found in the
<link linkend='build-directory'>Build Directory</link>.
</para>
@ -1026,8 +1026,8 @@
<title>Post-Installation Scripts</title>
<para>
To add a post-installation (postinstall) script to a package,
add a <filename>pkg_postinst_PACKAGENAME()
To add a post-installation script to a package, add a
<filename>pkg_postinst_PACKAGENAME()
</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>postinst</filename> script.
@ -3461,93 +3461,17 @@
<note>
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.
</note>
<section id='post-installation-scripts'>
<title>Post-Installation Scripts</title>
<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.
<filename>read-only-rootfs</filename> 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
@ -3571,6 +3495,84 @@
and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
</para>
</section>
<section id='post-installation-scripts'>
<title>Post-Installation Scripts</title>
<para>
It is very important that you make sure all
post-Installation (<filename>pkg_postinst</filename>) 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 <filename>read-only-rootfs</filename> 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.
</para>
<para>
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.
</para>
<para>
Here are some common problems that prevent
post-installation scripts from running during root filesystem
creation:
<itemizedlist>
<listitem><para><emphasis>Not using
<filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
in front of absolute paths:</emphasis>
The build system defines <filename>$D</filename>
at root filesystem creation time, 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><emphasis>Attempting to run processes that are
specific to or dependent on the target
architecture:</emphasis>
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 <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>
</itemizedlist>
</para>
</section>
<section id='areas-with-write-access'>
<title>Areas With Write Access</title>
<para>
With the <filename>read-only-rootfs</filename> 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.
<filename>/tmp</filename> or <filename>/var/run</filename>).
</para>
</section>
</section>
<section id="platdev-gdb-remotedebug">

6
documentation/ref-manual/ref-variables.xml
View File

@ -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.
<note>
To enable primary features from within the image, use
the
To enable primary features from within the image
recipe, use the
<link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
variable.
</note>
@ -1243,7 +1243,7 @@ Core layer for images cannot be removed
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
best practices dictate that you do not.
<note>
To enable extra features from outside the image,
To enable extra features from outside the image recipe,
use the
<filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
</note>