summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-10-10 12:24:01 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-10-16 23:46:51 +0100
commit7cf82df8b09dbdf999f9b85c33a7f3be10efc5ba (patch)
tree1cc7c4f1c99973213b09eda30f1e36c529d5d799 /documentation/dev-manual
parente746cc1c65bc4c4e3ce06e9a63b6897d82a6bb64 (diff)
downloadpoky-7cf82df8b09dbdf999f9b85c33a7f3be10efc5ba.tar.gz
dev-manual: Updated the plug-ins section.
(From yocto-docs rev: d1a4ff5ee177c7b9442d805b6e20a8ba8410d91d) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml198
1 files changed, 118 insertions, 80 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index c788a8d30a..a5fe63ac9d 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -5467,22 +5467,22 @@
5467 <title>Plug-ins</title> 5467 <title>Plug-ins</title>
5468 5468
5469 <para> 5469 <para>
5470 Plug-ins allow Wic functionality to 5470 You can extend and specialize Wic functionality by using
5471 be extended and specialized by users. 5471 Wic plug-ins.
5472 This section documents the plug-in interface, which is 5472 This section explains the Wic plug-in interface.
5473 currently restricted to source plug-ins. 5473 <note>
5474 Wic plug-ins consist of "source" and "imager" plug-ins.
5475 Imager plug-ins are beyond the scope of this section.
5476 </note>
5474 </para> 5477 </para>
5475 5478
5476 <para> 5479 <para>
5477 Source plug-ins provide a mechanism to customize 5480 Source plug-ins provide a mechanism to customize partition
5478 various aspects of the image generation process in 5481 content during the Wic image generation process.
5479 Wic, mainly the contents of 5482 You can use source plug-ins to map values that you specify
5480 partitions. 5483 using <filename>--source</filename> commands in kickstart
5481 The plug-ins provide a mechanism for mapping values 5484 files (i.e. <filename>*.wks</filename>) to a plug-in
5482 specified in <filename>.wks</filename> files using the 5485 implementation used to populate a given partition.
5483 <filename>--source</filename> keyword to a
5484 particular plug-in implementation that populates a
5485 corresponding partition.
5486 <note> 5486 <note>
5487 If you use plug-ins that have build-time dependencies 5487 If you use plug-ins that have build-time dependencies
5488 (e.g. native tools, bootloaders, and so forth) 5488 (e.g. native tools, bootloaders, and so forth)
@@ -5494,80 +5494,119 @@
5494 </para> 5494 </para>
5495 5495
5496 <para> 5496 <para>
5497 A source plug-in is created as a subclass of 5497 Source plug-ins are subclasses defined in plug-in files.
5498 <filename>SourcePlugin</filename>. 5498 As shipped, the Yocto Project provides several plug-in
5499 The plug-in file containing it is added to 5499 files.
5500 <filename>scripts/lib/wic/plugins/source/</filename> to 5500 You can see the source plug-in files that ship with the
5501 make the plug-in implementation available to the 5501 Yocto Project
5502 Wic implementation. 5502 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/scripts/lib/wic/plugins/source'>here</ulink>.
5503 For more information, see 5503 Each of these plug-in files contain source plug-ins that
5504 <filename>scripts/lib/wic/pluginbase.py</filename>. 5504 are designed to populate a specific Wic image partition.
5505 </para>
5506
5507 <para>
5508 Source plug-ins are subclasses of the
5509 <filename>SourcePlugin</filename> class, which is
5510 defined in the
5511 <filename>poky/scripts/lib/wic/pluginbase.py</filename>
5512 file.
5513 For example, the <filename>BootimgEFIPlugin</filename>
5514 source plug-in found in the
5515 <filename>bootimg-efi.py</filename> file is a subclass of
5516 the <filename>SourcePlugin</filename> class, which is found
5517 in the <filename>pluginbase.py</filename> file.
5505 </para> 5518 </para>
5506 5519
5507 <para> 5520 <para>
5508 Source plug-ins can also be implemented and added by 5521 You can also implement source plug-ins in a layer outside
5509 external layers. 5522 of the Source Repositories (external layer).
5510 As such, any plug-ins found in a 5523 To do so, be sure that your plug-in files are located in
5524 a directory whose path is
5511 <filename>scripts/lib/wic/plugins/source/</filename> 5525 <filename>scripts/lib/wic/plugins/source/</filename>
5512 directory in an external layer are also made 5526 within your external layer.
5513 available. 5527 When the plug-in files are located there, the source
5528 plug-ins they contain are made available to Wic.
5514 </para> 5529 </para>
5515 5530
5516 <para> 5531 <para>
5517 When the Wic implementation needs 5532 When the Wic implementation needs to invoke a
5518 to invoke a partition-specific implementation, it looks 5533 partition-specific implementation, it looks for the plug-in
5519 for the plug-in that has the same name as the 5534 with the same name as the <filename>--source</filename>
5520 <filename>--source</filename> parameter given to 5535 parameter used in the kickstart file given to that
5521 that partition. 5536 partition.
5522 For example, if the partition is set up as follows: 5537 For example, if the partition is set up using the following
5538 command in a kickstart file:
5523 <literallayout class='monospaced'> 5539 <literallayout class='monospaced'>
5524 part /boot --source bootimg-pcbios ... 5540 part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
5525 </literallayout> 5541 </literallayout>
5526 The methods defined as class members of the plug-in 5542 The methods defined as class members of the matching
5527 having the matching <filename>bootimg-pcbios.name</filename> 5543 source plug-in (i.e. <filename>bootimg-pcbios</filename>)
5528 class member are used. 5544 in the <filename>bootimg-pcbios.py</filename> plug-in file
5545 are used.
5529 </para> 5546 </para>
5530 5547
5531 <para> 5548 <para>
5532 To be more concrete, here is the plug-in definition that 5549 To be more concrete, here is the corresponding plug-in
5533 matches a 5550 definition from the <filename>bootimg-pcbios.py</filename>
5534 <filename>--source bootimg-pcbios</filename> usage, 5551 file for the previous command along with an example
5535 along with an example 5552 method called by the Wic implementation when it needs to
5536 method called by the Wic implementation 5553 prepare a partition using an implementation-specific
5537 when it needs to invoke an implementation-specific 5554 function:
5538 partition-preparation function:
5539 <literallayout class='monospaced'> 5555 <literallayout class='monospaced'>
5540 class BootimgPcbiosPlugin(SourcePlugin): 5556 bootimg-pcbios.py
5541 name = 'bootimg-pcbios' 5557 .
5558 .
5559 .
5560 class BootimgPcbiosPlugin(SourcePlugin):
5561 """
5562 Create MBR boot partition and install syslinux on it.
5563 """
5542 5564
5543 @classmethod 5565 name = 'bootimg-pcbios'
5544 def do_prepare_partition(self, part, ...) 5566 .
5567 .
5568 .
5569 @classmethod
5570 def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
5571 oe_builddir, bootimg_dir, kernel_dir,
5572 rootfs_dir, native_sysroot):
5573 """
5574 Called to do the actual content population for a partition i.e. it
5575 'prepares' the partition to be incorporated into the image.
5576 In this case, prepare content for legacy bios boot partition.
5577 """
5578 .
5579 .
5580 .
5545 </literallayout> 5581 </literallayout>
5546 If the subclass itself does not implement a function, a 5582 If a subclass (plug-in) itself does not implement a
5547 default version in a superclass is located and 5583 particular function, Wic locates and uses the default
5548 used, which is why all plug-ins must be derived from 5584 version in the superclass.
5549 <filename>SourcePlugin</filename>. 5585 It is for this reason that all source plug-ins are derived
5586 from the <filename>SourcePlugin</filename> class.
5550 </para> 5587 </para>
5551 5588
5552 <para> 5589 <para>
5553 The <filename>SourcePlugin</filename> class defines the 5590 The <filename>SourcePlugin</filename> class defined in
5554 following methods, which is the current set of methods 5591 the <filename>pluginbase.py</filename> file defines
5555 that can be implemented or overridden by 5592 a set of methods that source plug-ins can implement or
5556 <filename>--source</filename> plug-ins. 5593 override.
5557 Any methods not implemented by a 5594 Any plug-ins (subclass of
5558 <filename>SourcePlugin</filename> subclass inherit the 5595 <filename>SourcePlugin</filename>) that do not implement
5559 implementations present in the 5596 a particular method inherit the implementation of the
5560 <filename>SourcePlugin</filename> class. 5597 method from the <filename>SourcePlugin</filename> class.
5561 For more information, see the 5598 For more information, see the
5562 <filename>SourcePlugin</filename> source for details: 5599 <filename>SourcePlugin</filename> class in the
5600 <filename>pluginbase.py</filename> file for details:
5563 </para> 5601 </para>
5564 5602
5565 <para> 5603 <para>
5604 The following list describes the methods implemented in the
5605 <filename>SourcePlugin</filename> class:
5566 <itemizedlist> 5606 <itemizedlist>
5567 <listitem><para> 5607 <listitem><para>
5568 <emphasis><filename>do_prepare_partition()</filename>:</emphasis> 5608 <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
5569 Called to do the actual content population for a 5609 Called to populate a partition with actual content.
5570 partition.
5571 In other words, the method prepares the final 5610 In other words, the method prepares the final
5572 partition image that is incorporated into the 5611 partition image that is incorporated into the
5573 disk image. 5612 disk image.
@@ -5575,27 +5614,27 @@
5575 <listitem><para> 5614 <listitem><para>
5576 <emphasis><filename>do_configure_partition()</filename>:</emphasis> 5615 <emphasis><filename>do_configure_partition()</filename>:</emphasis>
5577 Called before 5616 Called before
5578 <filename>do_prepare_partition()</filename>. 5617 <filename>do_prepare_partition()</filename> to
5579 This method is typically used to create custom 5618 create custom configuration files for a partition
5580 configuration files for a partition (e.g. syslinux 5619 (e.g. syslinux or grub configuration files).
5581 or grub configuration files).
5582 </para></listitem> 5620 </para></listitem>
5583 <listitem><para> 5621 <listitem><para>
5584 <emphasis><filename>do_install_disk()</filename>:</emphasis> 5622 <emphasis><filename>do_install_disk()</filename>:</emphasis>
5585 Called after all partitions have been prepared and 5623 Called after all partitions have been prepared and
5586 assembled into a disk image. 5624 assembled into a disk image.
5587 This method provides a hook to allow finalization 5625 This method provides a hook to allow finalization
5588 of a disk image, (e.g. writing an MBR). 5626 of a disk image (e.g. writing an MBR).
5589 </para></listitem> 5627 </para></listitem>
5590 <listitem><para> 5628 <listitem><para>
5591 <emphasis><filename>do_stage_partition()</filename>:</emphasis> 5629 <emphasis><filename>do_stage_partition()</filename>:</emphasis>
5592 Special content-staging hook called before 5630 Special content-staging hook called before
5593 <filename>do_prepare_partition()</filename>. 5631 <filename>do_prepare_partition()</filename>.
5594 This method is normally empty.</para> 5632 This method is normally empty.</para>
5633
5595 <para>Typically, a partition just uses the passed-in 5634 <para>Typically, a partition just uses the passed-in
5596 parameters (e.g. the unmodified value of 5635 parameters (e.g. the unmodified value of
5597 <filename>bootimg_dir</filename>). 5636 <filename>bootimg_dir</filename>).
5598 However, in some cases things might need to be 5637 However, in some cases, things might need to be
5599 more tailored. 5638 more tailored.
5600 As an example, certain files might additionally 5639 As an example, certain files might additionally
5601 need to be taken from 5640 need to be taken from
@@ -5605,27 +5644,26 @@
5605 <note> 5644 <note>
5606 <filename>get_bitbake_var()</filename> 5645 <filename>get_bitbake_var()</filename>
5607 allows you to access non-standard variables 5646 allows you to access non-standard variables
5608 that you might want to use for this. 5647 that you might want to use for this
5648 behavior.
5609 </note> 5649 </note>
5610 </para></listitem> 5650 </para></listitem>
5611 </itemizedlist> 5651 </itemizedlist>
5612 </para> 5652 </para>
5613 5653
5614 <para> 5654 <para>
5615 This scheme is extensible. 5655 You can extend the source plug-in mechanism.
5616 Adding more hooks is a simple matter of adding more 5656 To add more hooks, create more source plug-in methods
5617 plug-in methods to <filename>SourcePlugin</filename> and 5657 within <filename>SourcePlugin</filename> and the
5618 derived classes. 5658 corresponding derived subclasses.
5619 The code that then needs to call the plug-in methods uses 5659 The code that calls the plug-in methods uses the
5620 <filename>plugin.get_source_plugin_methods()</filename> 5660 <filename>plugin.get_source_plugin_methods()</filename>
5621 to find the method or methods needed by the call. 5661 function to find the method or methods needed by the call.
5622 Retrieval of those methods is accomplished 5662 Retrieval of those methods is accomplished by filling up
5623 by filling up a dict with keys 5663 a dict with keys that contain the method names of interest.
5624 containing the method names of interest.
5625 On success, these will be filled in with the actual 5664 On success, these will be filled in with the actual
5626 methods. 5665 methods.
5627 Please see the Wic 5666 See the Wic implementation for examples and details.
5628 implementation for examples and details.
5629 </para> 5667 </para>
5630 </section> 5668 </section>
5631 5669