# 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)

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