mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-05-31 12:49:46 +00:00
Code Issues Projects Releases Wiki Activity

dev-manual: Updated the plug-ins section.

Browse Source 
(From yocto-docs rev: d1a4ff5ee177c7b9442d805b6e20a8ba8410d91d)

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-10 12:24:01 -07:00
committed by Richard Purdie
parent e746cc1c65
commit 7cf82df8b0
1 changed files with 118 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/dev-manual/dev-manual-common-tasks.xml
+118 -80
View File
@@ -5467,22 +5467,22 @@
<title>Plug-ins</title> <title>Plug-ins</title>
<para> <para>
Plug-ins allow Wic functionality to You can extend and specialize Wic functionality by using
be extended and specialized by users. Wic plug-ins.
This section documents the plug-in interface, which is This section explains the Wic plug-in interface.
currently restricted to source plug-ins. <note>
Wic plug-ins consist of "source" and "imager" plug-ins.
Imager plug-ins are beyond the scope of this section.
</note>
</para> </para>
<para> <para>
Source plug-ins provide a mechanism to customize Source plug-ins provide a mechanism to customize partition
various aspects of the image generation process in content during the Wic image generation process.
Wic, mainly the contents of You can use source plug-ins to map values that you specify
partitions. using <filename>--source</filename> commands in kickstart
The plug-ins provide a mechanism for mapping values files (i.e. <filename>*.wks</filename>) to a plug-in
specified in <filename>.wks</filename> files using the implementation used to populate a given partition.
<filename>--source</filename> keyword to a
particular plug-in implementation that populates a
corresponding partition.
<note> <note>
If you use plug-ins that have build-time dependencies If you use plug-ins that have build-time dependencies
(e.g. native tools, bootloaders, and so forth) (e.g. native tools, bootloaders, and so forth)
@@ -5494,80 +5494,119 @@
</para> </para>
<para> <para>
A source plug-in is created as a subclass of Source plug-ins are subclasses defined in plug-in files.
<filename>SourcePlugin</filename>. As shipped, the Yocto Project provides several plug-in
The plug-in file containing it is added to files.
<filename>scripts/lib/wic/plugins/source/</filename> to You can see the source plug-in files that ship with the
make the plug-in implementation available to the Yocto Project
Wic implementation. <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/scripts/lib/wic/plugins/source'>here</ulink>.
For more information, see Each of these plug-in files contain source plug-ins that
<filename>scripts/lib/wic/pluginbase.py</filename>. are designed to populate a specific Wic image partition.
</para> </para>
<para> <para>
Source plug-ins can also be implemented and added by Source plug-ins are subclasses of the
external layers. <filename>SourcePlugin</filename> class, which is
As such, any plug-ins found in a 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> <filename>scripts/lib/wic/plugins/source/</filename>
directory in an external layer are also made within your external layer.
available. When the plug-in files are located there, the source
plug-ins they contain are made available to Wic.
</para> </para>
<para> <para>
When the Wic implementation needs When the Wic implementation needs to invoke a
to invoke a partition-specific implementation, it looks partition-specific implementation, it looks for the plug-in
for the plug-in that has the same name as the with the same name as the <filename>--source</filename>
<filename>--source</filename> parameter given to parameter used in the kickstart file given to that
that partition. partition.
For example, if the partition is set up as follows: For example, if the partition is set up using the following
command in a kickstart file:
<literallayout class='monospaced'> <literallayout class='monospaced'>
part /boot --source bootimg-pcbios ... part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
</literallayout> </literallayout>
The methods defined as class members of the plug-in The methods defined as class members of the matching
having the matching <filename>bootimg-pcbios.name</filename> source plug-in (i.e. <filename>bootimg-pcbios</filename>)
class member are used. in the <filename>bootimg-pcbios.py</filename> plug-in file
are used.
</para> </para>
<para> <para>
To be more concrete, here is the plug-in definition that To be more concrete, here is the corresponding plug-in
matches a definition from the <filename>bootimg-pcbios.py</filename>
<filename>--source bootimg-pcbios</filename> usage, file for the previous command along with an example
along with an example method called by the Wic implementation when it needs to
method called by the Wic implementation prepare a partition using an implementation-specific
when it needs to invoke an implementation-specific function:
partition-preparation function:
<literallayout class='monospaced'> <literallayout class='monospaced'>
class BootimgPcbiosPlugin(SourcePlugin): bootimg-pcbios.py
.
.
.
class BootimgPcbiosPlugin(SourcePlugin):
"""
Create MBR boot partition and install syslinux on it.
"""
name = 'bootimg-pcbios' name = 'bootimg-pcbios'
.
@classmethod .
def do_prepare_partition(self, part, ...) .
@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> </literallayout>
If the subclass itself does not implement a function, a If a subclass (plug-in) itself does not implement a
default version in a superclass is located and particular function, Wic locates and uses the default
used, which is why all plug-ins must be derived from version in the superclass.
<filename>SourcePlugin</filename>. It is for this reason that all source plug-ins are derived
from the <filename>SourcePlugin</filename> class.
</para> </para>
<para> <para>
The <filename>SourcePlugin</filename> class defines the The <filename>SourcePlugin</filename> class defined in
following methods, which is the current set of methods the <filename>pluginbase.py</filename> file defines
that can be implemented or overridden by a set of methods that source plug-ins can implement or
<filename>--source</filename> plug-ins. override.
Any methods not implemented by a Any plug-ins (subclass of
<filename>SourcePlugin</filename> subclass inherit the <filename>SourcePlugin</filename>) that do not implement
implementations present in the a particular method inherit the implementation of the
<filename>SourcePlugin</filename> class. method from the <filename>SourcePlugin</filename> class.
For more information, see the For more information, see the
<filename>SourcePlugin</filename> source for details: <filename>SourcePlugin</filename> class in the
<filename>pluginbase.py</filename> file for details:
</para> </para>
<para> <para>
The following list describes the methods implemented in the
<filename>SourcePlugin</filename> class:
<itemizedlist> <itemizedlist>
<listitem><para> <listitem><para>
<emphasis><filename>do_prepare_partition()</filename>:</emphasis> <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
Called to do the actual content population for a Called to populate a partition with actual content.
partition.
In other words, the method prepares the final In other words, the method prepares the final
partition image that is incorporated into the partition image that is incorporated into the
disk image. disk image.
@@ -5575,27 +5614,27 @@
<listitem><para> <listitem><para>
<emphasis><filename>do_configure_partition()</filename>:</emphasis> <emphasis><filename>do_configure_partition()</filename>:</emphasis>
Called before Called before
<filename>do_prepare_partition()</filename>. <filename>do_prepare_partition()</filename> to
This method is typically used to create custom create custom configuration files for a partition
configuration files for a partition (e.g. syslinux (e.g. syslinux or grub configuration files).
or grub configuration files).
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
<emphasis><filename>do_install_disk()</filename>:</emphasis> <emphasis><filename>do_install_disk()</filename>:</emphasis>
Called after all partitions have been prepared and Called after all partitions have been prepared and
assembled into a disk image. assembled into a disk image.
This method provides a hook to allow finalization This method provides a hook to allow finalization
of a disk image, (e.g. writing an MBR). of a disk image (e.g. writing an MBR).
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
<emphasis><filename>do_stage_partition()</filename>:</emphasis> <emphasis><filename>do_stage_partition()</filename>:</emphasis>
Special content-staging hook called before Special content-staging hook called before
<filename>do_prepare_partition()</filename>. <filename>do_prepare_partition()</filename>.
This method is normally empty.</para> This method is normally empty.</para>
<para>Typically, a partition just uses the passed-in <para>Typically, a partition just uses the passed-in
parameters (e.g. the unmodified value of parameters (e.g. the unmodified value of
<filename>bootimg_dir</filename>). <filename>bootimg_dir</filename>).
However, in some cases things might need to be However, in some cases, things might need to be
more tailored. more tailored.
As an example, certain files might additionally As an example, certain files might additionally
need to be taken from need to be taken from
@@ -5605,27 +5644,26 @@
<note> <note>
<filename>get_bitbake_var()</filename> <filename>get_bitbake_var()</filename>
allows you to access non-standard variables allows you to access non-standard variables
that you might want to use for this. that you might want to use for this
behavior.
</note> </note>
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para> <para>
This scheme is extensible. You can extend the source plug-in mechanism.
Adding more hooks is a simple matter of adding more To add more hooks, create more source plug-in methods
plug-in methods to <filename>SourcePlugin</filename> and within <filename>SourcePlugin</filename> and the
derived classes. corresponding derived subclasses.
The code that then needs to call the plug-in methods uses The code that calls the plug-in methods uses the
<filename>plugin.get_source_plugin_methods()</filename> <filename>plugin.get_source_plugin_methods()</filename>
to find the method or methods needed by the call. function to find the method or methods needed by the call.
Retrieval of those methods is accomplished Retrieval of those methods is accomplished by filling up
by filling up a dict with keys a dict with keys that contain the method names of interest.
containing the method names of interest.
On success, these will be filled in with the actual On success, these will be filled in with the actual
methods. methods.
Please see the Wic See the Wic implementation for examples and details.
implementation for examples and details.
</para> </para>
</section> </section>