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

include <bpkg/configuration.cli>;

"\section=1"
"\name=bpkg-pkg-build"
"\summary=build package"

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

    "\h|SYNOPSIS|

     \c{\b{bpkg pkg-build}|\b{build} [<options>] (<pkg>[/<ver>] | <file> | <dir>/)...}

     \h|DESCRIPTION|

     The \cb{pkg-build} command builds one or more packages including all their
     prerequisites. Besides building new packages, this command is also used to
     upgrade or downgrade packages that already exists in the configuration.

     Each package can be specified as just the name (<pkg>) with optional
     package version (<ver>) in which case the package will be automatically
     fetched from one of the repositories. See the \l{bpkg-cfg-add(1)} and
     \l{bpkg-cfg-fetch(1)} commands for more information on package
     repositories. If <ver> is not specified, then the latest available
     version will be built. To downgrade, the desired version must be
     specified explicitly.

     Alternatively, the package can be specified as either the path to the
     package archive (<file>) or to the package directory (<dir>/; note that
     it must end with a directory separator). See the \l{bpkg-pkg-fetch(1)}
     and \l{bpkg-pkg-unpack(1)} commands for more information on the semantics
     of specifying the package as an archive or a directory.

     Packages that are specified explicitly on the command line will be
     \i{held}, that is, they will not be considered for automatic removal if
     they no longer have any dependents. Packages that are specified with the
     explicit package version (<ver>) or as an archive or directory, will, in
     addition, have their versions held, that is, they will not be
     automatically upgraded.

     The \cb{pkg-build} command also supports several options (described
     below) that allow you to control the amount of work that will be done."
  }

  class pkg_build_options: configuration_options
  {
    "\h|PKG-BUILD OPTIONS|"

    bool --yes|-y
    {
      "Assume the answer to all prompts is \cb{yes}."
    }

    bool --drop-prerequisite|-D
    {
      "Drop without confirmation prerequsite packages that were automatically
       built and will no longer be necessary."
    }

    bool --keep-prerequisite|-K
    {
      "Don't offer to drop prerequsite packages that were automatically built
       and will no longer be necessary."
    }

    bool --update-dependent|-U
    {
      "Update without confirmation dependent packages that are reconfigured
       due to their prerequisites being upgraded or downgraded."
    }

    bool --leave-dependent|-L
    {
      "Don't offer to update dependent packages that are reconfigured due to
       their prerequisites being upgraded or downgraded."
    }

    bool --print-only|-p
    {
      "Print to \cb{STDOUT} what would be done without actually doing
       anything."
    }

    bool --configure-only|-c
    {
      "Configure all the packages but don't update."
    }
  };
}