// file      : bpkg/pkg-unpack.cli
// copyright : Copyright (c) 2014-2019 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

include <bpkg/configuration.cli>;

"\section=1"
"\name=bpkg-pkg-unpack"
"\summary=unpack package archive"

namespace bpkg
{
  {
    "<options> <pkg> <ver> <dir>",

    "\h|SYNOPSIS|

     \c{\b{bpkg pkg-unpack} [<options>] (<pkg>[\b{/}<ver>] | \b{--existing|-e} <dir>)}

     \h|DESCRIPTION|

     If only the package name is specified, then the \cb{pkg-unpack} command
     unpacks the archive for the previously fetched (\l{bpkg-pkg-fetch(1)})
     package. The resulting package state is \cb{unpacked}
     (\l{bpkg-pkg-status(1)}).

     If the package version is also specified, then the (source) directory
     from one of the directory-based repositories (\l{bpkg-rep-add(1)}) is
     used in place, without copying it into the configuration directory. Such
     a package is called \i{external}.

     If the \cb{--existing|-e} option is used, then instead of the package
     name, \cb{pkg-unpack} expects a local path to an existing package
     directory. In this case, \cb{bpkg} will use the (source) directory in
     place, the same as for packages from directory-based repositories. Also,
     unless the \cb{--purge|-p} option is specified, \cb{bpkg} will not
     attempt to remove this directory when the package is later purged with
     the \l{bpkg-pkg-purge(1)} command. Such a package is also \i{external}.

     If \cb{--existing|-e} is specified together with the \cb{--replace|-r}
     option, then \cb{pkg-unpack} will replace the archive and/or source
     directory of a package that is already in the \cb{unpacked} or
     \cb{fetched} state.

     An external package triggers several changes in semantics compared to a
     normal package: The package (output) directory inside the configuration
     is called just <pkg> rather than <pkg>\cb{-}<ver>. It is also assumed
     that the packaging information (package manifest and lockfile) for such
     packages may change without incrementing the package version (for
     example, during development). To support this, \cb{bpkg} implements the
     \i{package iteration} mechanism which may result in iteration numbers to
     be shown as part of the package version, for example, \cb{1.2.3#1} (see
     \l{bpkg#package-version Package Version})."
  }

  class pkg_unpack_options: configuration_options
  {
    "\h|PKG-UNPACK OPTIONS|"

    bool --existing|-e
    {
      "Treat the argument as an existing package directory path rather than
       the package name to unpack."
    }

    bool --purge|-p
    {
      "Remove the existing package directory when the package is purged."
    }

    bool --replace|-r
    {
      "Replace the source directory if the package is already unpacked or
       fetched. Can only be specified with an external package."
    }
  };
}