help.py 40 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049
  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 the vfat or ext* partition
  258. usage: wic cp <src> <image>:<partition>[<path>] [--native-sysroot <path>]
  259. This command copies local files or directories to the vfat or ext* partitions
  260. of partitioned image.
  261. See 'wic help cp' for more detailed instructions.
  262. """
  263. wic_cp_help = """
  264. NAME
  265. wic cp - copy files and directories to the vfat or ext* partitions
  266. SYNOPSIS
  267. wic cp <src> <image>:<partition>
  268. wic cp <src> <image>:<partition><path>
  269. wic cp <src> <image>:<partition><path> --native-sysroot <path>
  270. DESCRIPTION
  271. This command copies files and directories to the vfat or ext* partition of
  272. the partitioned image.
  273. The first form of it copies file or directory to the root directory of
  274. the partition:
  275. $ wic cp test.wks tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
  276. $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
  277. Volume in drive : is boot
  278. Volume Serial Number is DB4C-FD4C
  279. Directory for ::/
  280. efi <DIR> 2017-05-24 18:15
  281. loader <DIR> 2017-05-24 18:15
  282. startup nsh 26 2017-05-24 18:15
  283. vmlinuz 6926384 2017-05-24 18:15
  284. test wks 628 2017-05-24 21:22
  285. 5 files 6 927 038 bytes
  286. 15 677 440 bytes free
  287. The second form of the command copies file or directory to the specified directory
  288. on the partition:
  289. $ wic cp test tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/efi/
  290. $ wic ls tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/efi/
  291. Volume in drive : is boot
  292. Volume Serial Number is DB4C-FD4C
  293. Directory for ::/efi
  294. . <DIR> 2017-05-24 18:15
  295. .. <DIR> 2017-05-24 18:15
  296. boot <DIR> 2017-05-24 18:15
  297. test <DIR> 2017-05-24 21:27
  298. 4 files 0 bytes
  299. 15 675 392 bytes free
  300. The -n option is used to specify the path to the native sysroot
  301. containing the tools(parted and mtools) to use.
  302. """
  303. wic_rm_usage = """
  304. Remove files or directories from the vfat or ext* partitions
  305. usage: wic rm <image>:<partition><path> [--native-sysroot <path>]
  306. This command removes files or directories from the vfat or ext* partitions of
  307. the partitioned image.
  308. See 'wic help rm' for more detailed instructions.
  309. """
  310. wic_rm_help = """
  311. NAME
  312. wic rm - remove files or directories from the vfat or ext* partitions
  313. SYNOPSIS
  314. wic rm <src> <image>:<partition><path>
  315. wic rm <src> <image>:<partition><path> --native-sysroot <path>
  316. DESCRIPTION
  317. This command removes files or directories from the vfat or ext* partition of the
  318. partitioned image:
  319. $ wic ls ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
  320. Volume in drive : is boot
  321. Volume Serial Number is 11D0-DE21
  322. Directory for ::/
  323. libcom32 c32 186500 2017-06-02 15:15
  324. libutil c32 24148 2017-06-02 15:15
  325. syslinux cfg 209 2017-06-02 15:15
  326. vesamenu c32 27104 2017-06-02 15:15
  327. vmlinuz 6926384 2017-06-02 15:15
  328. 5 files 7 164 345 bytes
  329. 16 582 656 bytes free
  330. $ wic rm ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1/libutil.c32
  331. $ wic ls ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic:1
  332. Volume in drive : is boot
  333. Volume Serial Number is 11D0-DE21
  334. Directory for ::/
  335. libcom32 c32 186500 2017-06-02 15:15
  336. syslinux cfg 209 2017-06-02 15:15
  337. vesamenu c32 27104 2017-06-02 15:15
  338. vmlinuz 6926384 2017-06-02 15:15
  339. 4 files 7 140 197 bytes
  340. 16 607 232 bytes free
  341. The -n option is used to specify the path to the native sysroot
  342. containing the tools(parted and mtools) to use.
  343. """
  344. wic_write_usage = """
  345. Write image to a device
  346. usage: wic write <image> <target device> [--expand [rules]] [--native-sysroot <path>]
  347. This command writes partitioned image to a target device (USB stick, SD card etc).
  348. See 'wic help write' for more detailed instructions.
  349. """
  350. wic_write_help = """
  351. NAME
  352. wic write - write an image to a device
  353. SYNOPSIS
  354. wic write <image> <target>
  355. wic write <image> <target> --expand auto
  356. wic write <image> <target> --expand 1:100M-2:300M
  357. wic write <image> <target> --native-sysroot <path>
  358. DESCRIPTION
  359. This command writes an image to a target device (USB stick, SD card etc)
  360. $ wic write ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic /dev/sdb
  361. The --expand option is used to resize image partitions.
  362. --expand auto expands partitions to occupy all free space available on the target device.
  363. It's also possible to specify expansion rules in a format
  364. <partition>:<size>[-<partition>:<size>...] for one or more partitions.
  365. Specifying size 0 will keep partition unmodified.
  366. Note: Resizing boot partition can result in non-bootable image for non-EFI images. It is
  367. recommended to use size 0 for boot partition to keep image bootable.
  368. The --native-sysroot option is used to specify the path to the native sysroot
  369. containing the tools(parted, resize2fs) to use.
  370. """
  371. wic_plugins_help = """
  372. NAME
  373. wic plugins - Overview and API
  374. DESCRIPTION
  375. plugins allow wic functionality to be extended and specialized by
  376. users. This section documents the plugin interface, which is
  377. currently restricted to 'source' plugins.
  378. 'Source' plugins provide a mechanism to customize various aspects
  379. of the image generation process in wic, mainly the contents of
  380. partitions.
  381. Source plugins provide a mechanism for mapping values specified in
  382. .wks files using the --source keyword to a particular plugin
  383. implementation that populates a corresponding partition.
  384. A source plugin is created as a subclass of SourcePlugin (see
  385. scripts/lib/wic/pluginbase.py) and the plugin file containing it
  386. is added to scripts/lib/wic/plugins/source/ to make the plugin
  387. implementation available to the wic implementation.
  388. Source plugins can also be implemented and added by external
  389. layers - any plugins found in a scripts/lib/wic/plugins/source/
  390. or lib/wic/plugins/source/ directory in an external layer will
  391. also be made available.
  392. When the wic implementation needs to invoke a partition-specific
  393. implementation, it looks for the plugin that has the same name as
  394. the --source param given to that partition. For example, if the
  395. partition is set up like this:
  396. part /boot --source bootimg-pcbios ...
  397. then the methods defined as class members of the plugin having the
  398. matching bootimg-pcbios .name class member would be used.
  399. To be more concrete, here's the plugin definition that would match
  400. a '--source bootimg-pcbios' usage, along with an example method
  401. that would be called by the wic implementation when it needed to
  402. invoke an implementation-specific partition-preparation function:
  403. class BootimgPcbiosPlugin(SourcePlugin):
  404. name = 'bootimg-pcbios'
  405. @classmethod
  406. def do_prepare_partition(self, part, ...)
  407. If the subclass itself doesn't implement a function, a 'default'
  408. version in a superclass will be located and used, which is why all
  409. plugins must be derived from SourcePlugin.
  410. The SourcePlugin class defines the following methods, which is the
  411. current set of methods that can be implemented/overridden by
  412. --source plugins. Any methods not implemented by a SourcePlugin
  413. subclass inherit the implementations present in the SourcePlugin
  414. class (see the SourcePlugin source for details):
  415. do_prepare_partition()
  416. Called to do the actual content population for a
  417. partition. In other words, it 'prepares' the final partition
  418. image which will be incorporated into the disk image.
  419. do_post_partition()
  420. Called after the partition is created. It is useful to add post
  421. operations e.g. signing the partition.
  422. do_configure_partition()
  423. Called before do_prepare_partition(), typically used to
  424. create custom configuration files for a partition, for
  425. example syslinux or grub config files.
  426. do_install_disk()
  427. Called after all partitions have been prepared and assembled
  428. into a disk image. This provides a hook to allow
  429. finalization of a disk image, for example to write an MBR to
  430. it.
  431. do_stage_partition()
  432. Special content-staging hook called before
  433. do_prepare_partition(), normally empty.
  434. Typically, a partition will just use the passed-in
  435. parameters, for example the unmodified value of bootimg_dir.
  436. In some cases however, things may need to be more tailored.
  437. As an example, certain files may additionally need to be
  438. take from bootimg_dir + /boot. This hook allows those files
  439. to be staged in a customized fashion. Note that
  440. get_bitbake_var() allows you to access non-standard
  441. variables that you might want to use for these types of
  442. situations.
  443. This scheme is extensible - adding more hooks is a simple matter
  444. of adding more plugin methods to SourcePlugin and derived classes.
  445. Please see the implementation for details.
  446. """
  447. wic_overview_help = """
  448. NAME
  449. wic overview - General overview of wic
  450. DESCRIPTION
  451. The 'wic' command generates partitioned images from existing
  452. OpenEmbedded build artifacts. Image generation is driven by
  453. partitioning commands contained in an 'Openembedded kickstart'
  454. (.wks) file (see 'wic help kickstart') specified either directly
  455. on the command-line or as one of a selection of canned .wks files
  456. (see 'wic list images'). When applied to a given set of build
  457. artifacts, the result is an image or set of images that can be
  458. directly written onto media and used on a particular system.
  459. The 'wic' command and the infrastructure it's based on is by
  460. definition incomplete - its purpose is to allow the generation of
  461. customized images, and as such was designed to be completely
  462. extensible via a plugin interface (see 'wic help plugins').
  463. Background and Motivation
  464. wic is meant to be a completely independent standalone utility
  465. that initially provides easier-to-use and more flexible
  466. replacements for a couple bits of existing functionality in
  467. oe-core: directdisk.bbclass and mkefidisk.sh. The difference
  468. between wic and those examples is that with wic the functionality
  469. of those scripts is implemented by a general-purpose partitioning
  470. 'language' based on Redhat kickstart syntax).
  471. The initial motivation and design considerations that lead to the
  472. current tool are described exhaustively in Yocto Bug #3847
  473. (https://bugzilla.yoctoproject.org/show_bug.cgi?id=3847).
  474. Implementation and Examples
  475. wic can be used in two different modes, depending on how much
  476. control the user needs in specifying the Openembedded build
  477. artifacts that will be used in creating the image: 'raw' and
  478. 'cooked'.
  479. If used in 'raw' mode, artifacts are explicitly specified via
  480. command-line arguments (see example below).
  481. The more easily usable 'cooked' mode uses the current MACHINE
  482. setting and a specified image name to automatically locate the
  483. artifacts used to create the image.
  484. OE kickstart files (.wks) can of course be specified directly on
  485. the command-line, but the user can also choose from a set of
  486. 'canned' .wks files available via the 'wic list images' command
  487. (example below).
  488. In any case, the prerequisite for generating any image is to have
  489. the build artifacts already available. The below examples assume
  490. the user has already build a 'core-image-minimal' for a specific
  491. machine (future versions won't require this redundant step, but
  492. for now that's typically how build artifacts get generated).
  493. The other prerequisite is to source the build environment:
  494. $ source oe-init-build-env
  495. To start out with, we'll generate an image from one of the canned
  496. .wks files. The following generates a list of availailable
  497. images:
  498. $ wic list images
  499. mkefidisk Create an EFI disk image
  500. directdisk Create a 'pcbios' direct disk image
  501. You can get more information about any of the available images by
  502. typing 'wic list xxx help', where 'xxx' is one of the image names:
  503. $ wic list mkefidisk help
  504. Creates a partitioned EFI disk image that the user can directly dd
  505. to boot media.
  506. At any time, you can get help on the 'wic' command or any
  507. subcommand (currently 'list' and 'create'). For instance, to get
  508. the description of 'wic create' command and its parameters:
  509. $ wic create
  510. Usage:
  511. Create a new OpenEmbedded image
  512. usage: wic create <wks file or image name> [-o <DIRNAME> | ...]
  513. [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]
  514. [-e | --image-name] [-s, --skip-build-check] [-D, --debug]
  515. [-r, --rootfs-dir] [-b, --bootimg-dir] [-k, --kernel-dir]
  516. [-n, --native-sysroot] [-f, --build-rootfs]
  517. This command creates an OpenEmbedded image based on the 'OE
  518. kickstart commands' found in the <wks file>.
  519. The -o option can be used to place the image in a directory
  520. with a different name and location.
  521. See 'wic help create' for more detailed instructions.
  522. ...
  523. As mentioned in the command, you can get even more detailed
  524. information by adding 'help' to the above:
  525. $ wic help create
  526. So, the easiest way to create an image is to use the -e option
  527. with a canned .wks file. To use the -e option, you need to
  528. specify the image used to generate the artifacts and you actually
  529. need to have the MACHINE used to build them specified in your
  530. local.conf (these requirements aren't necessary if you aren't
  531. using the -e options.) Below, we generate a directdisk image,
  532. pointing the process at the core-image-minimal artifacts for the
  533. current MACHINE:
  534. $ wic create directdisk -e core-image-minimal
  535. Checking basic build environment...
  536. Done.
  537. Creating image(s)...
  538. Info: The new image(s) can be found here:
  539. /var/tmp/wic/build/directdisk-201309252350-sda.direct
  540. The following build artifacts were used to create the image(s):
  541. ROOTFS_DIR: ...
  542. BOOTIMG_DIR: ...
  543. KERNEL_DIR: ...
  544. NATIVE_SYSROOT: ...
  545. The image(s) were created using OE kickstart file:
  546. .../scripts/lib/wic/canned-wks/directdisk.wks
  547. The output shows the name and location of the image created, and
  548. so that you know exactly what was used to generate the image, each
  549. of the artifacts and the kickstart file used.
  550. Similarly, you can create a 'mkefidisk' image in the same way
  551. (notice that this example uses a different machine - because it's
  552. using the -e option, you need to change the MACHINE in your
  553. local.conf):
  554. $ wic create mkefidisk -e core-image-minimal
  555. Checking basic build environment...
  556. Done.
  557. Creating image(s)...
  558. Info: The new image(s) can be found here:
  559. /var/tmp/wic/build/mkefidisk-201309260027-sda.direct
  560. ...
  561. Here's an example that doesn't take the easy way out and manually
  562. specifies each build artifact, along with a non-canned .wks file,
  563. and also uses the -o option to have wic create the output
  564. somewhere other than the default /var/tmp/wic:
  565. $ wic create ./test.wks -o ./out --rootfs-dir
  566. tmp/work/qemux86_64-poky-linux/core-image-minimal/1.0-r0/rootfs
  567. --bootimg-dir tmp/sysroots/qemux86-64/usr/share
  568. --kernel-dir tmp/deploy/images/qemux86-64
  569. --native-sysroot tmp/sysroots/x86_64-linux
  570. Creating image(s)...
  571. Info: The new image(s) can be found here:
  572. out/build/test-201507211313-sda.direct
  573. The following build artifacts were used to create the image(s):
  574. ROOTFS_DIR: tmp/work/qemux86_64-poky-linux/core-image-minimal/1.0-r0/rootfs
  575. BOOTIMG_DIR: tmp/sysroots/qemux86-64/usr/share
  576. KERNEL_DIR: tmp/deploy/images/qemux86-64
  577. NATIVE_SYSROOT: tmp/sysroots/x86_64-linux
  578. The image(s) were created using OE kickstart file:
  579. ./test.wks
  580. Here is a content of test.wks:
  581. part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
  582. part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024
  583. bootloader --timeout=0 --append="rootwait rootfstype=ext3 video=vesafb vga=0x318 console=tty0"
  584. Finally, here's an example of the actual partition language
  585. commands used to generate the mkefidisk image i.e. these are the
  586. contents of the mkefidisk.wks OE kickstart file:
  587. # short-description: Create an EFI disk image
  588. # long-description: Creates a partitioned EFI disk image that the user
  589. # can directly dd to boot media.
  590. part /boot --source bootimg-efi --ondisk sda --fstype=efi --active
  591. part / --source rootfs --ondisk sda --fstype=ext3 --label platform
  592. part swap --ondisk sda --size 44 --label swap1 --fstype=swap
  593. bootloader --timeout=10 --append="rootwait console=ttyPCH0,115200"
  594. You can get a complete listing and description of all the
  595. kickstart commands available for use in .wks files from 'wic help
  596. kickstart'.
  597. """
  598. wic_kickstart_help = """
  599. NAME
  600. wic kickstart - wic kickstart reference
  601. DESCRIPTION
  602. This section provides the definitive reference to the wic
  603. kickstart language. It also provides documentation on the list of
  604. --source plugins available for use from the 'part' command (see
  605. the 'Platform-specific Plugins' section below).
  606. The current wic implementation supports only the basic kickstart
  607. partitioning commands: partition (or part for short) and
  608. bootloader.
  609. The following is a listing of the commands, their syntax, and
  610. meanings. The commands are based on the Fedora kickstart
  611. documentation but with modifications to reflect wic capabilities.
  612. http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition
  613. http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader
  614. Commands
  615. * 'part' or 'partition'
  616. This command creates a partition on the system and uses the
  617. following syntax:
  618. part [<mountpoint>]
  619. The <mountpoint> is where the partition will be mounted and
  620. must take of one of the following forms:
  621. /<path>: For example: /, /usr, or /home
  622. swap: The partition will be used as swap space.
  623. If a <mountpoint> is not specified the partition will be created
  624. but will not be mounted.
  625. Partitions with a <mountpoint> specified will be automatically mounted.
  626. This is achieved by wic adding entries to the fstab during image
  627. generation. In order for a valid fstab to be generated one of the
  628. --ondrive, --ondisk, --use-uuid or --use-label partition options must
  629. be used for each partition that specifies a mountpoint. Note that with
  630. --use-{uuid,label} and non-root <mountpoint>, including swap, the mount
  631. program must understand the PARTUUID or LABEL syntax. This currently
  632. excludes the busybox versions of these applications.
  633. The following are supported 'part' options:
  634. --size: The minimum partition size. Specify an integer value
  635. such as 500. Multipliers k, M ang G can be used. If
  636. not specified, the size is in MB.
  637. You do not need this option if you use --source.
  638. --fixed-size: Exact partition size. Value format is the same
  639. as for --size option. This option cannot be
  640. specified along with --size. If partition data
  641. is larger than --fixed-size and error will be
  642. raised when assembling disk image.
  643. --source: This option is a wic-specific option that names the
  644. source of the data that will populate the
  645. partition. The most common value for this option
  646. is 'rootfs', but can be any value which maps to a
  647. valid 'source plugin' (see 'wic help plugins').
  648. If '--source rootfs' is used, it tells the wic
  649. command to create a partition as large as needed
  650. and to fill it with the contents of the root
  651. filesystem pointed to by the '-r' wic command-line
  652. option (or the equivalent rootfs derived from the
  653. '-e' command-line option). The filesystem type
  654. that will be used to create the partition is driven
  655. by the value of the --fstype option specified for
  656. the partition (see --fstype below).
  657. If --source <plugin-name>' is used, it tells the
  658. wic command to create a partition as large as
  659. needed and to fill with the contents of the
  660. partition that will be generated by the specified
  661. plugin name using the data pointed to by the '-r'
  662. wic command-line option (or the equivalent rootfs
  663. derived from the '-e' command-line option).
  664. Exactly what those contents and filesystem type end
  665. up being are dependent on the given plugin
  666. implementation.
  667. If --source option is not used, the wic command
  668. will create empty partition. --size parameter has
  669. to be used to specify size of empty partition.
  670. --ondisk or --ondrive: Forces the partition to be created on
  671. a particular disk.
  672. --fstype: Sets the file system type for the partition. These
  673. apply to partitions created using '--source rootfs' (see
  674. --source above). Valid values are:
  675. vfat
  676. msdos
  677. ext2
  678. ext3
  679. ext4
  680. btrfs
  681. squashfs
  682. swap
  683. --fsoptions: Specifies a free-form string of options to be
  684. used when mounting the filesystem. This string
  685. will be copied into the /etc/fstab file of the
  686. installed system and should be enclosed in
  687. quotes. If not specified, the default string is
  688. "defaults".
  689. --label label: Specifies the label to give to the filesystem
  690. to be made on the partition. If the given
  691. label is already in use by another filesystem,
  692. a new label is created for the partition.
  693. --use-label: This option is specific to wic. It makes wic to use the
  694. label in /etc/fstab to specify a partition. If the
  695. --use-label and --use-uuid are used at the same time,
  696. we prefer the uuid because it is less likely to cause
  697. name confliction. We don't support using this parameter
  698. on the root partition since it requires an initramfs to
  699. parse this value and we do not currently support that.
  700. --active: Marks the partition as active.
  701. --align (in KBytes): This option is specific to wic and says
  702. to start a partition on an x KBytes
  703. boundary.
  704. --no-table: This option is specific to wic. Space will be
  705. reserved for the partition and it will be
  706. populated but it will not be added to the
  707. partition table. It may be useful for
  708. bootloaders.
  709. --exclude-path: This option is specific to wic. It excludes the given
  710. relative path from the resulting image. If the path
  711. ends with a slash, only the content of the directory
  712. is omitted, not the directory itself. This option only
  713. has an effect with the rootfs source plugin.
  714. --extra-space: This option is specific to wic. It adds extra
  715. space after the space filled by the content
  716. of the partition. The final size can go
  717. beyond the size specified by --size.
  718. By default, 10MB. This option cannot be used
  719. with --fixed-size option.
  720. --overhead-factor: This option is specific to wic. The
  721. size of the partition is multiplied by
  722. this factor. It has to be greater than or
  723. equal to 1. The default value is 1.3.
  724. This option cannot be used with --fixed-size
  725. option.
  726. --part-name: This option is specific to wic. It specifies name for GPT partitions.
  727. --part-type: This option is specific to wic. It specifies partition
  728. type GUID for GPT partitions.
  729. List of partition type GUIDS can be found here:
  730. http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs
  731. --use-uuid: This option is specific to wic. It makes wic to generate
  732. random globally unique identifier (GUID) for the partition
  733. and use it in bootloader configuration to specify root partition.
  734. --uuid: This option is specific to wic. It specifies partition UUID.
  735. It's useful if preconfigured partition UUID is added to kernel command line
  736. in bootloader configuration before running wic. In this case .wks file can
  737. be generated or modified to set preconfigured parition UUID using this option.
  738. --fsuuid: This option is specific to wic. It specifies filesystem UUID.
  739. It's useful if preconfigured filesystem UUID is added to kernel command line
  740. in bootloader configuration before running wic. In this case .wks file can
  741. be generated or modified to set preconfigured filesystem UUID using this option.
  742. --system-id: This option is specific to wic. It specifies partition system id. It's useful
  743. for the harware that requires non-default partition system ids. The parameter
  744. in one byte long hex number either with 0x prefix or without it.
  745. --mkfs-extraopts: This option specifies extra options to pass to mkfs utility.
  746. NOTE, that wic uses default options for some filesystems, for example
  747. '-S 512' for mkfs.fat or '-F -i 8192' for mkfs.ext. Those options will
  748. not take effect when --mkfs-extraopts is used. This should be taken into
  749. account when using --mkfs-extraopts.
  750. * bootloader
  751. This command allows the user to specify various bootloader
  752. options. The following are supported 'bootloader' options:
  753. --timeout: Specifies the number of seconds before the
  754. bootloader times out and boots the default option.
  755. --append: Specifies kernel parameters. These will be added to
  756. bootloader command-line - for example, the syslinux
  757. APPEND or grub kernel command line.
  758. --configfile: Specifies a user defined configuration file for
  759. the bootloader. This file must be located in the
  760. canned-wks folder or could be the full path to the
  761. file. Using this option will override any other
  762. bootloader option.
  763. Note that bootloader functionality and boot partitions are
  764. implemented by the various --source plugins that implement
  765. bootloader functionality; the bootloader command essentially
  766. provides a means of modifying bootloader configuration.
  767. * include
  768. This command allows the user to include the content of .wks file
  769. into original .wks file.
  770. Command uses the following syntax:
  771. include <file>
  772. The <file> is either path to the file or its name. If name is
  773. specified wic will try to find file in the directories with canned
  774. .wks files.
  775. """
  776. wic_help_help = """
  777. NAME
  778. wic help - display a help topic
  779. DESCRIPTION
  780. Specify a help topic to display it. Topics are shown above.
  781. """