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

ref-manual, dev-manual: Moved plug-in section for wic to ref-manual

Browse Source 
Fixed links affected by the move.

(From yocto-docs rev: 250d312274788b0eebf3ae9143f2f89eafd4ab90)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2017-10-11 13:29:14 -07:00
committed by Richard Purdie
parent 6cee5c8b9b
commit 6077ebbe80
2 changed files with 655 additions and 666 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

File diff suppressed because it is too large Load Diff

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

@@ -1252,6 +1252,213 @@
</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'>Creating Partitioned Images</ulink>"
section in the Yocto Project Development 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='x32'>
<title>x32</title>