diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 58bb6012ce..78825c7f1e 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -4878,16 +4878,17 @@
customized images, and as such, was designed to be
completely extensible through a plug-in interface.
See the
- "Wic Plug-Ins Interface"
- section in the Yocto Project Reference Manual for information
- on these plug-ins.
+ "Using the Wic Plug-Ins Interface"
+ section for information on these plug-ins.
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.
@@ -5265,6 +5266,210 @@
+
+ Using the Wic Plug-Ins Interface
+
+
+ You can extend and specialize Wic functionality by using
+ Wic plug-ins.
+ This section explains the Wic plug-in interface.
+
+ Wic plug-ins consist of "source" and "imager" plug-ins.
+ Imager plug-ins are beyond the scope of this section.
+
+
+
+
+ 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 --source commands in kickstart
+ files (i.e. *.wks) to a plug-in
+ implementation used to populate a given partition.
+
+ 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
+ WKS_FILE_DEPENDS
+ variable.
+
+
+
+
+ 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
+ here.
+ Each of these plug-in files contains source plug-ins that
+ are designed to populate a specific Wic image partition.
+
+
+
+ Source plug-ins are subclasses of the
+ SourcePlugin class, which is
+ defined in the
+ poky/scripts/lib/wic/pluginbase.py
+ file.
+ For example, the BootimgEFIPlugin
+ source plug-in found in the
+ bootimg-efi.py file is a subclass of
+ the SourcePlugin class, which is found
+ in the pluginbase.py file.
+
+
+
+ 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
+ scripts/lib/wic/plugins/source/
+ within your external layer.
+ When the plug-in files are located there, the source
+ plug-ins they contain are made available to Wic.
+
+
+
+ When the Wic implementation needs to invoke a
+ partition-specific implementation, it looks for the plug-in
+ with the same name as the --source
+ 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:
+
+ part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
+
+ The methods defined as class members of the matching
+ source plug-in (i.e. bootimg-pcbios)
+ in the bootimg-pcbios.py plug-in file
+ are used.
+
+
+
+ To be more concrete, here is the corresponding plug-in
+ definition from the bootimg-pcbios.py
+ 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:
+
+ 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.
+ """
+ .
+ .
+ .
+
+ 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 SourcePlugin class.
+
+
+
+ The SourcePlugin class defined in
+ the pluginbase.py file defines
+ a set of methods that source plug-ins can implement or
+ override.
+ Any plug-ins (subclass of
+ SourcePlugin) that do not implement
+ a particular method inherit the implementation of the
+ method from the SourcePlugin class.
+ For more information, see the
+ SourcePlugin class in the
+ pluginbase.py file for details:
+
+
+
+ The following list describes the methods implemented in the
+ SourcePlugin class:
+
+
+ do_prepare_partition():
+ 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.
+
+
+ do_configure_partition():
+ Called before
+ do_prepare_partition() to
+ create custom configuration files for a partition
+ (e.g. syslinux or grub configuration files).
+
+
+ do_install_disk():
+ 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).
+
+
+ do_stage_partition():
+ Special content-staging hook called before
+ do_prepare_partition().
+ This method is normally empty.
+
+ Typically, a partition just uses the passed-in
+ parameters (e.g. the unmodified value of
+ bootimg_dir).
+ However, in some cases, things might need to be
+ more tailored.
+ As an example, certain files might additionally
+ need to be taken from
+ bootimg_dir + /boot.
+ This hook allows those files to be staged in a
+ customized fashion.
+
+ get_bitbake_var()
+ allows you to access non-standard variables
+ that you might want to use for this
+ behavior.
+
+
+
+
+
+
+ You can extend the source plug-in mechanism.
+ To add more hooks, create more source plug-in methods
+ within SourcePlugin and the
+ corresponding derived subclasses.
+ The code that calls the plug-in methods uses the
+ plugin.get_source_plugin_methods()
+ 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.
+
+
+
Examples
diff --git a/documentation/ref-manual/ref-kickstart.xml b/documentation/ref-manual/ref-kickstart.xml
index 1dd36b242c..ab3d1b8ef1 100644
--- a/documentation/ref-manual/ref-kickstart.xml
+++ b/documentation/ref-manual/ref-kickstart.xml
@@ -107,8 +107,9 @@
The most common value for this option is "rootfs", but you
can use any value that maps to a valid source plug-in.
For information on the source plug-ins, see the
- "Wic Plug-Ins Interface"
- section.
+ "Using the Wic Plug-Ins Interface"
+ section in the Yocto Project Development Tasks Manual.
+
If you use --source rootfs, Wic
creates a partition as large as needed and to fill it with
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 1ac020a5cf..5769cd619a 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -1255,213 +1255,6 @@
-
- Wic Plug-Ins Interface
-
-
- 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
- "Creating Partitioned Images Using Wic"
- section in the Yocto Project Development Tasks Manual.
-
- Wic plug-ins consist of "source" and "imager" plug-ins.
- Imager plug-ins are beyond the scope of this section.
-
-
-
-
- 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 --source commands in kickstart
- files (i.e. *.wks) to a plug-in
- implementation used to populate a given partition.
-
- 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
- WKS_FILE_DEPENDS
- variable.
-
-
-
-
- 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
- here.
- Each of these plug-in files contain source plug-ins that
- are designed to populate a specific Wic image partition.
-
-
-
- Source plug-ins are subclasses of the
- SourcePlugin class, which is
- defined in the
- poky/scripts/lib/wic/pluginbase.py
- file.
- For example, the BootimgEFIPlugin
- source plug-in found in the
- bootimg-efi.py file is a subclass of
- the SourcePlugin class, which is found
- in the pluginbase.py file.
-
-
-
- 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
- scripts/lib/wic/plugins/source/
- within your external layer.
- When the plug-in files are located there, the source
- plug-ins they contain are made available to Wic.
-
-
-
- When the Wic implementation needs to invoke a
- partition-specific implementation, it looks for the plug-in
- with the same name as the --source
- 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:
-
- part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
-
- The methods defined as class members of the matching
- source plug-in (i.e. bootimg-pcbios)
- in the bootimg-pcbios.py plug-in file
- are used.
-
-
-
- To be more concrete, here is the corresponding plug-in
- definition from the bootimg-pcbios.py
- 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:
-
- 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.
- """
- .
- .
- .
-
- 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 SourcePlugin class.
-
-
-
- The SourcePlugin class defined in
- the pluginbase.py file defines
- a set of methods that source plug-ins can implement or
- override.
- Any plug-ins (subclass of
- SourcePlugin) that do not implement
- a particular method inherit the implementation of the
- method from the SourcePlugin class.
- For more information, see the
- SourcePlugin class in the
- pluginbase.py file for details:
-
-
-
- The following list describes the methods implemented in the
- SourcePlugin class:
-
-
- do_prepare_partition():
- 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.
-
-
- do_configure_partition():
- Called before
- do_prepare_partition() to
- create custom configuration files for a partition
- (e.g. syslinux or grub configuration files).
-
-
- do_install_disk():
- 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).
-
-
- do_stage_partition():
- Special content-staging hook called before
- do_prepare_partition().
- This method is normally empty.
-
- Typically, a partition just uses the passed-in
- parameters (e.g. the unmodified value of
- bootimg_dir).
- However, in some cases, things might need to be
- more tailored.
- As an example, certain files might additionally
- need to be taken from
- bootimg_dir + /boot.
- This hook allows those files to be staged in a
- customized fashion.
-
- get_bitbake_var()
- allows you to access non-standard variables
- that you might want to use for this
- behavior.
-
-
-
-
-
-
- You can extend the source plug-in mechanism.
- To add more hooks, create more source plug-in methods
- within SourcePlugin and the
- corresponding derived subclasses.
- The code that calls the plug-in methods uses the
- plugin.get_source_plugin_methods()
- 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.
-
-
-
Wayland