summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml153
1 files changed, 153 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index be95c0f405..7f796fc037 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -4007,6 +4007,159 @@
4007 </section> 4007 </section>
4008 </section> 4008 </section>
4009 4009
4010 <section id='openembedded-kickstart-plugins'>
4011 <title>Plugins</title>
4012
4013 <para>
4014 Plugins allow <filename>wic</filename> functionality to
4015 be extended and specialized by users.
4016 This section documents the plugin interface, which is
4017 currently restricted to source plugins.
4018 </para>
4019
4020 <para>
4021 Source plugins provide a mechanism to customize
4022 various aspects of the image generation process in
4023 <filename>wic</filename>, mainly the contents of
4024 partitions.
4025 The plugins provide a mechanism for mapping values
4026 specified in <filename>.wks</filename> files using the
4027 <filename>&dash;&dash;source</filename> keyword to a
4028 particular plugin implementation that populates a
4029 corresponding partition.
4030 </para>
4031
4032 <para>
4033 A source plugin is created as a subclass of
4034 <filename>SourcePlugin</filename>.
4035 The plugin file containing it is added to
4036 <filename>scripts/lib/mic/plugins/source/</filename> to
4037 make the plugin implementation available to the
4038 <filename>wic</filename> implementation.
4039 For more information, see
4040 <filename>scripts/lib/mic/pluginbase.py</filename>.
4041 </para>
4042
4043 <para>
4044 Source plugins can also be implemented and added by
4045 external layers.
4046 As such, any plugins found in a
4047 <filename>scripts/lib/mic/plugins/source/</filename>
4048 directory in an external layer are also made
4049 available.
4050 </para>
4051
4052 <para>
4053 When the <filename>wic</filename> implementation needs
4054 to invoke a partition-specific implementation, it looks
4055 for the plugin that has the same name as the
4056 <filename>&dash;&dash;source</filename> parameter given to
4057 that partition.
4058 For example, if the partition is set up as follows:
4059 <literallayout class='monospaced'>
4060 part /boot --source bootimg-pcbios ...
4061 </literallayout>
4062 The methods defined as class members of the plugin
4063 having the matching <filename>bootimg-pcbios.name</filename>
4064 class member are used.
4065 </para>
4066
4067 <para>
4068 To be more concrete, here is the plugin definition that
4069 matches a
4070 <filename>'&dash;&dash;source bootimg-pcbios'</filename> usage,
4071 along with an example
4072 method called by the <filename>wic</filename> implementation
4073 when it needs to invoke an implementation-specific
4074 partition-preparation function:
4075 <literallayout class='monospaced'>
4076 class BootimgPcbiosPlugin(SourcePlugin):
4077 name = 'bootimg-pcbios'
4078
4079 @classmethod
4080 def do_prepare_partition(self, part, ...)
4081 </literallayout>
4082 If the subclass itself does not implement a function, a
4083 default version in a superclass is located and
4084 used, which is why all plugins must be derived from
4085 <filename>SourcePlugin</filename>.
4086 </para>
4087
4088 <para>
4089 The <filename>SourcePlugin</filename> class defines the
4090 following methods, which is the current set of methods
4091 that can be implemented or overridden by
4092 <filename>&dash;&dash;source</filename> plugins.
4093 Any methods not implemented by a
4094 <filename>SourcePlugin</filename> subclass inherit the
4095 implementations present in the
4096 <filename>SourcePlugin</filename> class.
4097 For more information, see the
4098 <filename>SourcePlugin</filename> source for details:
4099 </para>
4100
4101 <para>
4102 <itemizedlist>
4103 <listitem><para><emphasis><filename>do_prepare_partition()</filename>:</emphasis>
4104 Called to do the actual content population for a
4105 partition.
4106 In other words, the method prepares the final
4107 partition image that is incorporated into the
4108 disk image.
4109 </para></listitem>
4110 <listitem><para><emphasis><filename>do_configure_partition()</filename>:</emphasis>
4111 Called before
4112 <filename>do_prepare_partition()</filename>.
4113 This method is typically used to create custom
4114 configuration files for a partition (e.g. syslinux or
4115 grub configuration files).
4116 </para></listitem>
4117 <listitem><para><emphasis><filename>do_install_disk()</filename>:</emphasis>
4118 Called after all partitions have been prepared and
4119 assembled into a disk image.
4120 This method provides a hook to allow finalization of a
4121 disk image, (e.g. writing an MBR).
4122 </para></listitem>
4123 <listitem><para><emphasis><filename>do_stage_partition()</filename>:</emphasis>
4124 Special content-staging hook called before
4125 <filename>do_prepare_partition()</filename>.
4126 This method is normally empty.</para>
4127 <para>Typically, a partition just uses the passed-in
4128 parameters (e.g. the unmodified value of
4129 <filename>bootimg_dir</filename>).
4130 However, in some cases things might need to be
4131 more tailored.
4132 As an example, certain files might additionally
4133 need to be taken from
4134 <filename>bootimg_dir + /boot</filename>.
4135 This hook allows those files to be staged in a
4136 customized fashion.
4137 <note>
4138 <filename>get_bitbake_var()</filename>
4139 allows you to access non-standard variables
4140 that you might want to use for this.
4141 </note>
4142 </para></listitem>
4143 </itemizedlist>
4144 </para>
4145
4146 <para>
4147 This scheme is extensible.
4148 Adding more hooks is a simple matter of adding more
4149 plugin methods to <filename>SourcePlugin</filename> and
4150 derived classes.
4151 The code that then needs to call the plugin methods uses
4152 <filename>plugin.get_source_plugin_methods()</filename>
4153 to find the method or methods needed by the call.
4154 Location is accomplished by filling up a dict with keys
4155 containing the method names of interest.
4156 On success, these will be filled in with the actual
4157 methods.
4158 Please see the <filename>wic</filename>
4159 implementation for examples and details.
4160 </para>
4161 </section>
4162
4010 <section id='openembedded-kickstart-wks-reference'> 4163 <section id='openembedded-kickstart-wks-reference'>
4011 <title>OpenEmbedded Kickstart (.wks) Reference</title> 4164 <title>OpenEmbedded Kickstart (.wks) Reference</title>
4012 4165