# Copyright (C) 2014, 2015 Codethink Limited
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; version 2 of the License.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, see <http://www.gnu.org/licenses/>.

help: |

    Write a system produced by Morph to a physical disk, or to a file that can
    be used as a virtual disk. The target will be formatted as a single Btrfs
    partition, with the system image written to a subvolume in /systems, and
    other subvolumes created for /home, /opt, /root, /srv and /var.

    When written to a physical drive, the drive can be used as the boot device
    for a 'real' machine.

    When written to a file, the file can be used independently of `morph` to
    create virtual machines with KVM / libvirt, OpenStack or, after converting
    it to VDI format, VirtualBox.

    `morph deploy` will fail if the file specified by `location` already
    exists.

    If used in `morph upgrade`, the rootfs produced by 'morph build' is added
    to the existing raw disk image or device as an additional btrfs sub-volume.
    `morph upgrade` will fail if the file specified by `location` does not
    exist, or is not a Baserock raw disk image. (Most users are unlikely to
    need or use this functionality: it is useful mainly for developers working
    on the Baserock tools.)

    Parameters:

    * location: the pathname of the disk image to be created/upgraded, or the
      path to the physical device.

    * VERSION_LABEL=label - should contain only alpha-numeric
      characters and the '-' (hyphen) character. Mandatory if being used with
      `morph update`

    * INITRAMFS_PATH=path: the location of an initramfs for the bootloader to
      tell Linux to use, rather than booting the rootfs directly.

    * DTB_PATH=path: **(MANDATORY)** for systems that require a device tree
      binary - Give the full path (without a leading /) to the location of the
      DTB in the built system image . The deployment will fail if `path` does
      not exist.

    * BOOTLOADER_INSTALL=value: the bootloader to be installed
      **(MANDATORY)** for non-x86 systems

        allowed values =
        - 'extlinux' (default) - the extlinux bootloader will
           be installed
        - 'none' - no bootloader will be installed by `morph deploy`. A
           bootloader must be installed manually. This value must be used when
           deploying non-x86 systems such as ARM.

    * BOOTLOADER_CONFIG_FORMAT=value: the bootloader format to be used.
      If not specified for x86-32 and x86-64 systems, 'extlinux' will be used

        allowed values =
        - 'extlinux'

    * KERNEL_ARGS=args: optional additional kernel command-line parameters to
      be appended to the default set. The default set is:

        'rw init=/sbin/init rootfstype=btrfs \
          rootflags=subvol=systems/default/run \
          root=[name or UUID of root filesystem]'

        (See https://www.kernel.org/doc/Documentation/kernel-parameters.txt)

    * PARTITION_FILE=path: path to a YAML partition specification to use for
      producing partitioned disks or devices. The default specification is
      'partitioning/default' in definitions, which specifies a device with a
      single partition. This may serve as an example of the format of this
      file, or check the pyfdisk.py documentation in pyfdisk.README.

        In addition to the features available in pyfdisk.py, using this
        extension, a list of 'raw_files' items can be added at the partition
        level, or the top level of the partition specification. This specifies
        files to be written directly to the target device or image using `dd`

            start_offset: 2048
            partition_table_format: mbr
            partitions:
            - description: boot
              filesystem: none
              ...
              raw_files:
              - file: boot/uboot.img
            raw_files:
            - file: boot/uboot-env.img
              offset_bytes: 512
            - file: boot/preloader.bin
              skip_bytes: 128
              count_bytes: 16K

        * Files are written consecutively in the order they are listed, and
          sourced from the unpacked root filesystem image
        * Files can be given a specific offset with 'offset_sectors' or
          'offset_bytes'
        * With 'raw_files' specified inside a partition, 'offset_sectors' or
          'offset_bytes' is counted from the start of that partition,
          otherwise from the start of the device.
        * For files without an explicit offset, the next file is written
          starting with the next free byte following the previous file
        * Providing an offset is optional for all files
        * Specifying 'skip_bytes' will set the 'skip=' option for dd, skipping
          a number of bytes at the start of the input file
        * Specifying 'count_bytes' sets the 'count=' option for dd
        * For properties which take an input in bytes, a human-readable
          multiplier can be used, e.g. K, M, G (integer multiplicands only)

    * USE_PARTITIONING=boolean (default: no) Use this flag to enable
      partitioning functions.

    (See `morph help deploy` for details of how to pass parameters to write
    extensions)