mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-04-14 17:02:22 +02:00
Code Issues Packages Projects Releases Wiki Activity

dev-manual, ref-manual: Moved Wic Plug-In section to dev-manual

Browse Source 
Fixes [YOCTO #12370]

I had a section on Wick Plug-Ins in the ref-manual in the
"technical details" chapter.  This section has been combined with the
section on using Wic that lives in the dev-manual.  This move creates
a single section on using Wic to create Wic-partitioned images.

The section was moved out of the ref-manual and merged into the
dev-manual Wic section.

(From yocto-docs rev: 8724049141c9a793312dcf5ff5c3425948d1cbd0)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2018-01-10 11:36:56 -08:00
committed by Richard Purdie
parent e2060287db
commit 8097a978ce
3 changed files with 212 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -4878,16 +4878,17 @@
customized images, and as such, was designed to be
completely extensible through a plug-in interface.
See the
"<ulink url='&YOCTO_DOCS_REF_URL;#wic-plug-ins-interface'>Wic Plug-Ins Interface</ulink>"
section in the Yocto Project Reference Manual for information
on these plug-ins.
"<link linkend='wic-using-the-wic-plug-ins-interface'>Using the Wic Plug-Ins Interface</link>"
section for information on these plug-ins.
</para>
<para>
This section provides some background information on Wic,
describes what you need to have in
place to run the tool, provides instruction on how to use
the Wic utility, and provides several examples.
the Wic utility, provides information on using the Wic plug-ins
interface, and provides several examples that show how to use
Wic.
</para>
<section id='wic-background'>
@@ -5265,6 +5266,210 @@
</para>
</section>
<section id='wic-using-the-wic-plug-ins-interface'>
<title>Using the Wic Plug-Ins Interface</title>
<para>
You can extend and specialize Wic functionality by using
Wic plug-ins.
This section explains the Wic plug-in interface.
<note>
Wic plug-ins consist of "source" and "imager" plug-ins.
Imager plug-ins are beyond the scope of this section.
</note>
</para>
<para>
Source plug-ins provide a mechanism to customize partition
content during the Wic image generation process.
You can use source plug-ins to map values that you specify
using <filename>--source</filename> commands in kickstart
files (i.e. <filename>*.wks</filename>) to a plug-in
implementation used to populate a given partition.
<note>
If you use plug-ins that have build-time dependencies
(e.g. native tools, bootloaders, and so forth)
when building a Wic image, you need to specify those
dependencies using the
<ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE_DEPENDS'><filename>WKS_FILE_DEPENDS</filename></ulink>
variable.
</note>
</para>
<para>
Source plug-ins are subclasses defined in plug-in files.
As shipped, the Yocto Project provides several plug-in
files.
You can see the source plug-in files that ship with the
Yocto Project
<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/scripts/lib/wic/plugins/source'>here</ulink>.
Each of these plug-in files contains source plug-ins that
are designed to populate a specific Wic image partition.
</para>
<para>
Source plug-ins are subclasses of the
<filename>SourcePlugin</filename> class, which is
defined in the
<filename>poky/scripts/lib/wic/pluginbase.py</filename>
file.
For example, the <filename>BootimgEFIPlugin</filename>
source plug-in found in the
<filename>bootimg-efi.py</filename> file is a subclass of
the <filename>SourcePlugin</filename> class, which is found
in the <filename>pluginbase.py</filename> file.
</para>
<para>
You can also implement source plug-ins in a layer outside
of the Source Repositories (external layer).
To do so, be sure that your plug-in files are located in
a directory whose path is
<filename>scripts/lib/wic/plugins/source/</filename>
within your external layer.
When the plug-in files are located there, the source
plug-ins they contain are made available to Wic.
</para>
<para>
When the Wic implementation needs to invoke a
partition-specific implementation, it looks for the plug-in
with the same name as the <filename>--source</filename>
parameter used in the kickstart file given to that
partition.
For example, if the partition is set up using the following
command in a kickstart file:
<literallayout class='monospaced'>
part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
</literallayout>
The methods defined as class members of the matching
source plug-in (i.e. <filename>bootimg-pcbios</filename>)
in the <filename>bootimg-pcbios.py</filename> plug-in file
are used.
</para>
<para>
To be more concrete, here is the corresponding plug-in
definition from the <filename>bootimg-pcbios.py</filename>
file for the previous command along with an example
method called by the Wic implementation when it needs to
prepare a partition using an implementation-specific
function:
<literallayout class='monospaced'>
bootimg-pcbios.py
.
.
.
class BootimgPcbiosPlugin(SourcePlugin):
"""
Create MBR boot partition and install syslinux on it.
"""
name = 'bootimg-pcbios'
.
.
.
@classmethod
def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
oe_builddir, bootimg_dir, kernel_dir,
rootfs_dir, native_sysroot):
"""
Called to do the actual content population for a partition i.e. it
'prepares' the partition to be incorporated into the image.
In this case, prepare content for legacy bios boot partition.
"""
.
.
.
</literallayout>
If a subclass (plug-in) itself does not implement a
particular function, Wic locates and uses the default
version in the superclass.
It is for this reason that all source plug-ins are derived
from the <filename>SourcePlugin</filename> class.
</para>
<para>
The <filename>SourcePlugin</filename> class defined in
the <filename>pluginbase.py</filename> file defines
a set of methods that source plug-ins can implement or
override.
Any plug-ins (subclass of
<filename>SourcePlugin</filename>) that do not implement
a particular method inherit the implementation of the
method from the <filename>SourcePlugin</filename> class.
For more information, see the
<filename>SourcePlugin</filename> class in the
<filename>pluginbase.py</filename> file for details:
</para>
<para>
The following list describes the methods implemented in the
<filename>SourcePlugin</filename> class:
<itemizedlist>
<listitem><para>
<emphasis><filename>do_prepare_partition()</filename>:</emphasis>
Called to populate a partition with actual content.
In other words, the method prepares the final
partition image that is incorporated into the
disk image.
</para></listitem>
<listitem><para>
<emphasis><filename>do_configure_partition()</filename>:</emphasis>
Called before
<filename>do_prepare_partition()</filename> to
create custom configuration files for a partition
(e.g. syslinux or grub configuration files).
</para></listitem>
<listitem><para>
<emphasis><filename>do_install_disk()</filename>:</emphasis>
Called after all partitions have been prepared and
assembled into a disk image.
This method provides a hook to allow finalization
of a disk image (e.g. writing an MBR).
</para></listitem>
<listitem><para>
<emphasis><filename>do_stage_partition()</filename>:</emphasis>
Special content-staging hook called before
<filename>do_prepare_partition()</filename>.
This method is normally empty.</para>
<para>Typically, a partition just uses the passed-in
parameters (e.g. the unmodified value of
<filename>bootimg_dir</filename>).
However, in some cases, things might need to be
more tailored.
As an example, certain files might additionally
need to be taken from
<filename>bootimg_dir + /boot</filename>.
This hook allows those files to be staged in a
customized fashion.
<note>
<filename>get_bitbake_var()</filename>
allows you to access non-standard variables
that you might want to use for this
behavior.
</note>
</para></listitem>
</itemizedlist>
</para>
<para>
You can extend the source plug-in mechanism.
To add more hooks, create more source plug-in methods
within <filename>SourcePlugin</filename> and the
corresponding derived subclasses.
The code that calls the plug-in methods uses the
<filename>plugin.get_source_plugin_methods()</filename>
function to find the method or methods needed by the call.
Retrieval of those methods is accomplished by filling up
a dict with keys that contain the method names of interest.
On success, these will be filled in with the actual
methods.
See the Wic implementation for examples and details.
</para>
</section>
<section id='wic-usage-examples'>
<title>Examples</title>

