Bug 12408

Summary:	Update wic documentation to remove outdated "help" references
Product:	[Documentation] Mega Manual	Reporter:	Amber Elliot <amber.n.elliot>
Component:	mega-manual	Assignee:	Michael Opdenacker <michael.opdenacker>
Status:	RESOLVED OBSOLETE	QA Contact:
Severity:	normal
Priority:	Medium+	CC:	randy.macleod, ross.burton
Version:	5.99
Target Milestone:	Future
Hardware:	x86
OS:	Multiple
Whiteboard:
OS type for building Yocto:	---	Type of Regression:	---
Verified:		Documentation change:	Yes (doc changes required)

Description Amber Elliot 2017-12-07 19:13:01 UTC

Documentation fix for bug 12205.

Section 4.13.3 needs to be updated, as "wic help <command>" is no longer valid. The new functionality is:

for standard help output:
wic -h
wic -help
wic help            #left for compatibility reasons only

for command specific help output:
wic <command> -h
wic <command> -help

for canned image and source plugin information:
wic list <image> info

Comment 1 Scott Rifenbark 2017-12-08 22:46:26 UTC

Did this functionality just get changed?  I did a 'git pull' on poky/master and ran 'wic help write' and got well-formatted help for the wic write command.

I don't quite know what is going on here...

Here is an example of 'wic write -h' 

scottrif@scottrif-ThinkPad-T460:~/poky/build$ wic write -h
usage: wic write [-h] [-e EXPAND] [-n NATIVE_SYSROOT] image target

positional arguments:
  image                 path to the wic image
  target                target file or device

optional arguments:
  -h, --help            show this help message and exit
  -e EXPAND, --expand EXPAND
                        expand rules: auto or
                        <partition>:<size>[,<partition>:<size>]
  -n NATIVE_SYSROOT, --native-sysroot NATIVE_SYSROOT
                        path to the native sysroot containing the tools


Here is an example of 'wic help write'

scottrif@scottrif-ThinkPad-T460:~/poky/build$ wic help write


NAME
    wic write - write an image to a device

SYNOPSIS
    wic write <image> <target>
    wic write <image> <target> --expand auto
    wic write <image> <target> --expand 1:100M-2:300M
    wic write <image> <target> --native-sysroot <path>

DESCRIPTION
    This command writes an image to a target device (USB stick, SD card etc)

        $ wic write ./tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.wic /dev/sdb

    The --expand option is used to resize image partitions.
    --expand auto expands partitions to occupy all free space available on the target device.
    It's also possible to specify expansion rules in a format
    <partition>:<size>[-<partition>:<size>...] for one or more partitions.
    Specifying size 0 will keep partition unmodified.
    Note: Resizing boot partition can result in non-bootable image for non-EFI images. It is
    recommended to use size 0 for boot partition to keep image bootable.

    The --native-sysroot option is used to specify the path to the native sysroot
    containing the tools(parted, resize2fs) to use.

Comment 2 Stephen K Jolley 2017-12-14 15:36:18 UTC

Please answer Scott's Question.

Comment 3 Amber Elliot 2018-01-05 18:59:08 UTC

Hi Scott - sorry, I missed your comment when I was on vacation. If you refer to bug 12205, you'll better understand the motivation for this change. What you are seeing is correct; while 'wic help create' seems like it is formatted fine, it is not formatted based on standard command help output and wasn't implemented using the standard tools. Other help outputs were not so readable, so this change unifies the help output to be more standard and helpful. 

However - this bug was created when the pull request for bug 12205 was created, and it seems that this wasn't ever merged, so the changes don't exist on master yet. I'll look into this and see if there is a timeline for merging so the documentation changes can be made.

Comment 4 Amber Elliot 2018-02-05 21:42:52 UTC

Currently just waiting on the patch for 12205 to be accepted, latest version submitted 1/30.

Comment 5 Ross Burton 2024-02-27 20:16:13 UTC

I don't think this is really relevant anymore.