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:
parent
4be429fea5
commit
482c6a7120
|
@ -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">
|
||||
|
|
|
@ -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>
|
||||
|
|
Loading…
Reference in New Issue