help.py 42 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117
  1. # Copyright (c) 2013, Intel Corporation.
  2. #
  3. # SPDX-License-Identifier: GPL-2.0-only
  4. #
  5. # DESCRIPTION
  6. # This module implements some basic help invocation functions along
  7. # with the bulk of the help topic text for the OE Core Image Tools.
  8. #
  9. # AUTHORS
  10. # Tom Zanussi <tom.zanussi (at] linux.intel.com>
  11. #
  12. import subprocess
  13. import logging
  14. from wic.pluginbase import PluginMgr, PLUGIN_TYPES
  15. logger = logging.getLogger('wic')
  16. def subcommand_error(args):
  17. logger.info("invalid subcommand %s", args[0])
  18. def display_help(subcommand, subcommands):
  19. """
  20. Display help for subcommand.
  21. """
  22. if subcommand not in subcommands:
  23. return False
  24. hlp = subcommands.get(subcommand, subcommand_error)[2]
  25. if callable(hlp):
  26. hlp = hlp()
  27. pager = subprocess.Popen('less', stdin=subprocess.PIPE)
  28. pager.communicate(hlp.encode('utf-8'))
  29. return True
  30. def wic_help(args, usage_str, subcommands):
  31. """
  32. Subcommand help dispatcher.
  33. """
  34. if args.help_topic == None or not display_help(args.help_topic, subcommands):
  35. print(usage_str)
  36. def get_wic_plugins_help():
  37. """
  38. Combine wic_plugins_help with the help for every known
  39. source plugin.
  40. """
  41. result = wic_plugins_help
  42. for plugin_type in PLUGIN_TYPES:
  43. result += '\n\n%s PLUGINS\n\n' % plugin_type.upper()
  44. for name, plugin in PluginMgr.get_plugins(plugin_type).items():
  45. result += "\n %s plugin:\n" % name
  46. if plugin.__doc__:
  47. result += plugin.__doc__
  48. else:
  49. result += "\n %s is missing docstring\n" % plugin
  50. return result
  51. def invoke_subcommand(args, parser, main_command_usage, subcommands):
  52. """
  53. Dispatch to subcommand handler borrowed from combo-layer.
  54. Should use argparse, but has to work in 2.6.
  55. """
  56. if not args.command:
  57. logger.error("No subcommand specified, exiting")
  58. parser.print_help()
  59. return 1
  60. elif args.command == "help":
  61. wic_help(args, main_command_usage, subcommands)
  62. elif args.command not in subcommands:
  63. logger.error("Unsupported subcommand %s, exiting\n", args.command)
  64. parser.print_help()
  65. return 1
  66. else:
  67. subcmd = subcommands.get(args.command, subcommand_error)
  68. usage = subcmd[1]
  69. subcmd[0](args, usage)
  70. ##
  71. # wic help and usage strings
  72. ##
  73. wic_usage = """
  74. Create a customized OpenEmbedded image
  75. usage: wic [--version] | [--help] | [COMMAND [ARGS]]
  76. Current 'wic' commands are:
  77. help Show help for command or one of the topics (see below)
  78. create Create a new OpenEmbedded image
  79. list List available canned images and source plugins
  80. Help topics:
  81. overview wic overview - General overview of wic
  82. plugins wic plugins - Overview and API
  83. kickstart wic kickstart - wic kickstart reference
  84. """
  85. wic_help_usage = """
  86. usage: wic help <subcommand>
  87. This command displays detailed help for the specified subcommand.
  88. """
  89. wic_create_usage = """
  90. Create a new OpenEmbedded image
  91. usage: wic create <wks file or image name> [-o <DIRNAME> | --outdir <DIRNAME>]
  92. [-e | --image-name] [-s, --skip-build-check] [-D, --debug]
  93. [-r, --rootfs-dir] [-b, --bootimg-dir]
  94. [-k, --kernel-dir] [-n, --native-sysroot] [-f, --build-rootfs]
  95. [-c, --compress-with] [-m, --bmap]
  96. This command creates an OpenEmbedded image based on the 'OE kickstart
  97. commands' found in the <wks file>.
  98. The -o option can be used to place the image in a directory with a
  99. different name and location.
  100. See 'wic help create' for more detailed instructions.
  101. """
  102. wic_create_help = """
  103. NAME
  104. wic create - Create a new OpenEmbedded image
  105. SYNOPSIS
  106. wic create <wks file or image name> [-o <DIRNAME> | --outdir <DIRNAME>]
  107. [-e | --image-name] [-s, --skip-build-check] [-D, --debug]
  108. [-r, --rootfs-dir] [-b, --bootimg-dir]
  109. [-k, --kernel-dir] [-n, --native-sysroot] [-f, --build-rootfs]
  110. [-c, --compress-with] [-m, --bmap] [--no-fstab-update]
  111. DESCRIPTION
  112. This command creates an OpenEmbedded image based on the 'OE
  113. kickstart commands' found in the <wks file>.
  114. In order to do this, wic needs to know the locations of the
  115. various build artifacts required to build the image.
  116. Users can explicitly specify the build artifact locations using
  117. the -r, -b, -k, and -n options. See below for details on where
  118. the corresponding artifacts are typically found in a normal
  119. OpenEmbedded build.
  120. Alternatively, users can use the -e option to have 'wic' determine
  121. those locations for a given image. If the -e option is used, the
  122. user needs to have set the appropriate MACHINE variable in
  123. local.conf, and have sourced the build environment.
  124. The -e option is used to specify the name of the image to use the
  125. artifacts from e.g. core-image-sato.
  126. The -r option is used to specify the path to the /rootfs dir to
  127. use as the .wks rootfs source.
  128. The -b option is used to specify the path to the dir containing
  129. the boot artifacts (e.g. /EFI or /syslinux dirs) to use as the
  130. .wks bootimg source.
  131. The -k option is used to specify the path to the dir containing
  132. the kernel to use in the .wks bootimg.
  133. The -n option is used to specify the path to the native sysroot
  134. containing the tools to use to build the image.
  135. The -f option is used to build rootfs by running "bitbake <image>"
  136. The -s option is used to skip the build check. The build check is
  137. a simple sanity check used to determine whether the user has
  138. sourced the build environment so that the -e option can operate
  139. correctly. If the user has specified the build artifact locations
  140. explicitly, 'wic' assumes the user knows what he or she is doing
  141. and skips the build check.
  142. The -D option is used to display debug information detailing
  143. exactly what happens behind the scenes when a create request is
  144. fulfilled (or not, as the case may be). It enumerates and
  145. displays the command sequence used, and should be included in any
  146. bug report describing unexpected results.
  147. When 'wic -e' is used, the locations for the build artifacts
  148. values are determined by 'wic -e' from the output of the 'bitbake
  149. -e' command given an image name e.g. 'core-image-minimal' and a
  150. given machine set in local.conf. In that case, the image is
  151. created as if the following 'bitbake -e' variables were used:
  152. -r: IMAGE_ROOTFS
  153. -k: STAGING_KERNEL_DIR
  154. -n: STAGING_DIR_NATIVE
  155. -b: empty (plugin-specific handlers must determine this)
  156. If 'wic -e' is not used, the user needs to select the appropriate
  157. value for -b (as well as -r, -k, and -n).
  158. The -o option can be used to place the image in a directory with a
  159. different name and location.
  160. The -c option is used to specify compressor utility to compress
  161. an image. gzip, bzip2 and xz compressors are supported.
  162. The -m option is used to produce .bmap file for the image. This file
  163. can be used to flash image using bmaptool utility.
  164. The --no-fstab-update option is used to doesn't change fstab file. When
  165. using this option the final fstab file will be same that in rootfs and
  166. wic doesn't update file, e.g adding a new mount point. User can control
  167. the fstab file content in base-files recipe.
  168. """
  169. wic_list_usage = """
  170. List available OpenEmbedded images and source plugins
  171. usage: wic list images
  172. wic list <image> help
  173. wic list source-plugins
  174. This command enumerates the set of available canned images as well as
  175. help for those images. It also can be used to list of available source
  176. plugins.
  177. The first form enumerates all the available 'canned' images.
  178. The second form lists the detailed help information for a specific
  179. 'canned' image.
  180. The third form enumerates all the available --sources (source
  181. plugins).
  182. See 'wic help list' for more details.
  183. """
  184. wic_list_help = """
  185. NAME
  186. wic list - List available OpenEmbedded images and source plugins
  187. SYNOPSIS
  188. wic list images
  189. wic list <image> help
  190. wic list source-plugins
  191. DESCRIPTION
  192. This command enumerates the set of available canned images as well
  193. as help for those images. It also can be used to list available
  194. source plugins.
  195. The first form enumerates all the available 'canned' images.
  196. These are actually just the set of .wks files that have been moved
  197. into the /scripts/lib/wic/canned-wks directory).
  198. The second form lists the detailed help information for a specific
  199. 'canned' image.
  200. The third form enumerates all the available --sources (source
  201. plugins). The contents of a given partition are driven by code
  202. defined in 'source plugins'. Users specify a specific plugin via
  203. the --source parameter of the partition .wks command. Normally
  204. this is the 'rootfs' plugin but can be any of the more specialized
  205. sources listed by the 'list source-plugins' command. Users can
  206. also add their own source plugins - see 'wic help plugins' for
  207. details.
  208. """
  209. wic_ls_usage = """
  210. List content of a partitioned image
  211. usage: wic ls <image>[:<partition>[<path>]] [--native-sysroot <path>]
  212. This command outputs either list of image partitions or directory contents
  213. of vfat and ext* partitions.
  214. See 'wic help ls' for more detailed instructions.
  215. """
  216. wic_ls_help = """
  217. NAME
  218. wic ls - List contents of partitioned image or partition
  219. SYNOPSIS
  220. wic ls <image>
  221. wic ls <image>:<vfat or ext* partition>
  222. wic ls <image>:<vfat or ext* partition><path>
  223. wic ls <image>:<vfat or ext* partition><path> --native-sysroot <path>
  224. DESCRIPTION
  225. This command lists either partitions of the image or directory contents
  226. of vfat or ext* partitions.
  227. The first form it lists partitions of the image.
  228. For example:
  229. $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic
  230. Num Start End Size Fstype
  231. 1 1048576 24438783 23390208 fat16
  232. 2 25165824 50315263 25149440 ext4
  233. Second and third form list directory content of the partition:
  234. $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
  235. Volume in drive : is boot
  236. Volume Serial Number is 2DF2-5F02
  237. Directory for ::/
  238. efi <DIR> 2017-05-11 10:54
  239. startup nsh 26 2017-05-11 10:54
  240. vmlinuz 6922288 2017-05-11 10:54
  241. 3 files 6 922 314 bytes
  242. 15 818 752 bytes free
  243. $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/EFI/boot/
  244. Volume in drive : is boot
  245. Volume Serial Number is 2DF2-5F02
  246. Directory for ::/EFI/boot
  247. . <DIR> 2017-05-11 10:54
  248. .. <DIR> 2017-05-11 10:54
  249. grub cfg 679 2017-05-11 10:54
  250. bootx64 efi 571392 2017-05-11 10:54
  251. 4 files 572 071 bytes
  252. 15 818 752 bytes free
  253. The -n option is used to specify the path to the native sysroot
  254. containing the tools(parted and mtools) to use.
  255. """
  256. wic_cp_usage = """
  257. Copy files and directories to/from the vfat or ext* partition
  258. usage: wic cp <src> <dest> [--native-sysroot <path>]
  259. source/destination image in format <image>:<partition>[<path>]
  260. This command copies files or directories either
  261. - from local to vfat or ext* partitions of partitioned image
  262. - from vfat or ext* partitions of partitioned image to local
  263. See 'wic help cp' for more detailed instructions.
  264. """
  265. wic_cp_help = """
  266. NAME
  267. wic cp - copy files and directories to/from the vfat or ext* partitions
  268. SYNOPSIS
  269. wic cp <src> <dest>:<partition>
  270. wic cp <src>:<partition> <dest>
  271. wic cp <src> <dest-image>:<partition><path>
  272. wic cp <src> <dest-image>:<partition><path> --native-sysroot <path>
  273. DESCRIPTION
  274. This command copies files or directories either
  275. - from local to vfat or ext* partitions of partitioned image
  276. - from vfat or ext* partitions of partitioned image to local
  277. The first form of it copies file or directory to the root directory of
  278. the partition:
  279. $ wic cp test.wks tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
  280. $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
  281. Volume in drive : is boot
  282. Volume Serial Number is DB4C-FD4C
  283. Directory for ::/
  284. efi <DIR> 2017-05-24 18:15
  285. loader <DIR> 2017-05-24 18:15
  286. startup nsh 26 2017-05-24 18:15
  287. vmlinuz 6926384 2017-05-24 18:15
  288. test wks 628 2017-05-24 21:22
  289. 5 files 6 927 038 bytes
  290. 15 677 440 bytes free
  291. The second form of the command copies file or directory to the specified directory
  292. on the partition:
  293. $ wic cp test tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/efi/
  294. $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/efi/
  295. Volume in drive : is boot
  296. Volume Serial Number is DB4C-FD4C
  297. Directory for ::/efi
  298. . <DIR> 2017-05-24 18:15
  299. .. <DIR> 2017-05-24 18:15
  300. boot <DIR> 2017-05-24 18:15
  301. test <DIR> 2017-05-24 21:27
  302. 4 files 0 bytes
  303. 15 675 392 bytes free
  304. The third form of the command copies file or directory from the specified directory
  305. on the partition to local:
  306. $ wic cp tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/vmlinuz test
  307. The -n option is used to specify the path to the native sysroot
  308. containing the tools(parted and mtools) to use.
  309. """
  310. wic_rm_usage = """
  311. Remove files or directories from the vfat or ext* partitions
  312. usage: wic rm <image>:<partition><path> [--native-sysroot <path>]
  313. This command removes files or directories from the vfat or ext* partitions of
  314. the partitioned image.
  315. See 'wic help rm' for more detailed instructions.
  316. """
  317. wic_rm_help = """
  318. NAME
  319. wic rm - remove files or directories from the vfat or ext* partitions
  320. SYNOPSIS
  321. wic rm <src> <image>:<partition><path>
  322. wic rm <src> <image>:<partition><path> --native-sysroot <path>
  323. wic rm -r <image>:<partition><path>
  324. DESCRIPTION
  325. This command removes files or directories from the vfat or ext* partition of the
  326. partitioned image:
  327. $ wic ls ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
  328. Volume in drive : is boot
  329. Volume Serial Number is 11D0-DE21
  330. Directory for ::/
  331. libcom32 c32 186500 2017-06-02 15:15
  332. libutil c32 24148 2017-06-02 15:15
  333. syslinux cfg 209 2017-06-02 15:15
  334. vesamenu c32 27104 2017-06-02 15:15
  335. vmlinuz 6926384 2017-06-02 15:15
  336. 5 files 7 164 345 bytes
  337. 16 582 656 bytes free
  338. $ wic rm ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/libutil.c32
  339. $ wic ls ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
  340. Volume in drive : is boot
  341. Volume Serial Number is 11D0-DE21
  342. Directory for ::/
  343. libcom32 c32 186500 2017-06-02 15:15
  344. syslinux cfg 209 2017-06-02 15:15
  345. vesamenu c32 27104 2017-06-02 15:15
  346. vmlinuz 6926384 2017-06-02 15:15
  347. 4 files 7 140 197 bytes
  348. 16 607 232 bytes free
  349. The -n option is used to specify the path to the native sysroot
  350. containing the tools(parted and mtools) to use.
  351. The -r option is used to remove directories and their contents
  352. recursively,this only applies to ext* partition.
  353. """
  354. wic_write_usage = """
  355. Write image to a device
  356. usage: wic write <image> <target device> [--expand [rules]] [--native-sysroot <path>]
  357. This command writes partitioned image to a target device (USB stick, SD card etc).
  358. See 'wic help write' for more detailed instructions.
  359. """
  360. wic_write_help = """
  361. NAME
  362. wic write - write an image to a device
  363. SYNOPSIS
  364. wic write <image> <target>
  365. wic write <image> <target> --expand auto
  366. wic write <image> <target> --expand 1:100M,2:300M
  367. wic write <image> <target> --native-sysroot <path>
  368. DESCRIPTION
  369. This command writes an image to a target device (USB stick, SD card etc)
  370. $ wic write ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic /dev/sdb
  371. The --expand option is used to resize image partitions.
  372. --expand auto expands partitions to occupy all free space available on the target device.
  373. It's also possible to specify expansion rules in a format
  374. <partition>:<size>[,<partition>:<size>...] for one or more partitions.
  375. Specifying size 0 will keep partition unmodified.
  376. Note: Resizing boot partition can result in non-bootable image for non-EFI images. It is
  377. recommended to use size 0 for boot partition to keep image bootable.
  378. The --native-sysroot option is used to specify the path to the native sysroot
  379. containing the tools(parted, resize2fs) to use.
  380. """
  381. wic_plugins_help = """
  382. NAME
  383. wic plugins - Overview and API
  384. DESCRIPTION
  385. plugins allow wic functionality to be extended and specialized by
  386. users. This section documents the plugin interface, which is
  387. currently restricted to 'source' plugins.
  388. 'Source' plugins provide a mechanism to customize various aspects
  389. of the image generation process in wic, mainly the contents of
  390. partitions.
  391. Source plugins provide a mechanism for mapping values specified in
  392. .wks files using the --source keyword to a particular plugin
  393. implementation that populates a corresponding partition.
  394. A source plugin is created as a subclass of SourcePlugin (see
  395. scripts/lib/wic/pluginbase.py) and the plugin file containing it
  396. is added to scripts/lib/wic/plugins/source/ to make the plugin
  397. implementation available to the wic implementation.
  398. Source plugins can also be implemented and added by external
  399. layers - any plugins found in a scripts/lib/wic/plugins/source/
  400. directory in an external layer will also be made available.
  401. When the wic implementation needs to invoke a partition-specific
  402. implementation, it looks for the plugin that has the same name as
  403. the --source param given to that partition. For example, if the
  404. partition is set up like this:
  405. part /boot --source bootimg-pcbios ...
  406. then the methods defined as class members of the plugin having the
  407. matching bootimg-pcbios .name class member would be used.
  408. To be more concrete, here's the plugin definition that would match
  409. a '--source bootimg-pcbios' usage, along with an example method
  410. that would be called by the wic implementation when it needed to
  411. invoke an implementation-specific partition-preparation function:
  412. class BootimgPcbiosPlugin(SourcePlugin):
  413. name = 'bootimg-pcbios'
  414. @classmethod
  415. def do_prepare_partition(self, part, ...)
  416. If the subclass itself doesn't implement a function, a 'default'
  417. version in a superclass will be located and used, which is why all
  418. plugins must be derived from SourcePlugin.
  419. The SourcePlugin class defines the following methods, which is the
  420. current set of methods that can be implemented/overridden by
  421. --source plugins. Any methods not implemented by a SourcePlugin
  422. subclass inherit the implementations present in the SourcePlugin
  423. class (see the SourcePlugin source for details):
  424. do_prepare_partition()
  425. Called to do the actual content population for a
  426. partition. In other words, it 'prepares' the final partition
  427. image which will be incorporated into the disk image.
  428. do_post_partition()
  429. Called after the partition is created. It is useful to add post
  430. operations e.g. signing the partition.
  431. do_configure_partition()
  432. Called before do_prepare_partition(), typically used to
  433. create custom configuration files for a partition, for
  434. example syslinux or grub config files.
  435. do_install_disk()
  436. Called after all partitions have been prepared and assembled
  437. into a disk image. This provides a hook to allow
  438. finalization of a disk image, for example to write an MBR to
  439. it.
  440. do_stage_partition()
  441. Special content-staging hook called before
  442. do_prepare_partition(), normally empty.
  443. Typically, a partition will just use the passed-in
  444. parameters, for example the unmodified value of bootimg_dir.
  445. In some cases however, things may need to be more tailored.
  446. As an example, certain files may additionally need to be
  447. take from bootimg_dir + /boot. This hook allows those files
  448. to be staged in a customized fashion. Note that
  449. get_bitbake_var() allows you to access non-standard
  450. variables that you might want to use for these types of
  451. situations.
  452. This scheme is extensible - adding more hooks is a simple matter
  453. of adding more plugin methods to SourcePlugin and derived classes.
  454. Please see the implementation for details.
  455. """
  456. wic_overview_help = """
  457. NAME
  458. wic overview - General overview of wic
  459. DESCRIPTION
  460. The 'wic' command generates partitioned images from existing
  461. OpenEmbedded build artifacts. Image generation is driven by
  462. partitioning commands contained in an 'Openembedded kickstart'
  463. (.wks) file (see 'wic help kickstart') specified either directly
  464. on the command-line or as one of a selection of canned .wks files
  465. (see 'wic list images'). When applied to a given set of build
  466. artifacts, the result is an image or set of images that can be
  467. directly written onto media and used on a particular system.
  468. The 'wic' command and the infrastructure it's based on is by
  469. definition incomplete - its purpose is to allow the generation of
  470. customized images, and as such was designed to be completely
  471. extensible via a plugin interface (see 'wic help plugins').
  472. Background and Motivation
  473. wic is meant to be a completely independent standalone utility
  474. that initially provides easier-to-use and more flexible
  475. replacements for a couple bits of existing functionality in
  476. oe-core: directdisk.bbclass and mkefidisk.sh. The difference
  477. between wic and those examples is that with wic the functionality
  478. of those scripts is implemented by a general-purpose partitioning
  479. 'language' based on Redhat kickstart syntax).
  480. The initial motivation and design considerations that lead to the
  481. current tool are described exhaustively in Yocto Bug #3847
  482. (https://bugzilla.yoctoproject.org/show_bug.cgi?id=3847).
  483. Implementation and Examples
  484. wic can be used in two different modes, depending on how much
  485. control the user needs in specifying the Openembedded build
  486. artifacts that will be used in creating the image: 'raw' and
  487. 'cooked'.
  488. If used in 'raw' mode, artifacts are explicitly specified via
  489. command-line arguments (see example below).
  490. The more easily usable 'cooked' mode uses the current MACHINE
  491. setting and a specified image name to automatically locate the
  492. artifacts used to create the image.
  493. OE kickstart files (.wks) can of course be specified directly on
  494. the command-line, but the user can also choose from a set of
  495. 'canned' .wks files available via the 'wic list images' command
  496. (example below).
  497. In any case, the prerequisite for generating any image is to have
  498. the build artifacts already available. The below examples assume
  499. the user has already build a 'core-image-minimal' for a specific
  500. machine (future versions won't require this redundant step, but
  501. for now that's typically how build artifacts get generated).
  502. The other prerequisite is to source the build environment:
  503. $ source oe-init-build-env
  504. To start out with, we'll generate an image from one of the canned
  505. .wks files. The following generates a list of availailable
  506. images:
  507. $ wic list images
  508. mkefidisk Create an EFI disk image
  509. directdisk Create a 'pcbios' direct disk image
  510. You can get more information about any of the available images by
  511. typing 'wic list xxx help', where 'xxx' is one of the image names:
  512. $ wic list mkefidisk help
  513. Creates a partitioned EFI disk image that the user can directly dd
  514. to boot media.
  515. At any time, you can get help on the 'wic' command or any
  516. subcommand (currently 'list' and 'create'). For instance, to get
  517. the description of 'wic create' command and its parameters:
  518. $ wic create
  519. Usage:
  520. Create a new OpenEmbedded image
  521. usage: wic create <wks file or image name> [-o <DIRNAME> | ...]
  522. [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]
  523. [-e | --image-name] [-s, --skip-build-check] [-D, --debug]
  524. [-r, --rootfs-dir] [-b, --bootimg-dir] [-k, --kernel-dir]
  525. [-n, --native-sysroot] [-f, --build-rootfs]
  526. This command creates an OpenEmbedded image based on the 'OE
  527. kickstart commands' found in the <wks file>.
  528. The -o option can be used to place the image in a directory
  529. with a different name and location.
  530. See 'wic help create' for more detailed instructions.
  531. ...
  532. As mentioned in the command, you can get even more detailed
  533. information by adding 'help' to the above:
  534. $ wic help create
  535. So, the easiest way to create an image is to use the -e option
  536. with a canned .wks file. To use the -e option, you need to
  537. specify the image used to generate the artifacts and you actually
  538. need to have the MACHINE used to build them specified in your
  539. local.conf (these requirements aren't necessary if you aren't
  540. using the -e options.) Below, we generate a directdisk image,
  541. pointing the process at the core-image-minimal artifacts for the
  542. current MACHINE:
  543. $ wic create directdisk -e core-image-minimal
  544. Checking basic build environment...
  545. Done.
  546. Creating image(s)...
  547. Info: The new image(s) can be found here:
  548. /var/tmp/wic/build/directdisk-201309252350-sda.direct
  549. The following build artifacts were used to create the image(s):
  550. ROOTFS_DIR: ...
  551. BOOTIMG_DIR: ...
  552. KERNEL_DIR: ...
  553. NATIVE_SYSROOT: ...
  554. The image(s) were created using OE kickstart file:
  555. .../scripts/lib/wic/canned-wks/directdisk.wks
  556. The output shows the name and location of the image created, and
  557. so that you know exactly what was used to generate the image, each
  558. of the artifacts and the kickstart file used.
  559. Similarly, you can create a 'mkefidisk' image in the same way
  560. (notice that this example uses a different machine - because it's
  561. using the -e option, you need to change the MACHINE in your
  562. local.conf):
  563. $ wic create mkefidisk -e core-image-minimal
  564. Checking basic build environment...
  565. Done.
  566. Creating image(s)...
  567. Info: The new image(s) can be found here:
  568. /var/tmp/wic/build/mkefidisk-201309260027-sda.direct
  569. ...
  570. Here's an example that doesn't take the easy way out and manually
  571. specifies each build artifact, along with a non-canned .wks file,
  572. and also uses the -o option to have wic create the output
  573. somewhere other than the default /var/tmp/wic:
  574. $ wic create ./test.wks -o ./out --rootfs-dir
  575. tmp/work/qemux86_64-poky-linux/core-image-minimal/1.0-r0/rootfs
  576. --bootimg-dir tmp/sysroots/qemux86-64/usr/share
  577. --kernel-dir tmp/deploy/images/qemux86-64
  578. --native-sysroot tmp/sysroots/x86_64-linux
  579. Creating image(s)...
  580. Info: The new image(s) can be found here:
  581. out/build/test-201507211313-sda.direct
  582. The following build artifacts were used to create the image(s):
  583. ROOTFS_DIR: tmp/work/qemux86_64-poky-linux/core-image-minimal/1.0-r0/rootfs
  584. BOOTIMG_DIR: tmp/sysroots/qemux86-64/usr/share
  585. KERNEL_DIR: tmp/deploy/images/qemux86-64
  586. NATIVE_SYSROOT: tmp/sysroots/x86_64-linux
  587. The image(s) were created using OE kickstart file:
  588. ./test.wks
  589. Here is a content of test.wks:
  590. part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
  591. part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024
  592. bootloader --timeout=0 --append="rootwait rootfstype=ext3 video=vesafb vga=0x318 console=tty0"
  593. Finally, here's an example of the actual partition language
  594. commands used to generate the mkefidisk image i.e. these are the
  595. contents of the mkefidisk.wks OE kickstart file:
  596. # short-description: Create an EFI disk image
  597. # long-description: Creates a partitioned EFI disk image that the user
  598. # can directly dd to boot media.
  599. part /boot --source bootimg-efi --ondisk sda --fstype=efi --active
  600. part / --source rootfs --ondisk sda --fstype=ext3 --label platform
  601. part swap --ondisk sda --size 44 --label swap1 --fstype=swap
  602. bootloader --timeout=10 --append="rootwait console=ttyPCH0,115200"
  603. You can get a complete listing and description of all the
  604. kickstart commands available for use in .wks files from 'wic help
  605. kickstart'.
  606. """
  607. wic_kickstart_help = """
  608. NAME
  609. wic kickstart - wic kickstart reference
  610. DESCRIPTION
  611. This section provides the definitive reference to the wic
  612. kickstart language. It also provides documentation on the list of
  613. --source plugins available for use from the 'part' command (see
  614. the 'Platform-specific Plugins' section below).
  615. The current wic implementation supports only the basic kickstart
  616. partitioning commands: partition (or part for short) and
  617. bootloader.
  618. The following is a listing of the commands, their syntax, and
  619. meanings. The commands are based on the Fedora kickstart
  620. documentation but with modifications to reflect wic capabilities.
  621. http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition
  622. http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader
  623. Commands
  624. * 'part' or 'partition'
  625. This command creates a partition on the system and uses the
  626. following syntax:
  627. part [<mountpoint>]
  628. The <mountpoint> is where the partition will be mounted and
  629. must take of one of the following forms:
  630. /<path>: For example: /, /usr, or /home
  631. swap: The partition will be used as swap space.
  632. If a <mountpoint> is not specified the partition will be created
  633. but will not be mounted.
  634. Partitions with a <mountpoint> specified will be automatically mounted.
  635. This is achieved by wic adding entries to the fstab during image
  636. generation. In order for a valid fstab to be generated one of the
  637. --ondrive, --ondisk, --use-uuid or --use-label partition options must
  638. be used for each partition that specifies a mountpoint. Note that with
  639. --use-{uuid,label} and non-root <mountpoint>, including swap, the mount
  640. program must understand the PARTUUID or LABEL syntax. This currently
  641. excludes the busybox versions of these applications.
  642. The following are supported 'part' options:
  643. --size: The minimum partition size. Specify an integer value
  644. such as 500. Multipliers k, M ang G can be used. If
  645. not specified, the size is in MB.
  646. You do not need this option if you use --source.
  647. --fixed-size: Exact partition size. Value format is the same
  648. as for --size option. This option cannot be
  649. specified along with --size. If partition data
  650. is larger than --fixed-size and error will be
  651. raised when assembling disk image.
  652. --source: This option is a wic-specific option that names the
  653. source of the data that will populate the
  654. partition. The most common value for this option
  655. is 'rootfs', but can be any value which maps to a
  656. valid 'source plugin' (see 'wic help plugins').
  657. If '--source rootfs' is used, it tells the wic
  658. command to create a partition as large as needed
  659. and to fill it with the contents of the root
  660. filesystem pointed to by the '-r' wic command-line
  661. option (or the equivalent rootfs derived from the
  662. '-e' command-line option). The filesystem type
  663. that will be used to create the partition is driven
  664. by the value of the --fstype option specified for
  665. the partition (see --fstype below).
  666. If --source <plugin-name>' is used, it tells the
  667. wic command to create a partition as large as
  668. needed and to fill with the contents of the
  669. partition that will be generated by the specified
  670. plugin name using the data pointed to by the '-r'
  671. wic command-line option (or the equivalent rootfs
  672. derived from the '-e' command-line option).
  673. Exactly what those contents and filesystem type end
  674. up being are dependent on the given plugin
  675. implementation.
  676. If --source option is not used, the wic command
  677. will create empty partition. --size parameter has
  678. to be used to specify size of empty partition.
  679. --ondisk or --ondrive: Forces the partition to be created on
  680. a particular disk.
  681. --fstype: Sets the file system type for the partition. These
  682. apply to partitions created using '--source rootfs' (see
  683. --source above). Valid values are:
  684. vfat
  685. msdos
  686. ext2
  687. ext3
  688. ext4
  689. btrfs
  690. squashfs
  691. swap
  692. --fsoptions: Specifies a free-form string of options to be
  693. used when mounting the filesystem. This string
  694. will be copied into the /etc/fstab file of the
  695. installed system and should be enclosed in
  696. quotes. If not specified, the default string is
  697. "defaults".
  698. --label label: Specifies the label to give to the filesystem
  699. to be made on the partition. If the given
  700. label is already in use by another filesystem,
  701. a new label is created for the partition.
  702. --use-label: This option is specific to wic. It makes wic to use the
  703. label in /etc/fstab to specify a partition. If the
  704. --use-label and --use-uuid are used at the same time,
  705. we prefer the uuid because it is less likely to cause
  706. name confliction. We don't support using this parameter
  707. on the root partition since it requires an initramfs to
  708. parse this value and we do not currently support that.
  709. --active: Marks the partition as active.
  710. --align (in KBytes): This option is specific to wic and says
  711. to start a partition on an x KBytes
  712. boundary.
  713. --no-table: This option is specific to wic. Space will be
  714. reserved for the partition and it will be
  715. populated but it will not be added to the
  716. partition table. It may be useful for
  717. bootloaders.
  718. --exclude-path: This option is specific to wic. It excludes the given
  719. relative path from the resulting image. If the path
  720. ends with a slash, only the content of the directory
  721. is omitted, not the directory itself. This option only
  722. has an effect with the rootfs source plugin.
  723. --extra-space: This option is specific to wic. It adds extra
  724. space after the space filled by the content
  725. of the partition. The final size can go
  726. beyond the size specified by --size.
  727. By default, 10MB. This option cannot be used
  728. with --fixed-size option.
  729. --overhead-factor: This option is specific to wic. The
  730. size of the partition is multiplied by
  731. this factor. It has to be greater than or
  732. equal to 1. The default value is 1.3.
  733. This option cannot be used with --fixed-size
  734. option.
  735. --part-name: This option is specific to wic. It specifies name for GPT partitions.
  736. --part-type: This option is specific to wic. It specifies partition
  737. type GUID for GPT partitions.
  738. List of partition type GUIDS can be found here:
  739. http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
  740. --use-uuid: This option is specific to wic. It makes wic to generate
  741. random globally unique identifier (GUID) for the partition
  742. and use it in bootloader configuration to specify root partition.
  743. --uuid: This option is specific to wic. It specifies partition UUID.
  744. It's useful if preconfigured partition UUID is added to kernel command line
  745. in bootloader configuration before running wic. In this case .wks file can
  746. be generated or modified to set preconfigured parition UUID using this option.
  747. --fsuuid: This option is specific to wic. It specifies filesystem UUID.
  748. It's useful if preconfigured filesystem UUID is added to kernel command line
  749. in bootloader configuration before running wic. In this case .wks file can
  750. be generated or modified to set preconfigured filesystem UUID using this option.
  751. --system-id: This option is specific to wic. It specifies partition system id. It's useful
  752. for the harware that requires non-default partition system ids. The parameter
  753. in one byte long hex number either with 0x prefix or without it.
  754. --mkfs-extraopts: This option specifies extra options to pass to mkfs utility.
  755. NOTE, that wic uses default options for some filesystems, for example
  756. '-S 512' for mkfs.fat or '-F -i 8192' for mkfs.ext. Those options will
  757. not take effect when --mkfs-extraopts is used. This should be taken into
  758. account when using --mkfs-extraopts.
  759. * bootloader
  760. This command allows the user to specify various bootloader
  761. options. The following are supported 'bootloader' options:
  762. --timeout: Specifies the number of seconds before the
  763. bootloader times out and boots the default option.
  764. --append: Specifies kernel parameters. These will be added to
  765. bootloader command-line - for example, the syslinux
  766. APPEND or grub kernel command line.
  767. --configfile: Specifies a user defined configuration file for
  768. the bootloader. This file must be located in the
  769. canned-wks folder or could be the full path to the
  770. file. Using this option will override any other
  771. bootloader option.
  772. Note that bootloader functionality and boot partitions are
  773. implemented by the various --source plugins that implement
  774. bootloader functionality; the bootloader command essentially
  775. provides a means of modifying bootloader configuration.
  776. * include
  777. This command allows the user to include the content of .wks file
  778. into original .wks file.
  779. Command uses the following syntax:
  780. include <file>
  781. The <file> is either path to the file or its name. If name is
  782. specified wic will try to find file in the directories with canned
  783. .wks files.
  784. """
  785. wic_help_help = """
  786. NAME
  787. wic help - display a help topic
  788. DESCRIPTION
  789. Specify a help topic to display it. Topics are shown above.
  790. """
  791. wic_help = """
  792. Creates a customized OpenEmbedded image.
  793. Usage: wic [--version]
  794. wic help [COMMAND or TOPIC]
  795. wic COMMAND [ARGS]
  796. usage 1: Returns the current version of Wic
  797. usage 2: Returns detailed help for a COMMAND or TOPIC
  798. usage 3: Executes COMMAND
  799. COMMAND:
  800. list - List available canned images and source plugins
  801. ls - List contents of partitioned image or partition
  802. rm - Remove files or directories from the vfat or ext* partitions
  803. help - Show help for a wic COMMAND or TOPIC
  804. write - Write an image to a device
  805. cp - Copy files and directories to the vfat or ext* partitions
  806. create - Create a new OpenEmbedded image
  807. TOPIC:
  808. overview - Presents an overall overview of Wic
  809. plugins - Presents an overview and API for Wic plugins
  810. kickstart - Presents a Wic kicstart file reference
  811. Examples:
  812. $ wic --version
  813. Returns the current version of Wic
  814. $ wic help cp
  815. Returns the SYNOPSIS and DESCRIPTION for the Wic "cp" command.
  816. $ wic list images
  817. Returns the list of canned images (i.e. *.wks files located in
  818. the /scripts/lib/wic/canned-wks directory.
  819. $ wic create mkefidisk -e core-image-minimal
  820. Creates an EFI disk image from artifacts used in a previous
  821. core-image-minimal build in standard BitBake locations
  822. (e.g. Cooked Mode).
  823. """