dev-manual, ref-manual: Moved Wic Plug-In section to dev-manual

Fixes [YOCTO #12370]

I had a section on Wick Plug-Ins in the ref-manual in the
"technical details" chapter.  This section has been combined with the
section on using Wic that lives in the dev-manual.  This move creates
a single section on using Wic to create Wic-partitioned images.

The section was moved out of the ref-manual and merged into the
dev-manual Wic section.

(From yocto-docs rev: 8724049141c9a793312dcf5ff5c3425948d1cbd0)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 209 insertions, 4 deletions

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
-            "<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'>
@@ -5265,6 +5266,210 @@
             </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>