// 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> <dir> <vars> <pkg>",

    "\h|SYNOPSIS|

     \c{\b{bpkg pkg-bindist}|\b{bindist} [\b{--output-root}|\b{-o} <dir>] [<options>] [<vars>] <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)}. For some system package managers a directory
     for intermediate files and subdirectories as well as the resulting binary
     package may have to be specified explicitly with the
     \c{\b{--output-root}|\b{-o}} option.

     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. See distribution-specific description sections
     below for details and invocation examples.

     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|DEBIAN DESCRIPTION|

     The Debian binary packages are generated by producing the standard
     \cb{debian/control}, \cb{debian/rules}, and other package metadata files
     and then invoking \cb{dpkg-buildpackage(1)} to build the binary package
     from that. In particular, the \cb{debian/rules} implemenation is based on
     the \cb{dh(1)} command sequencer. While this approach is normally used to
     build packages from source, this implementation \"pretends\" that this is
     what's happening by overriding a number of \cb{dh} targets to invoke the
     \cb{build2} build system on the required packages directly in their
     \cb{bpkg} configuration locations. Typical invocation:

     \
     bpkg build libhello
     bpkg test libhello
     bpkg bindist -o /tmp/output/ libhello
     \

     Note that the \cb{dpkg-dev} (or \cb{build-essential}) and \cb{debhelper}
     Debian packages must be installed before invocation.

     See \l{bpkg#bindist-mapping-debian-produce Debian Package Mapping for
     Production} for details on \cb{bpkg} to Debian package name and version
     mapping.
     "

    "\h|PKG-BINDIST DEBIAN OPTIONS|"

    bool --debian-prepare-only
    {
      "Prepare all the package metadata files (\cb{control}, \cb{rules}, etc)
       but do not invoke \cb{bpkg-buildpackage} to generate the binary
       package, printing its command line instead unless requested to be
       quiet. Implies \cb{--keep-output}."
    }

    string --debian-buildflags = "assign"
    {
      "<mode>",
      "Package build flags (\cb{dpkg-buildflags}) usage mode. Valid <mode>
       values are \cb{assign} (use the build flags instead of configured),
       \cb{append} (use the build flags in addition to configured, putting
       them last), \cb{prepend} (use the build flags in addition to
       configured, putting them first), and \cb{ignore} (ignore build
       flags). The default mode is \cb{assign}. Note that compiler mode
       options, if any, are used as configured."
    }

    strings --debian-maint-option
    {
      "<o>",
      "Alternative options to specify in the \cb{DEB_BUILD_MAINT_OPTIONS}
       variable of the \cb{rules} file. To specify multiple maintainer options
       repeat this option and/or specify them as a single value separated
       with spaces."
    }

    strings --debian-build-option
    {
      "<o>",
      "Additional option to pass to the \cb{dpkg-buildpackage} program. Repeat
       this option to specify multiple build options."
    }

    string --debian-build-meta
    {
      "<data>",
      "Alternative build metadata to include in the binary package version.
       If empty value is specified, then no build metadata is included. By
       default, the build metadata is the \cb{ID} and \cb{VERSION_ID}
       components from \cb{os-release(5)}, for example, \cb{debian10} in
       version \cb{1.2.3-0~debian10}."
    }

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

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

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

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

    string --debian-main-langdep
    {
      "<v>",
      "Override the language runtime dependencies (such as \cb{libc6},
       \cb{libstdc++6}, etc) in the \cb{Depends} \cb{control} file field
       value of the main binary package."
    }

    string --debian-dev-langdep
    {
      "<v>",
      "Override the language runtime dependencies (such as \cb{libc-dev},
       \cb{libstdc++-dev}, etc) in the \cb{Depends} \cb{control} file field
       value of the development (\cb{-dev}) binary package."
    }

    string --debian-main-extradep
    {
      "<v>",
      "Extra dependencies to add to the \cb{Depends} \cb{control} file field
       value of the main binary package."
    }

    string --debian-dev-extradep
    {
      "<v>",
      "Extra dependencies to add to the \cb{Depends} \cb{control} file field
       value of the development (\cb{-dev}) binary package."
    }
  };

  // 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
       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}."
    }

    dir_path --output-root|-o
    {
      "<dir>",
      "Directory for intermediate files and subdirectories as well as the
       resulting binary package. Note that this option may be required for
       some system package managers and may not be specified for others."
    }

    bool --wipe-output
    {
      "Wipe the output root directory (either specified with \ci{--output-root}
       or system package manager-specific) clean before using it to generate
       the binary package."
    }

    bool --keep-output
    {
      "Keep intermediate files in the output root directory (either specified
       with \ci{--output-root} or system package manager-specific) 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
   \
  "
}