5
documentation/ref-manual/ref-kickstart.xml
View File

@@ -107,8 +107,9 @@
The most common value for this option is "rootfs", but you
can use any value that maps to a valid source plug-in.
For information on the source plug-ins, see the
"<link linkend='wic-plug-ins-interface'>Wic Plug-Ins Interface</link>"
section.</para>
"<ulink url='&YOCTO_DOCS_DEV_URL;#wic-using-the-wic-plug-ins-interface'>Using the Wic Plug-Ins Interface</ulink>"
section in the Yocto Project Development Tasks Manual.
</para>
<para>If you use <filename>--source rootfs</filename>, Wic
creates a partition as large as needed and to fill it with

207
documentation/ref-manual/technical-details.xml
View File

@@ -1255,213 +1255,6 @@
</para>
</section>
<section id='wic-plug-ins-interface'>
<title>Wic Plug-Ins Interface</title>
<para>
You can extend and specialize Wic functionality by using
Wic plug-ins.
This section explains the Wic plug-in interface.
For information on using Wic in general, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
section in the Yocto Project Development Tasks Manual.
<note>
Wic plug-ins consist of "source" and "imager" plug-ins.
Imager plug-ins are beyond the scope of this section.
</note>
</para>
<para>
Source plug-ins provide a mechanism to customize partition
content during the Wic image generation process.
You can use source plug-ins to map values that you specify
using <filename>--source</filename> commands in kickstart
files (i.e. <filename>*.wks</filename>) to a plug-in
implementation used to populate a given partition.
<note>
If you use plug-ins that have build-time dependencies
(e.g. native tools, bootloaders, and so forth)
when building a Wic image, you need to specify those
dependencies using the
<link linkend='var-WKS_FILE_DEPENDS'><filename>WKS_FILE_DEPENDS</filename></link>
variable.
</note>
</para>
<para>
Source plug-ins are subclasses defined in plug-in files.
As shipped, the Yocto Project provides several plug-in
files.
You can see the source plug-in files that ship with the
Yocto Project
<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/scripts/lib/wic/plugins/source'>here</ulink>.
Each of these plug-in files contain source plug-ins that
are designed to populate a specific Wic image partition.
</para>
<para>
Source plug-ins are subclasses of the
<filename>SourcePlugin</filename> class, which is
defined in the
<filename>poky/scripts/lib/wic/pluginbase.py</filename>
file.
For example, the <filename>BootimgEFIPlugin</filename>
source plug-in found in the
<filename>bootimg-efi.py</filename> file is a subclass of
the <filename>SourcePlugin</filename> class, which is found
in the <filename>pluginbase.py</filename> file.
</para>
<para>
You can also implement source plug-ins in a layer outside
of the Source Repositories (external layer).
To do so, be sure that your plug-in files are located in
a directory whose path is
<filename>scripts/lib/wic/plugins/source/</filename>
within your external layer.
When the plug-in files are located there, the source
plug-ins they contain are made available to Wic.
</para>
<para>
When the Wic implementation needs to invoke a
partition-specific implementation, it looks for the plug-in
with the same name as the <filename>--source</filename>
parameter used in the kickstart file given to that
partition.
For example, if the partition is set up using the following
command in a kickstart file:
<literallayout class='monospaced'>
part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
</literallayout>
The methods defined as class members of the matching
source plug-in (i.e. <filename>bootimg-pcbios</filename>)
in the <filename>bootimg-pcbios.py</filename> plug-in file
are used.
</para>
<para>
To be more concrete, here is the corresponding plug-in
definition from the <filename>bootimg-pcbios.py</filename>
file for the previous command along with an example
method called by the Wic implementation when it needs to
prepare a partition using an implementation-specific
function:
<literallayout class='monospaced'>
bootimg-pcbios.py
.
.
.
class BootimgPcbiosPlugin(SourcePlugin):
"""
Create MBR boot partition and install syslinux on it.
"""
name = 'bootimg-pcbios'
.
.
.
@classmethod
def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
oe_builddir, bootimg_dir, kernel_dir,
rootfs_dir, native_sysroot):
"""
Called to do the actual content population for a partition i.e. it
'prepares' the partition to be incorporated into the image.
In this case, prepare content for legacy bios boot partition.
"""
.
.
.
</literallayout>
If a subclass (plug-in) itself does not implement a
particular function, Wic locates and uses the default
version in the superclass.
It is for this reason that all source plug-ins are derived
from the <filename>SourcePlugin</filename> class.
</para>
<para>
The <filename>SourcePlugin</filename> class defined in
the <filename>pluginbase.py</filename> file defines
a set of methods that source plug-ins can implement or
override.
Any plug-ins (subclass of
<filename>SourcePlugin</filename>) that do not implement
a particular method inherit the implementation of the
method from the <filename>SourcePlugin</filename> class.
For more information, see the
<filename>SourcePlugin</filename> class in the
<filename>pluginbase.py</filename> file for details:
</para>
<para>
The following list describes the methods implemented in the
<filename>SourcePlugin</filename> class:
<itemizedlist>
<listitem><para>
<emphasis><filename>do_prepare_partition()</filename>:</emphasis>
Called to populate a partition with actual content.
In other words, the method prepares the final
partition image that is incorporated into the
disk image.
</para></listitem>
<listitem><para>
<emphasis><filename>do_configure_partition()</filename>:</emphasis>
Called before
<filename>do_prepare_partition()</filename> to
create custom configuration files for a partition
(e.g. syslinux or grub configuration files).
</para></listitem>
<listitem><para>
<emphasis><filename>do_install_disk()</filename>:</emphasis>
Called after all partitions have been prepared and
assembled into a disk image.
This method provides a hook to allow finalization
of a disk image (e.g. writing an MBR).
</para></listitem>
<listitem><para>
<emphasis><filename>do_stage_partition()</filename>:</emphasis>
Special content-staging hook called before
<filename>do_prepare_partition()</filename>.
This method is normally empty.</para>
<para>Typically, a partition just uses the passed-in
parameters (e.g. the unmodified value of
<filename>bootimg_dir</filename>).
However, in some cases, things might need to be
more tailored.
As an example, certain files might additionally
need to be taken from
<filename>bootimg_dir + /boot</filename>.
This hook allows those files to be staged in a
customized fashion.
<note>
<filename>get_bitbake_var()</filename>
allows you to access non-standard variables
that you might want to use for this
behavior.
</note>
</para></listitem>
</itemizedlist>
</para>
<para>
You can extend the source plug-in mechanism.
To add more hooks, create more source plug-in methods
within <filename>SourcePlugin</filename> and the
corresponding derived subclasses.
The code that calls the plug-in methods uses the
<filename>plugin.get_source_plugin_methods()</filename>
function to find the method or methods needed by the call.
Retrieval of those methods is accomplished by filling up
a dict with keys that contain the method names of interest.
On success, these will be filled in with the actual
methods.
See the Wic implementation for examples and details.
</para>
</section>
<section id="wayland">
<title>Wayland</title>