ref-manual, dev-manual: Moved plug-in section for wic to ref-manual

Fixed links affected by the move.

(From yocto-docs rev: 250d312274788b0eebf3ae9143f2f89eafd4ab90)

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

1 files changed, 207 insertions, 0 deletions

diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index f566ec243a..0cfc6e675e 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -1252,6 +1252,213 @@
     </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'>Creating Partitioned Images</ulink>"
+        section in the Yocto Project Development 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='x32'>
     <title>x32</title>