// file      : bpkg/pkg-bindist.cli
// license   : MIT; see accompanying LICENSE file

include <bpkg/configuration.cli>;

"\section=1"
"\name=bpkg-pkg-bindist"
"\summary=generate binary distribution package"

namespace bpkg
{
  {
    "<options> <vars> <out-dir> <pkg>",

    "\h|SYNOPSIS|

     \c{\b{bpkg pkg-bindist}|\b{bindist} [<options>] [<vars>] <out-dir> <pkg> [<pkg>...]}

     \h|DESCRIPTION|

     The \cb{pkg-bindist} command generates a binary distribution package for
     the specified package. If additional packages are specified, then they
     are bundled in the same distribution package. All the specified packages
     must have been previously configured with \l{bpkg-pkg-build(1)} or
     \l{bpkg-pkg-configure(1)}. The intermediate files and the resulting
     binary package are created in the <out-dir> directory.

     Underneath, this command roughly performs the following steps: First it
     installs the specified packages similar to the \l{bpkg-pkg-install(1)}
     command except that it may override the installation locations (via the
     \cb{config.install.*} variables) to match the distribution's layout. Then
     it generates any necessary distribution package metadata files based on
     the information from the package \cb{manifest} files. Finally, it invokes
     the distribution-specified command to produce the binary package. Unless
     overrident with the \cb{--architecture} and \cb{--distribution} options,
     the binary package is generated for the host architecture using the
     host's standard system package manager. Additional command line variables
     (<vars>, normally \cb{config.*}) can be passed to the build system during
     the installation step.

     The specified packages may have dependencies and the default behavior is
     to not bundle them but rather to specify them as dependencies in the
     corresponding distribution package metadata, if applicable. This default
     behavior can be overridden with the \cb{--recursive} option (see the
     option description for the available modes). Note, however, that
     dependencies that are satisfied by system packages are always specified
     as dependencies in the distribution package metadata.
     "
  }

  // Place distribution-specific options into separate classes in case one day
  // we want to only pass their own options to each implementation.
  //
  class pkg_bindist_debian_options
  {
    "\h|PKG-BINDIST DEBIAN OPTIONS|"

    string --debian-section
    {
      "<val>",
      "Alternative \cb{Section} field value in the \cb{control} file for
       the main binary package. The default is either \cb{libs} or \cb{devel},
       depending on the package type."
    }

    string --debian-priority
    {
      "<val>",
      "Alternative \cb{Priority} field value in the \cb{control} file. The
       default is \cb{optional}."
    }

    string --debian-maintainer
    {
      "<val>",
      "Alternative \cb{Maintainer} field value in the \cb{control} file. The
       default is the \cb{package-email} value from package \cb{manifest}."
    }

    string --debian-architecture
    {
      "<vl>",
      "Alternative \cb{Architecture} field value in the \cb{control} file for
       the main binary package. The default is \cb{any}."
    }
  };

  // NOTE: remember to add the corresponding `--class-doc ...=exclude-base`
  //       (both in bpkg/ and doc/) if adding a new base class.
  //
  class pkg_bindist_options: configuration_options,
                             pkg_bindist_debian_options
  {
    "\h|PKG-BINDIST COMMON OPTIONS|"

    string --distribution
    {
      "<name>",
      "Alternative system/distribution package manager to generate the binary
       package for. The valid <name> values are \cb{debian} (Debian and
       alike, such as Ubuntu, etc) and \cb{fedora} (Fedora and alike,
       such as RHEL, CentOS, etc). Note that some package managers may
       only be supported when running on certain host operating systems."
    }

    string --architecture
    {
      "<name>",
      "Alternative architecture to generate the binary package for. The
       valid <name> values are system/distribution package manager-specific.
       If unspecified, the host architecture is used."
    }

    string --recursive
    {
      "<mode>",
      "Bundle dependencies of the specified packages. The <mode> value can be
       either \cb{auto}, in which case only the required files from each
       dependency package are bundled, or \cb{full}, in which case all the
       files are bundled. Specifically, in the \cb{auto} mode any required
       files, for example, shared libraries, are pulled implicitly by the
       \cb{install} build system operation, for example, as part of
       installing an executable from one of the specified packages. In
       contrast, in the \cb{full} mode, each dependency package is
       installed explicitly and completely, as if they were specified
       as additional package on the command line. See also the \cb{--private}
       option."
    }

    bool --private
    {
      "Enable the private installation subdirectory functionality using the
       binary package name as the private subdirectory. This is primarily
       useful when bundling dependencies, such as shared libraries, of an
       executable that is being installed into a shared location, such as
       \cb{/usr/}. See the \cb{config.install.private} configuration variable
       documentation in the build system manual for details. This option
       only makes sense together with \cb{--recursive}."
    }

    bool --wipe-out
    {
      "Wipe the output directory (\ci{out-dir}) clean before using it to
       generate the binary package."
    }

    bool --keep-out
    {
      "Keep intermediate files in the output directory (\ci{out-dir}) that
       were used to generate the binary package. This is primarily useful
       for troubleshooting."
    }
  };

  "
   \h|DEFAULT OPTIONS FILES|

   See \l{bpkg-default-options-files(1)} for an overview of the default
   options files. For the \cb{pkg-bindist} command the search start
   directory is the configuration directory. The following options files are
   searched for in each directory and, if found, loaded in the order listed:

   \
   bpkg.options
   bpkg-pkg-bindist.options
   \

   The following \cb{pkg-bindist} command options cannot be specified in the
   default options files:

   \
   --directory|-d
   \
  "
}