summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-01-10 11:36:56 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-02-14 15:25:27 +0000
commit8097a978cef998d82cc1e35e94b090b0c8bb264f (patch)
tree0e725c2d08c6961c1ace67139dbb5ce91429fb06 /documentation/ref-manual
parente2060287db8093b53d2d18a217c0c463eb6b0c86 (diff)
downloadpoky-8097a978cef998d82cc1e35e94b090b0c8bb264f.tar.gz
dev-manual, ref-manual: Moved Wic Plug-In section to dev-manual
Fixes [YOCTO #12370] I had a section on Wick Plug-Ins in the ref-manual in the "technical details" chapter. This section has been combined with the section on using Wic that lives in the dev-manual. This move creates a single section on using Wic to create Wic-partitioned images. The section was moved out of the ref-manual and merged into the dev-manual Wic section. (From yocto-docs rev: 8724049141c9a793312dcf5ff5c3425948d1cbd0) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/ref-kickstart.xml5
-rw-r--r--documentation/ref-manual/technical-details.xml207
2 files changed, 3 insertions, 209 deletions
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