summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml213
-rw-r--r--documentation/ref-manual/ref-kickstart.xml5
-rw-r--r--documentation/ref-manual/technical-details.xml207
3 files changed, 212 insertions, 213 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 @@
4878 customized images, and as such, was designed to be 4878 customized images, and as such, was designed to be
4879 completely extensible through a plug-in interface. 4879 completely extensible through a plug-in interface.
4880 See the 4880 See the
4881 "<ulink url='&YOCTO_DOCS_REF_URL;#wic-plug-ins-interface'>Wic Plug-Ins Interface</ulink>" 4881 "<link linkend='wic-using-the-wic-plug-ins-interface'>Using the Wic Plug-Ins Interface</link>"
4882 section in the Yocto Project Reference Manual for information 4882 section for information on these plug-ins.
4883 on these plug-ins.
4884 </para> 4883 </para>
4885 4884
4886 <para> 4885 <para>
4887 This section provides some background information on Wic, 4886 This section provides some background information on Wic,
4888 describes what you need to have in 4887 describes what you need to have in
4889 place to run the tool, provides instruction on how to use 4888 place to run the tool, provides instruction on how to use
4890 the Wic utility, and provides several examples. 4889 the Wic utility, provides information on using the Wic plug-ins
4890 interface, and provides several examples that show how to use
4891 Wic.
4891 </para> 4892 </para>
4892 4893
4893 <section id='wic-background'> 4894 <section id='wic-background'>
@@ -5265,6 +5266,210 @@
5265 </para> 5266 </para>
5266 </section> 5267 </section>
5267 5268
5269 <section id='wic-using-the-wic-plug-ins-interface'>
5270 <title>Using the Wic Plug-Ins Interface</title>
5271
5272 <para>
5273 You can extend and specialize Wic functionality by using
5274 Wic plug-ins.
5275 This section explains the Wic plug-in interface.
5276 <note>
5277 Wic plug-ins consist of "source" and "imager" plug-ins.
5278 Imager plug-ins are beyond the scope of this section.
5279 </note>
5280 </para>
5281
5282 <para>
5283 Source plug-ins provide a mechanism to customize partition
5284 content during the Wic image generation process.
5285 You can use source plug-ins to map values that you specify
5286 using <filename>--source</filename> commands in kickstart
5287 files (i.e. <filename>*.wks</filename>) to a plug-in
5288 implementation used to populate a given partition.
5289 <note>
5290 If you use plug-ins that have build-time dependencies
5291 (e.g. native tools, bootloaders, and so forth)
5292 when building a Wic image, you need to specify those
5293 dependencies using the
5294 <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE_DEPENDS'><filename>WKS_FILE_DEPENDS</filename></ulink>
5295 variable.
5296 </note>
5297 </para>
5298
5299 <para>
5300 Source plug-ins are subclasses defined in plug-in files.
5301 As shipped, the Yocto Project provides several plug-in
5302 files.
5303 You can see the source plug-in files that ship with the
5304 Yocto Project
5305 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/scripts/lib/wic/plugins/source'>here</ulink>.
5306 Each of these plug-in files contains source plug-ins that
5307 are designed to populate a specific Wic image partition.
5308 </para>
5309
5310 <para>
5311 Source plug-ins are subclasses of the
5312 <filename>SourcePlugin</filename> class, which is
5313 defined in the
5314 <filename>poky/scripts/lib/wic/pluginbase.py</filename>
5315 file.
5316 For example, the <filename>BootimgEFIPlugin</filename>
5317 source plug-in found in the
5318 <filename>bootimg-efi.py</filename> file is a subclass of
5319 the <filename>SourcePlugin</filename> class, which is found
5320 in the <filename>pluginbase.py</filename> file.
5321 </para>
5322
5323 <para>
5324 You can also implement source plug-ins in a layer outside
5325 of the Source Repositories (external layer).
5326 To do so, be sure that your plug-in files are located in
5327 a directory whose path is
5328 <filename>scripts/lib/wic/plugins/source/</filename>
5329 within your external layer.
5330 When the plug-in files are located there, the source
5331 plug-ins they contain are made available to Wic.
5332 </para>
5333
5334 <para>
5335 When the Wic implementation needs to invoke a
5336 partition-specific implementation, it looks for the plug-in
5337 with the same name as the <filename>--source</filename>
5338 parameter used in the kickstart file given to that
5339 partition.
5340 For example, if the partition is set up using the following
5341 command in a kickstart file:
5342 <literallayout class='monospaced'>
5343 part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
5344 </literallayout>
5345 The methods defined as class members of the matching
5346 source plug-in (i.e. <filename>bootimg-pcbios</filename>)
5347 in the <filename>bootimg-pcbios.py</filename> plug-in file
5348 are used.
5349 </para>
5350
5351 <para>
5352 To be more concrete, here is the corresponding plug-in
5353 definition from the <filename>bootimg-pcbios.py</filename>
5354 file for the previous command along with an example
5355 method called by the Wic implementation when it needs to
5356 prepare a partition using an implementation-specific
5357 function:
5358 <literallayout class='monospaced'>
5359 bootimg-pcbios.py
5360 .
5361 .
5362 .
5363 class BootimgPcbiosPlugin(SourcePlugin):
5364 """
5365 Create MBR boot partition and install syslinux on it.
5366 """
5367
5368 name = 'bootimg-pcbios'
5369 .
5370 .
5371 .
5372 @classmethod
5373 def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
5374 oe_builddir, bootimg_dir, kernel_dir,
5375 rootfs_dir, native_sysroot):
5376 """
5377 Called to do the actual content population for a partition i.e. it
5378 'prepares' the partition to be incorporated into the image.
5379 In this case, prepare content for legacy bios boot partition.
5380 """
5381 .
5382 .
5383 .
5384 </literallayout>
5385 If a subclass (plug-in) itself does not implement a
5386 particular function, Wic locates and uses the default
5387 version in the superclass.
5388 It is for this reason that all source plug-ins are derived
5389 from the <filename>SourcePlugin</filename> class.
5390 </para>
5391
5392 <para>
5393 The <filename>SourcePlugin</filename> class defined in
5394 the <filename>pluginbase.py</filename> file defines
5395 a set of methods that source plug-ins can implement or
5396 override.
5397 Any plug-ins (subclass of
5398 <filename>SourcePlugin</filename>) that do not implement
5399 a particular method inherit the implementation of the
5400 method from the <filename>SourcePlugin</filename> class.
5401 For more information, see the
5402 <filename>SourcePlugin</filename> class in the
5403 <filename>pluginbase.py</filename> file for details:
5404 </para>
5405
5406 <para>
5407 The following list describes the methods implemented in the
5408 <filename>SourcePlugin</filename> class:
5409 <itemizedlist>
5410 <listitem><para>
5411 <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
5412 Called to populate a partition with actual content.
5413 In other words, the method prepares the final
5414 partition image that is incorporated into the
5415 disk image.
5416 </para></listitem>
5417 <listitem><para>
5418 <emphasis><filename>do_configure_partition()</filename>:</emphasis>
5419 Called before
5420 <filename>do_prepare_partition()</filename> to
5421 create custom configuration files for a partition
5422 (e.g. syslinux or grub configuration files).
5423 </para></listitem>
5424 <listitem><para>
5425 <emphasis><filename>do_install_disk()</filename>:</emphasis>
5426 Called after all partitions have been prepared and
5427 assembled into a disk image.
5428 This method provides a hook to allow finalization
5429 of a disk image (e.g. writing an MBR).
5430 </para></listitem>
5431 <listitem><para>
5432 <emphasis><filename>do_stage_partition()</filename>:</emphasis>
5433 Special content-staging hook called before
5434 <filename>do_prepare_partition()</filename>.
5435 This method is normally empty.</para>
5436
5437 <para>Typically, a partition just uses the passed-in
5438 parameters (e.g. the unmodified value of
5439 <filename>bootimg_dir</filename>).
5440 However, in some cases, things might need to be
5441 more tailored.
5442 As an example, certain files might additionally
5443 need to be taken from
5444 <filename>bootimg_dir + /boot</filename>.
5445 This hook allows those files to be staged in a
5446 customized fashion.
5447 <note>
5448 <filename>get_bitbake_var()</filename>
5449 allows you to access non-standard variables
5450 that you might want to use for this
5451 behavior.
5452 </note>
5453 </para></listitem>
5454 </itemizedlist>
5455 </para>
5456
5457 <para>
5458 You can extend the source plug-in mechanism.
5459 To add more hooks, create more source plug-in methods
5460 within <filename>SourcePlugin</filename> and the
5461 corresponding derived subclasses.
5462 The code that calls the plug-in methods uses the
5463 <filename>plugin.get_source_plugin_methods()</filename>
5464 function to find the method or methods needed by the call.
5465 Retrieval of those methods is accomplished by filling up
5466 a dict with keys that contain the method names of interest.
5467 On success, these will be filled in with the actual
5468 methods.
5469 See the Wic implementation for examples and details.
5470 </para>
5471 </section>
5472
5268 <section id='wic-usage-examples'> 5473 <section id='wic-usage-examples'>
5269 <title>Examples</title> 5474 <title>Examples</title>
5270 5475
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 @@
107 The most common value for this option is "rootfs", but you 107 The most common value for this option is "rootfs", but you
108 can use any value that maps to a valid source plug-in. 108 can use any value that maps to a valid source plug-in.
109 For information on the source plug-ins, see the 109 For information on the source plug-ins, see the
110 "<link linkend='wic-plug-ins-interface'>Wic Plug-Ins Interface</link>" 110 "<ulink url='&YOCTO_DOCS_DEV_URL;#wic-using-the-wic-plug-ins-interface'>Using the Wic Plug-Ins Interface</ulink>"
111 section.</para> 111 section in the Yocto Project Development Tasks Manual.
112 </para>
112 113
113 <para>If you use <filename>--source rootfs</filename>, Wic 114 <para>If you use <filename>--source rootfs</filename>, Wic
114 creates a partition as large as needed and to fill it with 115 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 @@
1255 </para> 1255 </para>
1256</section> 1256</section>
1257 1257
1258<section id='wic-plug-ins-interface'>
1259 <title>Wic Plug-Ins Interface</title>
1260
1261 <para>
1262 You can extend and specialize Wic functionality by using
1263 Wic plug-ins.
1264 This section explains the Wic plug-in interface.
1265 For information on using Wic in general, see the
1266 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
1267 section in the Yocto Project Development Tasks Manual.
1268 <note>
1269 Wic plug-ins consist of "source" and "imager" plug-ins.
1270 Imager plug-ins are beyond the scope of this section.
1271 </note>
1272 </para>
1273
1274 <para>
1275 Source plug-ins provide a mechanism to customize partition
1276 content during the Wic image generation process.
1277 You can use source plug-ins to map values that you specify
1278 using <filename>--source</filename> commands in kickstart
1279 files (i.e. <filename>*.wks</filename>) to a plug-in
1280 implementation used to populate a given partition.
1281 <note>
1282 If you use plug-ins that have build-time dependencies
1283 (e.g. native tools, bootloaders, and so forth)
1284 when building a Wic image, you need to specify those
1285 dependencies using the
1286 <link linkend='var-WKS_FILE_DEPENDS'><filename>WKS_FILE_DEPENDS</filename></link>
1287 variable.
1288 </note>
1289 </para>
1290
1291 <para>
1292 Source plug-ins are subclasses defined in plug-in files.
1293 As shipped, the Yocto Project provides several plug-in
1294 files.
1295 You can see the source plug-in files that ship with the
1296 Yocto Project
1297 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/scripts/lib/wic/plugins/source'>here</ulink>.
1298 Each of these plug-in files contain source plug-ins that
1299 are designed to populate a specific Wic image partition.
1300 </para>
1301
1302 <para>
1303 Source plug-ins are subclasses of the
1304 <filename>SourcePlugin</filename> class, which is
1305 defined in the
1306 <filename>poky/scripts/lib/wic/pluginbase.py</filename>
1307 file.
1308 For example, the <filename>BootimgEFIPlugin</filename>
1309 source plug-in found in the
1310 <filename>bootimg-efi.py</filename> file is a subclass of
1311 the <filename>SourcePlugin</filename> class, which is found
1312 in the <filename>pluginbase.py</filename> file.
1313 </para>
1314
1315 <para>
1316 You can also implement source plug-ins in a layer outside
1317 of the Source Repositories (external layer).
1318 To do so, be sure that your plug-in files are located in
1319 a directory whose path is
1320 <filename>scripts/lib/wic/plugins/source/</filename>
1321 within your external layer.
1322 When the plug-in files are located there, the source
1323 plug-ins they contain are made available to Wic.
1324 </para>
1325
1326 <para>
1327 When the Wic implementation needs to invoke a
1328 partition-specific implementation, it looks for the plug-in
1329 with the same name as the <filename>--source</filename>
1330 parameter used in the kickstart file given to that
1331 partition.
1332 For example, if the partition is set up using the following
1333 command in a kickstart file:
1334 <literallayout class='monospaced'>
1335 part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
1336 </literallayout>
1337 The methods defined as class members of the matching
1338 source plug-in (i.e. <filename>bootimg-pcbios</filename>)
1339 in the <filename>bootimg-pcbios.py</filename> plug-in file
1340 are used.
1341 </para>
1342
1343 <para>
1344 To be more concrete, here is the corresponding plug-in
1345 definition from the <filename>bootimg-pcbios.py</filename>
1346 file for the previous command along with an example
1347 method called by the Wic implementation when it needs to
1348 prepare a partition using an implementation-specific
1349 function:
1350 <literallayout class='monospaced'>
1351 bootimg-pcbios.py
1352 .
1353 .
1354 .
1355 class BootimgPcbiosPlugin(SourcePlugin):
1356 """
1357 Create MBR boot partition and install syslinux on it.
1358 """
1359
1360 name = 'bootimg-pcbios'
1361 .
1362 .
1363 .
1364 @classmethod
1365 def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
1366 oe_builddir, bootimg_dir, kernel_dir,
1367 rootfs_dir, native_sysroot):
1368 """
1369 Called to do the actual content population for a partition i.e. it
1370 'prepares' the partition to be incorporated into the image.
1371 In this case, prepare content for legacy bios boot partition.
1372 """
1373 .
1374 .
1375 .
1376 </literallayout>
1377 If a subclass (plug-in) itself does not implement a
1378 particular function, Wic locates and uses the default
1379 version in the superclass.
1380 It is for this reason that all source plug-ins are derived
1381 from the <filename>SourcePlugin</filename> class.
1382 </para>
1383
1384 <para>
1385 The <filename>SourcePlugin</filename> class defined in
1386 the <filename>pluginbase.py</filename> file defines
1387 a set of methods that source plug-ins can implement or
1388 override.
1389 Any plug-ins (subclass of
1390 <filename>SourcePlugin</filename>) that do not implement
1391 a particular method inherit the implementation of the
1392 method from the <filename>SourcePlugin</filename> class.
1393 For more information, see the
1394 <filename>SourcePlugin</filename> class in the
1395 <filename>pluginbase.py</filename> file for details:
1396 </para>
1397
1398 <para>
1399 The following list describes the methods implemented in the
1400 <filename>SourcePlugin</filename> class:
1401 <itemizedlist>
1402 <listitem><para>
1403 <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
1404 Called to populate a partition with actual content.
1405 In other words, the method prepares the final
1406 partition image that is incorporated into the
1407 disk image.
1408 </para></listitem>
1409 <listitem><para>
1410 <emphasis><filename>do_configure_partition()</filename>:</emphasis>
1411 Called before
1412 <filename>do_prepare_partition()</filename> to
1413 create custom configuration files for a partition
1414 (e.g. syslinux or grub configuration files).
1415 </para></listitem>
1416 <listitem><para>
1417 <emphasis><filename>do_install_disk()</filename>:</emphasis>
1418 Called after all partitions have been prepared and
1419 assembled into a disk image.
1420 This method provides a hook to allow finalization
1421 of a disk image (e.g. writing an MBR).
1422 </para></listitem>
1423 <listitem><para>
1424 <emphasis><filename>do_stage_partition()</filename>:</emphasis>
1425 Special content-staging hook called before
1426 <filename>do_prepare_partition()</filename>.
1427 This method is normally empty.</para>
1428
1429 <para>Typically, a partition just uses the passed-in
1430 parameters (e.g. the unmodified value of
1431 <filename>bootimg_dir</filename>).
1432 However, in some cases, things might need to be
1433 more tailored.
1434 As an example, certain files might additionally
1435 need to be taken from
1436 <filename>bootimg_dir + /boot</filename>.
1437 This hook allows those files to be staged in a
1438 customized fashion.
1439 <note>
1440 <filename>get_bitbake_var()</filename>
1441 allows you to access non-standard variables
1442 that you might want to use for this
1443 behavior.
1444 </note>
1445 </para></listitem>
1446 </itemizedlist>
1447 </para>
1448
1449 <para>
1450 You can extend the source plug-in mechanism.
1451 To add more hooks, create more source plug-in methods
1452 within <filename>SourcePlugin</filename> and the
1453 corresponding derived subclasses.
1454 The code that calls the plug-in methods uses the
1455 <filename>plugin.get_source_plugin_methods()</filename>
1456 function to find the method or methods needed by the call.
1457 Retrieval of those methods is accomplished by filling up
1458 a dict with keys that contain the method names of interest.
1459 On success, these will be filled in with the actual
1460 methods.
1461 See the Wic implementation for examples and details.
1462 </para>
1463</section>
1464
1465<section id="wayland"> 1258<section id="wayland">
1466 <title>Wayland</title> 1259 <title>Wayland</title>
1467 1260