summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-10-11 13:29:14 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-10-16 23:46:52 +0100
commit6077ebbe806bb232e3d96b0f138e1f4748e5ef5b (patch)
treef875bca0e44753c576cf2e67879e83e573919ff4 /documentation
parent6cee5c8b9b07b1c660e8fdea7a3cb85d4ac238f6 (diff)
downloadpoky-6077ebbe806bb232e3d96b0f138e1f4748e5ef5b.tar.gz
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>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml1110
-rw-r--r--documentation/ref-manual/technical-details.xml207
2 files changed, 653 insertions, 664 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index a5fe63ac9d..3f4c2802ce 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -4796,24 +4796,138 @@
4796 </para> 4796 </para>
4797 4797
4798 <para> 4798 <para>
4799 You can generate partitioned images 4799 The <filename>wic</filename> command generates partitioned
4800 (<replaceable>image</replaceable><filename>.wic</filename>) 4800 images from existing OpenEmbedded build artifacts.
4801 two ways: using the OpenEmbedded build system and by running 4801 Image generation is driven by partitioning commands
4802 the OpenEmbedded Image Creator Wic directly. 4802 contained in an Openembedded kickstart file
4803 The former way is preferable as it is easier to use and understand. 4803 (<filename>.wks</filename>) specified either directly on
4804 the command line or as one of a selection of canned
4805 kickstart files as shown with the
4806 <filename>wic list images</filename> command in the
4807 "<link linkend='using-a-provided-kickstart-file'>Using an Existing Kickstart File</link>"
4808 section.
4809 When you apply the command to a given set of build
4810 artifacts, the result is an image or set of images that
4811 can be directly written onto media and used on a particular
4812 system.
4813 <note>
4814 For a kickstart file reference, see the
4815 "<link linkend='openembedded-kickstart-wks-reference'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</link>"
4816 section.
4817 </note>
4818 </para>
4819
4820 <para>
4821 The <filename>wic</filename> command and the infrastructure
4822 it is based on is by definition incomplete.
4823 The purpose of the command is to allow the generation of
4824 customized images, and as such, was designed to be
4825 completely extensible through a plug-in interface.
4826 See the
4827 "<ulink url='&YOCTO_DOCS_REF_URL;#wic-plug-ins-interface'>Wic Plug-Ins Interface</ulink>"
4828 section in the Yocto Project Reference Manual for information
4829 on these plug-ins.
4830 </para>
4831
4832 <para>
4833 This section provides some background information on Wic,
4834 describes what you need to have in
4835 place to run the tool, provides instruction on how to use
4836 the Wic utility, and provides several examples.
4804 </para> 4837 </para>
4805 4838
4806 <section id='creating-wic-images-oe'> 4839 <section id='wic-background'>
4807 <title>Creating Partitioned Images</title> 4840 <title>Background</title>
4808 4841
4809 <para> 4842 <para>
4810 The OpenEmbedded build system can generate 4843 This section provides some background on the Wic utility.
4811 partitioned images the same way as it generates 4844 While none of this information is required to use
4812 any other image type. 4845 Wic, you might find it interesting.
4813 To generate a partitioned image, you need to modify
4814 two variables.
4815 <itemizedlist> 4846 <itemizedlist>
4816 <listitem><para> 4847 <listitem><para>
4848 The name "Wic" is derived from OpenEmbedded
4849 Image Creator (oeic).
4850 The "oe" diphthong in "oeic" was promoted to the
4851 letter "w", because "oeic" is both difficult to
4852 remember and to pronounce.
4853 </para></listitem>
4854 <listitem><para>
4855 Wic is loosely based on the
4856 Meego Image Creator (<filename>mic</filename>)
4857 framework.
4858 The Wic implementation has been
4859 heavily modified to make direct use of OpenEmbedded
4860 build artifacts instead of package installation and
4861 configuration, which are already incorporated within
4862 the OpenEmbedded artifacts.
4863 </para></listitem>
4864 <listitem><para>
4865 Wic is a completely independent
4866 standalone utility that initially provides
4867 easier-to-use and more flexible replacements for an
4868 existing functionality in OE Core's
4869 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink>
4870 class and <filename>mkefidisk.sh</filename> script.
4871 The difference between
4872 Wic and those examples is
4873 that with Wic the
4874 functionality of those scripts is implemented
4875 by a general-purpose partitioning language, which is
4876 based on Redhat kickstart syntax.</para></listitem>
4877 </itemizedlist>
4878 </para>
4879 </section>
4880
4881 <section id='wic-requirements'>
4882 <title>Requirements</title>
4883
4884 <para>
4885 In order to use the Wic utility with the OpenEmbedded Build
4886 system, your system needs to meet the following
4887 requirements:
4888 <itemizedlist>
4889 <listitem><para>
4890 The Linux distribution on your development host must
4891 support the Yocto Project.
4892 See the
4893 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
4894 section in the Yocto Project Reference Manual for
4895 the list of distributions that support the
4896 Yocto Project.
4897 </para></listitem>
4898 <listitem><para>
4899 The standard system utilities, such as
4900 <filename>cp</filename>, must be installed on your
4901 development host system.
4902 </para></listitem>
4903 <listitem><para>
4904 You must have sourced the build environment
4905 setup script (i.e.
4906 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>)
4907 found in the
4908 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
4909 </para></listitem>
4910 <listitem><para>
4911 You need to have the build artifacts already
4912 available, which typically means that you must
4913 have already created an image using the
4914 Openembedded build system (e.g.
4915 <filename>core-image-minimal</filename>).
4916 While it might seem redundant to generate an image
4917 in order to create an image using
4918 Wic, the current version of
4919 Wic requires the artifacts
4920 in the form generated by the OpenEmbedded build
4921 system.
4922 </para></listitem>
4923 <listitem><para>
4924 You must build several native tools, which are
4925 built to run on the build system:
4926 <literallayout class='monospaced'>
4927 $ bitbake parted-native dosfstools-native mtools-native
4928 </literallayout>
4929 </para></listitem>
4930 <listitem><para>
4817 Include "wic" as part of the 4931 Include "wic" as part of the
4818 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink> 4932 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
4819 variable. 4933 variable.
@@ -4826,198 +4940,61 @@
4826 variable 4940 variable
4827 </para></listitem> 4941 </para></listitem>
4828 </itemizedlist> 4942 </itemizedlist>
4829 Further steps to generate a partitioned image
4830 are the same as for any other image type.
4831 For information on image types, see the
4832 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
4833 section in the Yocto Project Reference Manual.
4834 </para> 4943 </para>
4835 </section> 4944 </section>
4836 4945
4837 <section id='create-wic-images-wic'> 4946 <section id='wic-getting-help'>
4838 <title>Using OpenEmbedded Image Creator Wic to Generate Partitioned Images</title> 4947 <title>Getting Help</title>
4839 4948
4840 <para> 4949 <para>
4841 The <filename>wic</filename> command generates partitioned 4950 You can get general help for the <filename>wic</filename>
4842 images from existing OpenEmbedded build artifacts. 4951 command by entering the <filename>wic</filename> command
4843 Image generation is driven by partitioning commands 4952 by itself or by entering the command with a help argument
4844 contained in an Openembedded kickstart file 4953 as follows:
4845 (<filename>.wks</filename>) specified either directly on 4954 <literallayout class='monospaced'>
4846 the command line or as one of a selection of canned 4955 $ wic -h
4847 kickstart files as shown with the 4956 $ wic --help
4848 <filename>wic list images</filename> command in the 4957 </literallayout>
4849 "<link linkend='using-a-provided-kickstart-file'>Using an Existing Kickstart File</link>"
4850 section.
4851 When you apply the command to a given set of build
4852 artifacts, the result is an image or set of images that
4853 can be directly written onto media and used on a particular
4854 system.
4855 </para> 4958 </para>
4856 4959
4857 <para> 4960 <para>
4858 The <filename>wic</filename> command and the infrastructure 4961 Currently, Wic supports seven commands:
4859 it is based on is by definition incomplete. 4962 <filename>cp</filename>, <filename>create</filename>,
4860 The purpose of the command is to allow the generation of 4963 <filename>help</filename>, <filename>list</filename>,
4861 customized images, and as such, was designed to be 4964 <filename>ls</filename>, <filename>rm</filename>, and
4862 completely extensible through a plug-in interface. 4965 <filename>write</filename>.
4863 See the 4966 You can get help for these commands as follows with
4864 "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>" 4967 <replaceable>command</replaceable> being one of the
4865 section for information on these plug-ins. 4968 supported commands:
4969 <literallayout class='monospaced'>
4970 $ wic help <replaceable>command</replaceable>
4971 </literallayout>
4866 </para> 4972 </para>
4867 4973
4868 <para> 4974 <para>
4869 This section provides some background information on Wic, 4975 You can also get detailed help on a number of topics
4870 describes what you need to have in 4976 from the help system.
4871 place to run the tool, provides instruction on how to use 4977 The output of <filename>wic --help</filename>
4872 the Wic utility, and provides several examples. 4978 displays a list of available help
4873 </para> 4979 topics under a "Help topics" heading.
4874 4980 You can have the help system display the help text for
4875 <section id='wic-background'> 4981 a given topic by prefacing the topic with
4876 <title>Background</title> 4982 <filename>wic help</filename>:
4877 4983 <literallayout class='monospaced'>
4878 <para>
4879 This section provides some background on the Wic utility.
4880 While none of this information is required to use
4881 Wic, you might find it interesting.
4882 <itemizedlist>
4883 <listitem><para>
4884 The name "Wic" is derived from OpenEmbedded
4885 Image Creator (oeic).
4886 The "oe" diphthong in "oeic" was promoted to the
4887 letter "w", because "oeic" is both difficult to
4888 remember and to pronounce.
4889 </para></listitem>
4890 <listitem><para>
4891 Wic is loosely based on the
4892 Meego Image Creator (<filename>mic</filename>)
4893 framework.
4894 The Wic implementation has been
4895 heavily modified to make direct use of OpenEmbedded
4896 build artifacts instead of package installation and
4897 configuration, which are already incorporated within
4898 the OpenEmbedded artifacts.
4899 </para></listitem>
4900 <listitem><para>
4901 Wic is a completely independent
4902 standalone utility that initially provides
4903 easier-to-use and more flexible replacements for an
4904 existing functionality in OE Core's
4905 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink>
4906 class and <filename>mkefidisk.sh</filename> script.
4907 The difference between
4908 Wic and those examples is
4909 that with Wic the
4910 functionality of those scripts is implemented
4911 by a general-purpose partitioning language, which is
4912 based on Redhat kickstart syntax.</para></listitem>
4913 </itemizedlist>
4914 </para>
4915 </section>
4916
4917 <section id='wic-requirements'>
4918 <title>Requirements</title>
4919
4920 <para>
4921 In order to use the Wic utility with the OpenEmbedded Build
4922 system, your system needs to meet the following
4923 requirements:
4924 <itemizedlist>
4925 <listitem><para>The Linux distribution on your
4926 development host must support the Yocto Project.
4927 See the
4928 "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
4929 section in the Yocto Project Reference Manual for
4930 the list of distributions that support the
4931 Yocto Project.
4932 </para></listitem>
4933 <listitem><para>
4934 The standard system utilities, such as
4935 <filename>cp</filename>, must be installed on your
4936 development host system.
4937 </para></listitem>
4938 <listitem><para>
4939 You must have sourced the build environment
4940 setup script (i.e.
4941 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>)
4942 found in the
4943 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
4944 </para></listitem>
4945 <listitem><para>
4946 You need to have the build artifacts already
4947 available, which typically means that you must
4948 have already created an image using the
4949 Openembedded build system (e.g.
4950 <filename>core-image-minimal</filename>).
4951 While it might seem redundant to generate an image
4952 in order to create an image using
4953 Wic, the current version of
4954 Wic requires the artifacts
4955 in the form generated by the OpenEmbedded build
4956 system.
4957 </para></listitem>
4958 <listitem><para>
4959 You must build several native tools, which are
4960 built to run on the build system:
4961 <literallayout class='monospaced'>
4962 $ bitbake parted-native dosfstools-native mtools-native
4963 </literallayout>
4964 </para></listitem>
4965 </itemizedlist>
4966 </para>
4967 </section>
4968
4969 <section id='wic-getting-help'>
4970 <title>Getting Help</title>
4971
4972 <para>
4973 You can get general help for the <filename>wic</filename>
4974 command by entering the <filename>wic</filename> command
4975 by itself or by entering the command with a help argument
4976 as follows:
4977 <literallayout class='monospaced'>
4978 $ wic -h
4979 $ wic --help
4980 </literallayout>
4981 </para>
4982
4983 <para>
4984 Currently, Wic supports seven commands:
4985 <filename>cp</filename>, <filename>create</filename>,
4986 <filename>help</filename>, <filename>list</filename>,
4987 <filename>ls</filename>, <filename>rm</filename>, and
4988 <filename>write</filename>.
4989 You can get help for these commands as follows with
4990 <replaceable>command</replaceable> being one of the
4991 supported commands:
4992 <literallayout class='monospaced'>
4993 $ wic help <replaceable>command</replaceable>
4994 </literallayout>
4995 </para>
4996
4997 <para>
4998 You can also get detailed help on a number of topics
4999 from the help system.
5000 The output of <filename>wic --help</filename>
5001 displays a list of available help
5002 topics under a "Help topics" heading.
5003 You can have the help system display the help text for
5004 a given topic by prefacing the topic with
5005 <filename>wic help</filename>:
5006 <literallayout class='monospaced'>
5007 $ wic help <replaceable>help_topic</replaceable> 4984 $ wic help <replaceable>help_topic</replaceable>
5008 </literallayout> 4985 </literallayout>
5009 </para> 4986 </para>
5010 4987
5011 <para> 4988 <para>
5012 You can find out more about the images Wic creates using 4989 You can find out more about the images Wic creates using
5013 the existing kickstart files with the following form of 4990 the existing kickstart files with the following form of
5014 the command: 4991 the command:
5015 <literallayout class='monospaced'> 4992 <literallayout class='monospaced'>
5016 $ wic list <replaceable>image</replaceable> help 4993 $ wic list <replaceable>image</replaceable> help
5017 </literallayout> 4994 </literallayout>
5018 For <replaceable>image</replaceable>, you can provide 4995 For <replaceable>image</replaceable>, you can provide
5019 any of the following: 4996 any of the following:
5020 <literallayout class='monospaced'> 4997 <literallayout class='monospaced'>
5021 beaglebone 4998 beaglebone
5022 mpc8315e-rdb 4999 mpc8315e-rdb
5023 genericx86 5000 genericx86
@@ -5031,62 +5008,62 @@
5031 sdimage-bootpart 5008 sdimage-bootpart
5032 directdisk-multi-rootfs 5009 directdisk-multi-rootfs
5033 directdisk-bootloader-config 5010 directdisk-bootloader-config
5034 </literallayout> 5011 </literallayout>
5035 </para> 5012 </para>
5036 </section> 5013 </section>
5037 5014
5038 <section id='operational-modes'> 5015 <section id='operational-modes'>
5039 <title>Operational Modes</title> 5016 <title>Operational Modes</title>
5040 5017
5041 <para> 5018 <para>
5042 You can use Wic in two different 5019 You can use Wic in two different
5043 modes, depending on how much control you need for 5020 modes, depending on how much control you need for
5044 specifying the Openembedded build artifacts that are 5021 specifying the Openembedded build artifacts that are
5045 used for creating the image: Raw and Cooked: 5022 used for creating the image: Raw and Cooked:
5046 <itemizedlist> 5023 <itemizedlist>
5047 <listitem><para> 5024 <listitem><para>
5048 <emphasis>Raw Mode:</emphasis> 5025 <emphasis>Raw Mode:</emphasis>
5049 You explicitly specify build artifacts through 5026 You explicitly specify build artifacts through
5050 <filename>wic</filename> command-line arguments. 5027 <filename>wic</filename> command-line arguments.
5051 </para></listitem> 5028 </para></listitem>
5052 <listitem><para> 5029 <listitem><para>
5053 <emphasis>Cooked Mode:</emphasis> 5030 <emphasis>Cooked Mode:</emphasis>
5054 The current 5031 The current
5055 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> 5032 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
5056 setting and image name are used to automatically 5033 setting and image name are used to automatically
5057 locate and provide the build artifacts. 5034 locate and provide the build artifacts.
5058 You just supply a kickstart file and the name 5035 You just supply a kickstart file and the name
5059 of the image from which to use artifacts. 5036 of the image from which to use artifacts.
5060 </para></listitem> 5037 </para></listitem>
5061 </itemizedlist> 5038 </itemizedlist>
5062 </para> 5039 </para>
5063 5040
5064 <para> 5041 <para>
5065 Regardless of the mode you use, you need to have the build 5042 Regardless of the mode you use, you need to have the build
5066 artifacts ready and available. 5043 artifacts ready and available.
5067 </para> 5044 </para>
5068 5045
5069 <section id='raw-mode'> 5046 <section id='raw-mode'>
5070 <title>Raw Mode</title> 5047 <title>Raw Mode</title>
5071 5048
5072 <para> 5049 <para>
5073 Running Wic in raw mode allows you to specify all the 5050 Running Wic in raw mode allows you to specify all the
5074 partitions through the <filename>wic</filename> 5051 partitions through the <filename>wic</filename>
5075 command line. 5052 command line.
5076 The primary use for raw mode is if you have built 5053 The primary use for raw mode is if you have built
5077 your kernel outside of the Yocto Project 5054 your kernel outside of the Yocto Project
5078 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>. 5055 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
5079 In other words, you can point to arbitrary kernel, 5056 In other words, you can point to arbitrary kernel,
5080 root filesystem locations, and so forth. 5057 root filesystem locations, and so forth.
5081 Contrast this behavior with cooked mode where Wic 5058 Contrast this behavior with cooked mode where Wic
5082 looks in the Build Directory (e.g. 5059 looks in the Build Directory (e.g.
5083 <filename>tmp/deploy/images/</filename><replaceable>machine</replaceable>). 5060 <filename>tmp/deploy/images/</filename><replaceable>machine</replaceable>).
5084 </para> 5061 </para>
5085 5062
5086 <para> 5063 <para>
5087 The general form of the 5064 The general form of the
5088 <filename>wic</filename> command in raw mode is: 5065 <filename>wic</filename> command in raw mode is:
5089 <literallayout class='monospaced'> 5066 <literallayout class='monospaced'>
5090 $ wic create <replaceable>wks_file</replaceable> <replaceable>options</replaceable> ... 5067 $ wic create <replaceable>wks_file</replaceable> <replaceable>options</replaceable> ...
5091 5068
5092 Where: 5069 Where:
@@ -5127,36 +5104,36 @@
5127 directory with &lt;image&gt;.env files that store bitbake 5104 directory with &lt;image&gt;.env files that store bitbake
5128 variables 5105 variables
5129 -D, --debug output debug information 5106 -D, --debug output debug information
5130 </literallayout> 5107 </literallayout>
5131 <note> 5108 <note>
5132 You do not need root privileges to run 5109 You do not need root privileges to run
5133 Wic. 5110 Wic.
5134 In fact, you should not run as root when using the 5111 In fact, you should not run as root when using the
5135 utility. 5112 utility.
5136 </note> 5113 </note>
5137 </para> 5114 </para>
5138 </section> 5115 </section>
5139 5116
5140 <section id='cooked-mode'> 5117 <section id='cooked-mode'>
5141 <title>Cooked Mode</title> 5118 <title>Cooked Mode</title>
5142 5119
5143 <para> 5120 <para>
5144 Running Wic in cooked mode leverages off artifacts in 5121 Running Wic in cooked mode leverages off artifacts in
5145 Build Directory. 5122 Build Directory.
5146 In other words, you do not have to specify kernel or 5123 In other words, you do not have to specify kernel or
5147 root filesystem locations as part of the command. 5124 root filesystem locations as part of the command.
5148 All you need to provide is a kickstart file and the 5125 All you need to provide is a kickstart file and the
5149 name of the image from which to use artifacts by using 5126 name of the image from which to use artifacts by using
5150 the "-e" option. 5127 the "-e" option.
5151 Wic looks in the Build Directory (e.g. 5128 Wic looks in the Build Directory (e.g.
5152 <filename>tmp/deploy/images/</filename><replaceable>machine</replaceable>) 5129 <filename>tmp/deploy/images/</filename><replaceable>machine</replaceable>)
5153 for artifacts. 5130 for artifacts.
5154 </para> 5131 </para>
5155 5132
5156 <para> 5133 <para>
5157 The general form of the <filename>wic</filename> 5134 The general form of the <filename>wic</filename>
5158 command using Cooked Mode is as follows: 5135 command using Cooked Mode is as follows:
5159 <literallayout class='monospaced'> 5136 <literallayout class='monospaced'>
5160 $ wic create <replaceable>wks_file</replaceable> -e <replaceable>IMAGE_NAME</replaceable> 5137 $ wic create <replaceable>wks_file</replaceable> -e <replaceable>IMAGE_NAME</replaceable>
5161 5138
5162 Where: 5139 Where:
@@ -5171,28 +5148,28 @@
5171 -e <replaceable>IMAGE_NAME</replaceable>, --image-name <replaceable>IMAGE_NAME</replaceable> 5148 -e <replaceable>IMAGE_NAME</replaceable>, --image-name <replaceable>IMAGE_NAME</replaceable>
5172 name of the image to use the artifacts from e.g. core- 5149 name of the image to use the artifacts from e.g. core-
5173 image-sato 5150 image-sato
5174 </literallayout> 5151 </literallayout>
5175 </para> 5152 </para>
5176 </section>
5177 </section> 5153 </section>
5154 </section>
5178 5155
5179 <section id='using-a-provided-kickstart-file'> 5156 <section id='using-a-provided-kickstart-file'>
5180 <title>Using an Existing Kickstart File</title> 5157 <title>Using an Existing Kickstart File</title>
5181 5158
5182 <para> 5159 <para>
5183 If you do not want to create your own kickstart file, you 5160 If you do not want to create your own kickstart file, you
5184 can use an existing file provided by the Wic installation. 5161 can use an existing file provided by the Wic installation.
5185 As shipped, kickstart files can be found in the 5162 As shipped, kickstart files can be found in the
5186 Yocto Project 5163 Yocto Project
5187 <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink> 5164 <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
5188 in the following two locations: 5165 in the following two locations:
5189 <literallayout class='monospaced'> 5166 <literallayout class='monospaced'>
5190 poky/meta-yocto-bsp/wic 5167 poky/meta-yocto-bsp/wic
5191 poky/scripts/lib/wic/canned-wks 5168 poky/scripts/lib/wic/canned-wks
5192 </literallayout> 5169 </literallayout>
5193 Use the following command to list the available kickstart 5170 Use the following command to list the available kickstart
5194 files: 5171 files:
5195 <literallayout class='monospaced'> 5172 <literallayout class='monospaced'>
5196 $ wic list images 5173 $ wic list images
5197 beaglebone Create SD card image for Beaglebone 5174 beaglebone Create SD card image for Beaglebone
5198 mpc8315e-rdb Create SD card image for MPC8315E-RDB 5175 mpc8315e-rdb Create SD card image for MPC8315E-RDB
@@ -5207,22 +5184,22 @@
5207 sdimage-bootpart Create SD card image with a boot partition 5184 sdimage-bootpart Create SD card image with a boot partition
5208 directdisk-multi-rootfs Create multi rootfs image using rootfs plugin 5185 directdisk-multi-rootfs Create multi rootfs image using rootfs plugin
5209 directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config 5186 directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config
5210 </literallayout> 5187 </literallayout>
5211 When you use an existing file, you do not have to use the 5188 When you use an existing file, you do not have to use the
5212 <filename>.wks</filename> extension. 5189 <filename>.wks</filename> extension.
5213 Here is an example in Raw Mode that uses the 5190 Here is an example in Raw Mode that uses the
5214 <filename>directdisk</filename> file: 5191 <filename>directdisk</filename> file:
5215 <literallayout class='monospaced'> 5192 <literallayout class='monospaced'>
5216 $ wic create directdisk -r <replaceable>rootfs_dir</replaceable> -b <replaceable>bootimg_dir</replaceable> \ 5193 $ wic create directdisk -r <replaceable>rootfs_dir</replaceable> -b <replaceable>bootimg_dir</replaceable> \
5217 -k <replaceable>kernel_dir</replaceable> -n <replaceable>native_sysroot</replaceable> 5194 -k <replaceable>kernel_dir</replaceable> -n <replaceable>native_sysroot</replaceable>
5218 </literallayout> 5195 </literallayout>
5219 </para> 5196 </para>
5220 5197
5221 <para> 5198 <para>
5222 Here are the actual partition language commands 5199 Here are the actual partition language commands
5223 used in the <filename>genericx86.wks</filename> file to 5200 used in the <filename>genericx86.wks</filename> file to
5224 generate an image: 5201 generate an image:
5225 <literallayout class='monospaced'> 5202 <literallayout class='monospaced'>
5226 # short-description: Create an EFI disk image for genericx86* 5203 # short-description: Create an EFI disk image for genericx86*
5227 # long-description: Creates a partitioned EFI disk image for genericx86* machines 5204 # long-description: Creates a partitioned EFI disk image for genericx86* machines
5228 part /boot --source bootimg-efi --sourceparams="loader=grub-efi" --ondisk sda --label msdos --active --align 1024 5205 part /boot --source bootimg-efi --sourceparams="loader=grub-efi" --ondisk sda --label msdos --active --align 1024
@@ -5230,30 +5207,30 @@
5230 part swap --ondisk sda --size 44 --label swap1 --fstype=swap 5207 part swap --ondisk sda --size 44 --label swap1 --fstype=swap
5231 5208
5232 bootloader --ptable gpt --timeout=5 --append="rootfstype=ext4 console=ttyS0,115200 console=tty0" 5209 bootloader --ptable gpt --timeout=5 --append="rootfstype=ext4 console=ttyS0,115200 console=tty0"
5233 </literallayout> 5210 </literallayout>
5234 </para> 5211 </para>
5235 </section> 5212 </section>
5236 5213
5237 <section id='wic-usage-examples'> 5214 <section id='wic-usage-examples'>
5238 <title>Examples</title> 5215 <title>Examples</title>
5239 5216
5240 <para> 5217 <para>
5241 This section provides several examples that show how to use 5218 This section provides several examples that show how to use
5242 the Wic utility. 5219 the Wic utility.
5243 All the examples assume the list of requirements in the 5220 All the examples assume the list of requirements in the
5244 "<link linkend='wic-requirements'>Requirements</link>" 5221 "<link linkend='wic-requirements'>Requirements</link>"
5245 section have been met. 5222 section have been met.
5246 The examples assume the previously generated image is 5223 The examples assume the previously generated image is
5247 <filename>core-image-minimal</filename>. 5224 <filename>core-image-minimal</filename>.
5248 </para> 5225 </para>
5249 5226
5250 <section id='generate-an-image-using-a-provided-kickstart-file'> 5227 <section id='generate-an-image-using-a-provided-kickstart-file'>
5251 <title>Generate an Image using an Existing Kickstart File</title> 5228 <title>Generate an Image using an Existing Kickstart File</title>
5252 5229
5253 <para> 5230 <para>
5254 This example runs in Cooked Mode and uses the 5231 This example runs in Cooked Mode and uses the
5255 <filename>mkefidisk</filename> kickstart file: 5232 <filename>mkefidisk</filename> kickstart file:
5256 <literallayout class='monospaced'> 5233 <literallayout class='monospaced'>
5257 $ wic create mkefidisk -e core-image-minimal 5234 $ wic create mkefidisk -e core-image-minimal
5258 INFO: Building wic-tools... 5235 INFO: Building wic-tools...
5259 . 5236 .
@@ -5270,122 +5247,122 @@
5270 5247
5271 INFO: The image(s) were created using OE kickstart file: 5248 INFO: The image(s) were created using OE kickstart file:
5272 /home/scottrif/poky/scripts/lib/wic/canned-wks/mkefidisk.wks 5249 /home/scottrif/poky/scripts/lib/wic/canned-wks/mkefidisk.wks
5273 </literallayout> 5250 </literallayout>
5274 The previous example shows the easiest way to create 5251 The previous example shows the easiest way to create
5275 an image by running in cooked mode and supplying 5252 an image by running in cooked mode and supplying
5276 a kickstart file and the "-e" option to point to the 5253 a kickstart file and the "-e" option to point to the
5277 existing build artifacts. 5254 existing build artifacts.
5278 Your <filename>local.conf</filename> file needs to have 5255 Your <filename>local.conf</filename> file needs to have
5279 the 5256 the
5280 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> 5257 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
5281 variable set to the machine you are using, which is 5258 variable set to the machine you are using, which is
5282 "qemux86" in this example. 5259 "qemux86" in this example.
5283 </para> 5260 </para>
5284 5261
5285 <para> 5262 <para>
5286 Once the image builds, the output provides image 5263 Once the image builds, the output provides image
5287 location, artifact use, and kickstart file information. 5264 location, artifact use, and kickstart file information.
5288 <note> 5265 <note>
5289 You should always verify the details provided in the 5266 You should always verify the details provided in the
5290 output to make sure that the image was indeed 5267 output to make sure that the image was indeed
5291 created exactly as expected. 5268 created exactly as expected.
5292 </note> 5269 </note>
5293 </para> 5270 </para>
5294 5271
5295 <para> 5272 <para>
5296 Continuing with the example, you can now write the 5273 Continuing with the example, you can now write the
5297 image to a USB stick, or whatever media for which you 5274 image to a USB stick, or whatever media for which you
5298 built your image, and boot from the media. 5275 built your image, and boot from the media.
5299 You can write the image by using 5276 You can write the image by using
5300 <filename>bmaptool</filename> or 5277 <filename>bmaptool</filename> or
5301 <filename>dd</filename>: 5278 <filename>dd</filename>:
5302 <literallayout class='monospaced'> 5279 <literallayout class='monospaced'>
5303 $ oe-run-native bmaptool copy build/mkefidisk-201710061409-sda.direct /dev/sd<replaceable>X</replaceable> 5280 $ oe-run-native bmaptool copy build/mkefidisk-201710061409-sda.direct /dev/sd<replaceable>X</replaceable>
5304 </literallayout> 5281 </literallayout>
5305 or 5282 or
5306 <literallayout class='monospaced'> 5283 <literallayout class='monospaced'>
5307 $ sudo dd if=build/mkefidisk-201710061409-sda.direct of=/dev/sd<replaceable>X</replaceable> 5284 $ sudo dd if=build/mkefidisk-201710061409-sda.direct of=/dev/sd<replaceable>X</replaceable>
5308 </literallayout> 5285 </literallayout>
5309 <note> 5286 <note>
5310 For more information on how to use the 5287 For more information on how to use the
5311 <filename>bmaptool</filename> to flash a device 5288 <filename>bmaptool</filename> to flash a device
5312 with an image, see the 5289 with an image, see the
5313 "<link linkend='flashing-images-using-bmaptool'>Flashing Images Using <filename>bmaptool</filename></link>" 5290 "<link linkend='flashing-images-using-bmaptool'>Flashing Images Using <filename>bmaptool</filename></link>"
5314 section. 5291 section.
5315 </note> 5292 </note>
5316 </para> 5293 </para>
5317 </section> 5294 </section>
5318 5295
5319 <section id='using-a-modified-kickstart-file'> 5296 <section id='using-a-modified-kickstart-file'>
5320 <title>Using a Modified Kickstart File</title> 5297 <title>Using a Modified Kickstart File</title>
5321 5298
5322 <para> 5299 <para>
5323 Because partitioned image creation is driven by the 5300 Because partitioned image creation is driven by the
5324 kickstart file, it is easy to affect image creation by 5301 kickstart file, it is easy to affect image creation by
5325 changing the parameters in the file. 5302 changing the parameters in the file.
5326 This next example demonstrates that through modification 5303 This next example demonstrates that through modification
5327 of the <filename>directdisk-gpt</filename> kickstart 5304 of the <filename>directdisk-gpt</filename> kickstart
5328 file. 5305 file.
5329 </para> 5306 </para>
5330 5307
5331 <para> 5308 <para>
5332 As mentioned earlier, you can use the command 5309 As mentioned earlier, you can use the command
5333 <filename>wic list images</filename> to show the list 5310 <filename>wic list images</filename> to show the list
5334 of existing kickstart files. 5311 of existing kickstart files.
5335 The directory in which the 5312 The directory in which the
5336 <filename>directdisk-gpt.wks</filename> file resides is 5313 <filename>directdisk-gpt.wks</filename> file resides is
5337 <filename>scripts/lib/image/canned-wks/</filename>, 5314 <filename>scripts/lib/image/canned-wks/</filename>,
5338 which is located in the 5315 which is located in the
5339 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> 5316 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
5340 (e.g. <filename>poky</filename>). 5317 (e.g. <filename>poky</filename>).
5341 Because available files reside in this directory, 5318 Because available files reside in this directory,
5342 you can create and add your own custom files to the 5319 you can create and add your own custom files to the
5343 directory. 5320 directory.
5344 Subsequent use of the 5321 Subsequent use of the
5345 <filename>wic list images</filename> command would then 5322 <filename>wic list images</filename> command would then
5346 include your kickstart files. 5323 include your kickstart files.
5347 </para> 5324 </para>
5348 5325
5349 <para> 5326 <para>
5350 In this example, the existing 5327 In this example, the existing
5351 <filename>directdisk-gpt</filename> file already does 5328 <filename>directdisk-gpt</filename> file already does
5352 most of what is needed. 5329 most of what is needed.
5353 However, for the hardware in this example, the image 5330 However, for the hardware in this example, the image
5354 will need to boot from <filename>sdb</filename> instead 5331 will need to boot from <filename>sdb</filename> instead
5355 of <filename>sda</filename>, which is what the 5332 of <filename>sda</filename>, which is what the
5356 <filename>directdisk-gpt</filename> kickstart file 5333 <filename>directdisk-gpt</filename> kickstart file
5357 uses. 5334 uses.
5358 </para> 5335 </para>
5359 5336
5360 <para> 5337 <para>
5361 The example begins by making a copy of the 5338 The example begins by making a copy of the
5362 <filename>directdisk-gpt.wks</filename> file in the 5339 <filename>directdisk-gpt.wks</filename> file in the
5363 <filename>scripts/lib/image/canned-wks</filename> 5340 <filename>scripts/lib/image/canned-wks</filename>
5364 directory and then by changing the lines that specify 5341 directory and then by changing the lines that specify
5365 the target disk from which to boot. 5342 the target disk from which to boot.
5366 <literallayout class='monospaced'> 5343 <literallayout class='monospaced'>
5367 $ cp /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \ 5344 $ cp /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \
5368 /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks 5345 /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
5369 </literallayout> 5346 </literallayout>
5370 Next, the example modifies the 5347 Next, the example modifies the
5371 <filename>directdisksdb-gpt.wks</filename> file and 5348 <filename>directdisksdb-gpt.wks</filename> file and
5372 changes all instances of 5349 changes all instances of
5373 "<filename>--ondisk sda</filename>" to 5350 "<filename>--ondisk sda</filename>" to
5374 "<filename>--ondisk sdb</filename>". 5351 "<filename>--ondisk sdb</filename>".
5375 The example changes the following two lines and leaves 5352 The example changes the following two lines and leaves
5376 the remaining lines untouched: 5353 the remaining lines untouched:
5377 <literallayout class='monospaced'> 5354 <literallayout class='monospaced'>
5378 part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024 5355 part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024
5379 part / --source rootfs --ondisk sdb --fstype=ext4 --label platform --align 1024 --use-uuid 5356 part / --source rootfs --ondisk sdb --fstype=ext4 --label platform --align 1024 --use-uuid
5380 </literallayout> 5357 </literallayout>
5381 Once the lines are changed, the example generates the 5358 Once the lines are changed, the example generates the
5382 <filename>directdisksdb-gpt</filename> image. 5359 <filename>directdisksdb-gpt</filename> image.
5383 The command points the process at the 5360 The command points the process at the
5384 <filename>core-image-minimal</filename> artifacts for 5361 <filename>core-image-minimal</filename> artifacts for
5385 the Next Unit of Computing (nuc) 5362 the Next Unit of Computing (nuc)
5386 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> 5363 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
5387 the <filename>local.conf</filename>. 5364 the <filename>local.conf</filename>.
5388 <literallayout class='monospaced'> 5365 <literallayout class='monospaced'>
5389 $ wic create directdisksdb-gpt -e core-image-minimal 5366 $ wic create directdisksdb-gpt -e core-image-minimal
5390 INFO: Building wic-tools... 5367 INFO: Building wic-tools...
5391 . 5368 .
@@ -5408,32 +5385,32 @@
5408 5385
5409 INFO: The image(s) were created using OE kickstart file: 5386 INFO: The image(s) were created using OE kickstart file:
5410 /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks 5387 /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
5411 </literallayout> 5388 </literallayout>
5412 Continuing with the example, you can now directly 5389 Continuing with the example, you can now directly
5413 <filename>dd</filename> the image to a USB stick, or 5390 <filename>dd</filename> the image to a USB stick, or
5414 whatever media for which you built your image, 5391 whatever media for which you built your image,
5415 and boot the resulting media: 5392 and boot the resulting media:
5416 <literallayout class='monospaced'> 5393 <literallayout class='monospaced'>
5417 $ sudo dd if=directdisksdb-gpt-201710090938-sdb.direct of=/dev/sdb 5394 $ sudo dd if=directdisksdb-gpt-201710090938-sdb.direct of=/dev/sdb
5418 140966+0 records in 5395 140966+0 records in
5419 140966+0 records out 5396 140966+0 records out
5420 72174592 bytes (72 MB, 69 MiB) copied, 78.0282 s, 925 kB/s 5397 72174592 bytes (72 MB, 69 MiB) copied, 78.0282 s, 925 kB/s
5421 $ sudo eject /dev/sdb 5398 $ sudo eject /dev/sdb
5422 </literallayout> 5399 </literallayout>
5423 </para> 5400 </para>
5424 </section> 5401 </section>
5425 5402
5426 <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'> 5403 <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'>
5427 <title>Using a Modified Kickstart File and Running in Raw Mode</title> 5404 <title>Using a Modified Kickstart File and Running in Raw Mode</title>
5428 5405
5429 <para> 5406 <para>
5430 This next example manually specifies each build artifact 5407 This next example manually specifies each build artifact
5431 (runs in Raw Mode) and uses a modified kickstart file. 5408 (runs in Raw Mode) and uses a modified kickstart file.
5432 The example also uses the <filename>-o</filename> option 5409 The example also uses the <filename>-o</filename> option
5433 to cause Wic to create the output 5410 to cause Wic to create the output
5434 somewhere other than the default output directory, 5411 somewhere other than the default output directory,
5435 which is the current directory: 5412 which is the current directory:
5436 <literallayout class='monospaced'> 5413 <literallayout class='monospaced'>
5437 $ wic create /home/scottrif/my_yocto/test.wks -o /home/scottrif/testwic \ 5414 $ wic create /home/scottrif/my_yocto/test.wks -o /home/scottrif/testwic \
5438 --rootfs-dir /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \ 5415 --rootfs-dir /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \
5439 --bootimg-dir /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \ 5416 --bootimg-dir /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \
@@ -5453,219 +5430,15 @@
5453 5430
5454 INFO: The image(s) were created using OE kickstart file: 5431 INFO: The image(s) were created using OE kickstart file:
5455 /home/scottrif/my_yocto/test.wks 5432 /home/scottrif/my_yocto/test.wks
5456 </literallayout>
5457 For this example,
5458 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
5459 did not have to be specified in the
5460 <filename>local.conf</filename> file since the
5461 artifact is manually specified.
5462 </para>
5463 </section>
5464 </section>
5465
5466 <section id='openembedded-kickstart-plugins'>
5467 <title>Plug-ins</title>
5468
5469 <para>
5470 You can extend and specialize Wic functionality by using
5471 Wic plug-ins.
5472 This section explains the Wic plug-in interface.
5473 <note>
5474 Wic plug-ins consist of "source" and "imager" plug-ins.
5475 Imager plug-ins are beyond the scope of this section.
5476 </note>
5477 </para>
5478
5479 <para>
5480 Source plug-ins provide a mechanism to customize partition
5481 content during the Wic image generation process.
5482 You can use source plug-ins to map values that you specify
5483 using <filename>--source</filename> commands in kickstart
5484 files (i.e. <filename>*.wks</filename>) to a plug-in
5485 implementation used to populate a given partition.
5486 <note>
5487 If you use plug-ins that have build-time dependencies
5488 (e.g. native tools, bootloaders, and so forth)
5489 when building a Wic image, you need to specify those
5490 dependencies using the
5491 <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE_DEPENDS'><filename>WKS_FILE_DEPENDS</filename></ulink>
5492 variable.
5493 </note>
5494 </para>
5495
5496 <para>
5497 Source plug-ins are subclasses defined in plug-in files.
5498 As shipped, the Yocto Project provides several plug-in
5499 files.
5500 You can see the source plug-in files that ship with the
5501 Yocto Project
5502 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/scripts/lib/wic/plugins/source'>here</ulink>.
5503 Each of these plug-in files contain source plug-ins that
5504 are designed to populate a specific Wic image partition.
5505 </para>
5506
5507 <para>
5508 Source plug-ins are subclasses of the
5509 <filename>SourcePlugin</filename> class, which is
5510 defined in the
5511 <filename>poky/scripts/lib/wic/pluginbase.py</filename>
5512 file.
5513 For example, the <filename>BootimgEFIPlugin</filename>
5514 source plug-in found in the
5515 <filename>bootimg-efi.py</filename> file is a subclass of
5516 the <filename>SourcePlugin</filename> class, which is found
5517 in the <filename>pluginbase.py</filename> file.
5518 </para>
5519
5520 <para>
5521 You can also implement source plug-ins in a layer outside
5522 of the Source Repositories (external layer).
5523 To do so, be sure that your plug-in files are located in
5524 a directory whose path is
5525 <filename>scripts/lib/wic/plugins/source/</filename>
5526 within your external layer.
5527 When the plug-in files are located there, the source
5528 plug-ins they contain are made available to Wic.
5529 </para>
5530
5531 <para>
5532 When the Wic implementation needs to invoke a
5533 partition-specific implementation, it looks for the plug-in
5534 with the same name as the <filename>--source</filename>
5535 parameter used in the kickstart file given to that
5536 partition.
5537 For example, if the partition is set up using the following
5538 command in a kickstart file:
5539 <literallayout class='monospaced'>
5540 part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
5541 </literallayout>
5542 The methods defined as class members of the matching
5543 source plug-in (i.e. <filename>bootimg-pcbios</filename>)
5544 in the <filename>bootimg-pcbios.py</filename> plug-in file
5545 are used.
5546 </para>
5547
5548 <para>
5549 To be more concrete, here is the corresponding plug-in
5550 definition from the <filename>bootimg-pcbios.py</filename>
5551 file for the previous command along with an example
5552 method called by the Wic implementation when it needs to
5553 prepare a partition using an implementation-specific
5554 function:
5555 <literallayout class='monospaced'>
5556 bootimg-pcbios.py
5557 .
5558 .
5559 .
5560 class BootimgPcbiosPlugin(SourcePlugin):
5561 """
5562 Create MBR boot partition and install syslinux on it.
5563 """
5564
5565 name = 'bootimg-pcbios'
5566 .
5567 .
5568 .
5569 @classmethod
5570 def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
5571 oe_builddir, bootimg_dir, kernel_dir,
5572 rootfs_dir, native_sysroot):
5573 """
5574 Called to do the actual content population for a partition i.e. it
5575 'prepares' the partition to be incorporated into the image.
5576 In this case, prepare content for legacy bios boot partition.
5577 """
5578 .
5579 .
5580 .
5581 </literallayout> 5433 </literallayout>
5582 If a subclass (plug-in) itself does not implement a 5434 For this example,
5583 particular function, Wic locates and uses the default 5435 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
5584 version in the superclass. 5436 did not have to be specified in the
5585 It is for this reason that all source plug-ins are derived 5437 <filename>local.conf</filename> file since the
5586 from the <filename>SourcePlugin</filename> class. 5438 artifact is manually specified.
5587 </para>
5588
5589 <para>
5590 The <filename>SourcePlugin</filename> class defined in
5591 the <filename>pluginbase.py</filename> file defines
5592 a set of methods that source plug-ins can implement or
5593 override.
5594 Any plug-ins (subclass of
5595 <filename>SourcePlugin</filename>) that do not implement
5596 a particular method inherit the implementation of the
5597 method from the <filename>SourcePlugin</filename> class.
5598 For more information, see the
5599 <filename>SourcePlugin</filename> class in the
5600 <filename>pluginbase.py</filename> file for details:
5601 </para>
5602
5603 <para>
5604 The following list describes the methods implemented in the
5605 <filename>SourcePlugin</filename> class:
5606 <itemizedlist>
5607 <listitem><para>
5608 <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
5609 Called to populate a partition with actual content.
5610 In other words, the method prepares the final
5611 partition image that is incorporated into the
5612 disk image.
5613 </para></listitem>
5614 <listitem><para>
5615 <emphasis><filename>do_configure_partition()</filename>:</emphasis>
5616 Called before
5617 <filename>do_prepare_partition()</filename> to
5618 create custom configuration files for a partition
5619 (e.g. syslinux or grub configuration files).
5620 </para></listitem>
5621 <listitem><para>
5622 <emphasis><filename>do_install_disk()</filename>:</emphasis>
5623 Called after all partitions have been prepared and
5624 assembled into a disk image.
5625 This method provides a hook to allow finalization
5626 of a disk image (e.g. writing an MBR).
5627 </para></listitem>
5628 <listitem><para>
5629 <emphasis><filename>do_stage_partition()</filename>:</emphasis>
5630 Special content-staging hook called before
5631 <filename>do_prepare_partition()</filename>.
5632 This method is normally empty.</para>
5633
5634 <para>Typically, a partition just uses the passed-in
5635 parameters (e.g. the unmodified value of
5636 <filename>bootimg_dir</filename>).
5637 However, in some cases, things might need to be
5638 more tailored.
5639 As an example, certain files might additionally
5640 need to be taken from
5641 <filename>bootimg_dir + /boot</filename>.
5642 This hook allows those files to be staged in a
5643 customized fashion.
5644 <note>
5645 <filename>get_bitbake_var()</filename>
5646 allows you to access non-standard variables
5647 that you might want to use for this
5648 behavior.
5649 </note>
5650 </para></listitem>
5651 </itemizedlist>
5652 </para>
5653
5654 <para>
5655 You can extend the source plug-in mechanism.
5656 To add more hooks, create more source plug-in methods
5657 within <filename>SourcePlugin</filename> and the
5658 corresponding derived subclasses.
5659 The code that calls the plug-in methods uses the
5660 <filename>plugin.get_source_plugin_methods()</filename>
5661 function to find the method or methods needed by the call.
5662 Retrieval of those methods is accomplished by filling up
5663 a dict with keys that contain the method names of interest.
5664 On success, these will be filled in with the actual
5665 methods.
5666 See the Wic implementation for examples and details.
5667 </para> 5439 </para>
5668 </section> 5440 </section>
5441 </section>
5669 5442
5670 <section id='openembedded-kickstart-wks-reference'> 5443 <section id='openembedded-kickstart-wks-reference'>
5671 <title>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</title> 5444 <title>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</title>
@@ -5773,8 +5546,10 @@
5773 "rootfs", but you can use any value that maps to 5546 "rootfs", but you can use any value that maps to
5774 a valid source plug-in. 5547 a valid source plug-in.
5775 For information on the source plug-ins, see the 5548 For information on the source plug-ins, see the
5776 "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>" 5549 "<ulink url='&YOCTO_DOCS_REF_URL;#wic-plug-ins-interface'>Wic Plug-Ins Interface</ulink>"
5777 section.</para> 5550 section in the Yocto Project Reference
5551 manual.</para>
5552
5778 <para>If you use 5553 <para>If you use
5779 <filename>--source rootfs</filename>, 5554 <filename>--source rootfs</filename>,
5780 Wic creates a partition as 5555 Wic creates a partition as
@@ -5792,6 +5567,7 @@
5792 <filename>--fstype</filename> that 5567 <filename>--fstype</filename> that
5793 follows for more information. 5568 follows for more information.
5794 </para> 5569 </para>
5570
5795 <para>If you use 5571 <para>If you use
5796 <filename>--source <replaceable>plugin-name</replaceable></filename>, 5572 <filename>--source <replaceable>plugin-name</replaceable></filename>,
5797 Wic creates a partition as 5573 Wic creates a partition as
@@ -5806,6 +5582,7 @@
5806 end up being are dependent on the given plug-in 5582 end up being are dependent on the given plug-in
5807 implementation. 5583 implementation.
5808 </para> 5584 </para>
5585
5809 <para>If you do not use the 5586 <para>If you do not use the
5810 <filename>--source</filename> option, the 5587 <filename>--source</filename> option, the
5811 <filename>wic</filename> command creates an 5588 <filename>wic</filename> command creates an
@@ -5824,18 +5601,24 @@
5824 Sets the file system type for the partition. 5601 Sets the file system type for the partition.
5825 Valid values are: 5602 Valid values are:
5826 <itemizedlist> 5603 <itemizedlist>
5827 <listitem><para><filename>ext4</filename> 5604 <listitem><para>
5828 </para></listitem> 5605 <filename>ext4</filename>
5829 <listitem><para><filename>ext3</filename> 5606 </para></listitem>
5830 </para></listitem> 5607 <listitem><para>
5831 <listitem><para><filename>ext2</filename> 5608 <filename>ext3</filename>
5832 </para></listitem> 5609 </para></listitem>
5833 <listitem><para><filename>btrfs</filename> 5610 <listitem><para>
5834 </para></listitem> 5611 <filename>ext2</filename>
5835 <listitem><para><filename>squashfs</filename> 5612 </para></listitem>
5836 </para></listitem> 5613 <listitem><para>
5837 <listitem><para><filename>swap</filename> 5614 <filename>btrfs</filename>
5838 </para></listitem> 5615 </para></listitem>
5616 <listitem><para>
5617 <filename>squashfs</filename>
5618 </para></listitem>
5619 <listitem><para>
5620 <filename>swap</filename>
5621 </para></listitem>
5839 </itemizedlist> 5622 </itemizedlist>
5840 </para></listitem> 5623 </para></listitem>
5841 <listitem><para> 5624 <listitem><para>
@@ -5969,7 +5752,6 @@
5969 </para> 5752 </para>
5970 </section> 5753 </section>
5971 </section> 5754 </section>
5972 </section>
5973 </section> 5755 </section>
5974 5756
5975 <section id='building-an-initramfs-image'> 5757 <section id='building-an-initramfs-image'>
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 @@
1252 </para> 1252 </para>
1253</section> 1253</section>
1254 1254
1255<section id='wic-plug-ins-interface'>
1256 <title>Wic Plug-Ins Interface</title>
1257
1258 <para>
1259 You can extend and specialize Wic functionality by using
1260 Wic plug-ins.
1261 This section explains the Wic plug-in interface.
1262 For information on using Wic in general, see the
1263 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images'>Creating Partitioned Images</ulink>"
1264 section in the Yocto Project Development Manual.
1265 <note>
1266 Wic plug-ins consist of "source" and "imager" plug-ins.
1267 Imager plug-ins are beyond the scope of this section.
1268 </note>
1269 </para>
1270
1271 <para>
1272 Source plug-ins provide a mechanism to customize partition
1273 content during the Wic image generation process.
1274 You can use source plug-ins to map values that you specify
1275 using <filename>--source</filename> commands in kickstart
1276 files (i.e. <filename>*.wks</filename>) to a plug-in
1277 implementation used to populate a given partition.
1278 <note>
1279 If you use plug-ins that have build-time dependencies
1280 (e.g. native tools, bootloaders, and so forth)
1281 when building a Wic image, you need to specify those
1282 dependencies using the
1283 <link linkend='var-WKS_FILE_DEPENDS'><filename>WKS_FILE_DEPENDS</filename></link>
1284 variable.
1285 </note>
1286 </para>
1287
1288 <para>
1289 Source plug-ins are subclasses defined in plug-in files.
1290 As shipped, the Yocto Project provides several plug-in
1291 files.
1292 You can see the source plug-in files that ship with the
1293 Yocto Project
1294 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/scripts/lib/wic/plugins/source'>here</ulink>.
1295 Each of these plug-in files contain source plug-ins that
1296 are designed to populate a specific Wic image partition.
1297 </para>
1298
1299 <para>
1300 Source plug-ins are subclasses of the
1301 <filename>SourcePlugin</filename> class, which is
1302 defined in the
1303 <filename>poky/scripts/lib/wic/pluginbase.py</filename>
1304 file.
1305 For example, the <filename>BootimgEFIPlugin</filename>
1306 source plug-in found in the
1307 <filename>bootimg-efi.py</filename> file is a subclass of
1308 the <filename>SourcePlugin</filename> class, which is found
1309 in the <filename>pluginbase.py</filename> file.
1310 </para>
1311
1312 <para>
1313 You can also implement source plug-ins in a layer outside
1314 of the Source Repositories (external layer).
1315 To do so, be sure that your plug-in files are located in
1316 a directory whose path is
1317 <filename>scripts/lib/wic/plugins/source/</filename>
1318 within your external layer.
1319 When the plug-in files are located there, the source
1320 plug-ins they contain are made available to Wic.
1321 </para>
1322
1323 <para>
1324 When the Wic implementation needs to invoke a
1325 partition-specific implementation, it looks for the plug-in
1326 with the same name as the <filename>--source</filename>
1327 parameter used in the kickstart file given to that
1328 partition.
1329 For example, if the partition is set up using the following
1330 command in a kickstart file:
1331 <literallayout class='monospaced'>
1332 part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
1333 </literallayout>
1334 The methods defined as class members of the matching
1335 source plug-in (i.e. <filename>bootimg-pcbios</filename>)
1336 in the <filename>bootimg-pcbios.py</filename> plug-in file
1337 are used.
1338 </para>
1339
1340 <para>
1341 To be more concrete, here is the corresponding plug-in
1342 definition from the <filename>bootimg-pcbios.py</filename>
1343 file for the previous command along with an example
1344 method called by the Wic implementation when it needs to
1345 prepare a partition using an implementation-specific
1346 function:
1347 <literallayout class='monospaced'>
1348 bootimg-pcbios.py
1349 .
1350 .
1351 .
1352 class BootimgPcbiosPlugin(SourcePlugin):
1353 """
1354 Create MBR boot partition and install syslinux on it.
1355 """
1356
1357 name = 'bootimg-pcbios'
1358 .
1359 .
1360 .
1361 @classmethod
1362 def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
1363 oe_builddir, bootimg_dir, kernel_dir,
1364 rootfs_dir, native_sysroot):
1365 """
1366 Called to do the actual content population for a partition i.e. it
1367 'prepares' the partition to be incorporated into the image.
1368 In this case, prepare content for legacy bios boot partition.
1369 """
1370 .
1371 .
1372 .
1373 </literallayout>
1374 If a subclass (plug-in) itself does not implement a
1375 particular function, Wic locates and uses the default
1376 version in the superclass.
1377 It is for this reason that all source plug-ins are derived
1378 from the <filename>SourcePlugin</filename> class.
1379 </para>
1380
1381 <para>
1382 The <filename>SourcePlugin</filename> class defined in
1383 the <filename>pluginbase.py</filename> file defines
1384 a set of methods that source plug-ins can implement or
1385 override.
1386 Any plug-ins (subclass of
1387 <filename>SourcePlugin</filename>) that do not implement
1388 a particular method inherit the implementation of the
1389 method from the <filename>SourcePlugin</filename> class.
1390 For more information, see the
1391 <filename>SourcePlugin</filename> class in the
1392 <filename>pluginbase.py</filename> file for details:
1393 </para>
1394
1395 <para>
1396 The following list describes the methods implemented in the
1397 <filename>SourcePlugin</filename> class:
1398 <itemizedlist>
1399 <listitem><para>
1400 <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
1401 Called to populate a partition with actual content.
1402 In other words, the method prepares the final
1403 partition image that is incorporated into the
1404 disk image.
1405 </para></listitem>
1406 <listitem><para>
1407 <emphasis><filename>do_configure_partition()</filename>:</emphasis>
1408 Called before
1409 <filename>do_prepare_partition()</filename> to
1410 create custom configuration files for a partition
1411 (e.g. syslinux or grub configuration files).
1412 </para></listitem>
1413 <listitem><para>
1414 <emphasis><filename>do_install_disk()</filename>:</emphasis>
1415 Called after all partitions have been prepared and
1416 assembled into a disk image.
1417 This method provides a hook to allow finalization
1418 of a disk image (e.g. writing an MBR).
1419 </para></listitem>
1420 <listitem><para>
1421 <emphasis><filename>do_stage_partition()</filename>:</emphasis>
1422 Special content-staging hook called before
1423 <filename>do_prepare_partition()</filename>.
1424 This method is normally empty.</para>
1425
1426 <para>Typically, a partition just uses the passed-in
1427 parameters (e.g. the unmodified value of
1428 <filename>bootimg_dir</filename>).
1429 However, in some cases, things might need to be
1430 more tailored.
1431 As an example, certain files might additionally
1432 need to be taken from
1433 <filename>bootimg_dir + /boot</filename>.
1434 This hook allows those files to be staged in a
1435 customized fashion.
1436 <note>
1437 <filename>get_bitbake_var()</filename>
1438 allows you to access non-standard variables
1439 that you might want to use for this
1440 behavior.
1441 </note>
1442 </para></listitem>
1443 </itemizedlist>
1444 </para>
1445
1446 <para>
1447 You can extend the source plug-in mechanism.
1448 To add more hooks, create more source plug-in methods
1449 within <filename>SourcePlugin</filename> and the
1450 corresponding derived subclasses.
1451 The code that calls the plug-in methods uses the
1452 <filename>plugin.get_source_plugin_methods()</filename>
1453 function to find the method or methods needed by the call.
1454 Retrieval of those methods is accomplished by filling up
1455 a dict with keys that contain the method names of interest.
1456 On success, these will be filled in with the actual
1457 methods.
1458 See the Wic implementation for examples and details.
1459 </para>
1460</section>
1461
1255<section id='x32'> 1462<section id='x32'>
1256 <title>x32</title> 1463 <title>x32</title>
1257 1464
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-23 08:05:13 +0000