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>
|
<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>
|
||||||
variables.
|
variables.
|
||||||
Although both variables function nearly equivalent, best
|
Although the functions for both variables are nearly equivalent,
|
||||||
practices dictate using <filename>IMAGE_FEATURES</filename>
|
best practices dictate using <filename>IMAGE_FEATURES</filename>
|
||||||
from within a recipe and using
|
from within a recipe and using
|
||||||
<filename>EXTRA_IMAGE_FEATURES</filename> from within
|
<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>.
|
<link linkend='build-directory'>Build Directory</link>.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
@ -1026,8 +1026,8 @@
|
||||||
<title>Post-Installation Scripts</title>
|
<title>Post-Installation Scripts</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To add a post-installation (postinstall) script to a package,
|
To add a post-installation script to a package, add a
|
||||||
add a <filename>pkg_postinst_PACKAGENAME()
|
<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.
|
||||||
|
@ -3461,93 +3461,17 @@
|
||||||
<note>
|
<note>
|
||||||
Supporting a read-only root filesystem requires that the system and
|
Supporting a read-only root filesystem requires that the system and
|
||||||
applications do not try to write to the root filesystem.
|
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>
|
</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'>
|
<section id='creating-the-root-filesystem'>
|
||||||
<title>Creating the Root Filesystem</title>
|
<title>Creating the Root Filesystem</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To create the read-only root filesystem, simply add the
|
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
|
Using either of the following statements in your
|
||||||
image recipe or from within the
|
image recipe or from within the
|
||||||
<filename>local.conf</filename> file found in 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>.
|
and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
|
||||||
</para>
|
</para>
|
||||||
</section>
|
</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>
|
||||||
|
|
||||||
<section id="platdev-gdb-remotedebug">
|
<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,
|
Although you can use this variable from within a recipe,
|
||||||
best practices dictate that you do not.
|
best practices dictate that you do not.
|
||||||
<note>
|
<note>
|
||||||
To enable primary features from within the image, use
|
To enable primary features from within the image
|
||||||
the
|
recipe, use the
|
||||||
<link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
|
<link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
|
||||||
variable.
|
variable.
|
||||||
</note>
|
</note>
|
||||||
|
@ -1243,7 +1243,7 @@ Core layer for images cannot be removed
|
||||||
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
|
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
|
||||||
best practices dictate that you do not.
|
best practices dictate that you do not.
|
||||||
<note>
|
<note>
|
||||||
To enable extra features from outside the image,
|
To enable extra features from outside the image recipe,
|
||||||
use the
|
use the
|
||||||
<filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
|
<filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
|
||||||
</note>
|
</note>
|
||||||
|
|
Loading…
Reference in New Issue