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'>
</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>
</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>
projects / thirdparty / openembedded / openembedded-core-contrib.git / commitdiff
