dpkg-source: Add backend-specific --help options support

This will print source format specific options depending on the
--format version specified.

debian/changelog

@@ -23,6 +23,7 @@ dpkg (1.18.5) UNRELEASED; urgency=medium
     not supported by gcc yet).
   * Check first for build type to short-circuit boolean expressions in
     dpkg-genchanges.
+  * Add source format backend-specific --help options support to dpkg-source.
   * Perl modules:
     - Add new CTRL_REPO_RELEASE control block type to Dpkg::Control.
     - Add new CTRL_COPYRIGHT_HEADER, CTRL_COPYRIGHT_FILES and

man/dpkg-source.1

@@ -123,6 +123,8 @@ It will error out for formats where this operation doesn't mean anything.
 .TP
 .BR \-? ", " \-\-help
 Show the usage message and exit.
+The format specific build and extract options can be shown by using the
+\fB\-\-format\fP option.
 .TP
 .BR \-\-version
 Show the version and exit.

scripts/Dpkg/Source/Package.pm

@@ -447,6 +447,10 @@ sub check_signature {
     }
 }
 
+sub describe_cmdline_options {
+    return;
+}
+
 sub parse_cmdline_options {
     my ($self, @opts) = @_;
     foreach my $option (@opts) {

scripts/Dpkg/Source/Package/V1.pm

@@ -64,6 +64,66 @@ sub init_options {
     $self->{options}{comp_ext} //= compression_get_property('gzip', 'file_ext');
 }
 
+my @module_cmdline = (
+    {
+        name => '-sa',
+        help => N_('auto select original source'),
+        when => 'build',
+    }, {
+        name => '-sk',
+        help => N_('use packed original source (unpack and keep)'),
+        when => 'build',
+    }, {
+        name => '-sp',
+        help => N_('use packed original source (unpack and remove)'),
+        when => 'build',
+    }, {
+        name => '-su',
+        help => N_('use unpacked original source (pack and keep)'),
+        when => 'build',
+    }, {
+        name => '-sr',
+        help => N_('use unpacked original source (pack and remove)'),
+        when => 'build',
+    }, {
+        name => '-ss',
+        help => N_('trust packed and unpacked original sources are same'),
+        when => 'build',
+    }, {
+        name => '-sn',
+        help => N_('there is no diff, do main tarfile only'),
+        when => 'build',
+    }, {
+        name => '-sA, -sK, -sP, -sU, -sR',
+        help => N_('like -sa, -sk, -sp, -su, -sr but may overwrite'),
+        when => 'build',
+    }, {
+        name => '--abort-on-upstream-changes',
+        help => N_('abort if generated diff has upstream files changes'),
+        when => 'build',
+    }, {
+        name => '-sp',
+        help => N_('leave original source packed in current directory'),
+        when => 'extract',
+    }, {
+        name => '-su',
+        help => N_('do not copy original source to current directory'),
+        when => 'extract',
+    }, {
+        name => '-sn',
+        help => N_('unpack original source tree too'),
+        when => 'extract',
+    }, {
+        name => '--skip-debianization',
+        help => N_('do not apply debian diff to upstream sources'),
+        when => 'extract',
+    },
+);
+
+sub describe_cmdline_options {
+    return @module_cmdline;
+}
+
 sub parse_cmdline_option {
     my ($self, $opt) = @_;
     my $o = $self->{options};

scripts/Dpkg/Source/Package/V2.pm

@@ -63,6 +63,58 @@ sub init_options {
     $self->{options}{ignore_bad_version} //= 0;
 }
 
+my @module_cmdline = (
+    {
+        name => '--include-removal',
+        help => N_('include removed files in the patch'),
+        when => 'build',
+    }, {
+        name => '--include-timestamp',
+        help => N_('include timestamp in the patch'),
+        when => 'build',
+    }, {
+        name => '--include-binaries',
+        help => N_('include binary files in the tarball'),
+        when => 'build',
+    }, {
+        name => '--no-preparation',
+        help => N_('do not prepare build tree by applying patches'),
+        when => 'build',
+    }, {
+        name => '--no-unapply-patches',
+        help => N_('do not unapply patches if previously applied'),
+        when => 'build',
+    }, {
+        name => '--unapply-patches',
+        help => N_('unapply patches if previously applied (default)'),
+        when => 'build',
+    }, {
+        name => '--create-empty-orig',
+        help => N_('create an empty original tarball if missing'),
+        when => 'build',
+    }, {
+        name => '--abort-on-upstream-changes',
+        help => N_('abort if generated diff has upstream files changes'),
+        when => 'build',
+    }, {
+        name => '--auto-commit',
+        help => N_('record generated patches, instead of aborting'),
+        when => 'build',
+    }, {
+        name => '--skip-debianization',
+        help => N_('do not extract debian tarball into upstream sources'),
+        when => 'extract',
+    }, {
+        name => '--skip-patches',
+        help => N_('do not apply patches at the end of the extraction'),
+        when => 'extract',
+    }
+);
+
+sub describe_cmdline_options {
+    return @module_cmdline;
+}
+
 sub parse_cmdline_option {
     my ($self, $opt) = @_;
     if ($opt eq '--include-removal') {

scripts/Dpkg/Source/Package/V3/Custom.pm

@@ -27,6 +27,18 @@ use parent qw(Dpkg::Source::Package);
 
 our $CURRENT_MINOR_VERSION = '0';
 
+my @module_cmdline = (
+    {
+        name => '--target-format=<value>',
+        help => N_('define the format of the generated source package'),
+        when => 'build',
+    }
+);
+
+sub describe_cmdline_options {
+    return @module_cmdline;
+}
+
 sub parse_cmdline_option {
     my ($self, $opt) = @_;
     if ($opt =~ /^--target-format=(.*)$/) {

scripts/Dpkg/Source/Package/V3/Git.pm

@@ -71,6 +71,26 @@ sub sanity_check {
     return 1;
 }
 
+my @module_cmdline = (
+    {
+        name => '--git-ref=<ref>',
+        help => N_('specify a git <ref> to include in the git bundle'),
+        when => 'build',
+    }, {
+        name => '--git-depth=<number>',
+        help => N_('create a shallow clone with <number> depth'),
+        when => 'build',
+    }
+);
+
+sub describe_cmdline_options {
+    my $self = shift;
+
+    my @cmdline = ( $self->SUPER::describe_cmdline_options(), @module_cmdline );
+
+    return @cmdline;
+}
+
 sub parse_cmdline_option {
     my ($self, $opt) = @_;
     return 1 if $self->SUPER::parse_cmdline_option($opt);

scripts/Dpkg/Source/Package/V3/Quilt.pm

@@ -45,6 +45,26 @@ sub init_options {
     $self->SUPER::init_options();
 }
 
+my @module_cmdline = (
+    {
+        name => '--single-debian-patch',
+        help => N_('use a single debianization patch'),
+        when => 'build',
+    }, {
+        name => '--allow-version-of-quilt-db=<version>',
+        help => N_('accept quilt metadata <version> even if unknown'),
+        when => 'build',
+    }
+);
+
+sub describe_cmdline_options {
+    my $self = shift;
+
+    my @cmdline = ( $self->SUPER::describe_cmdline_options(), @module_cmdline );
+
+    return @cmdline;
+}
+
 sub parse_cmdline_option {
     my ($self, $opt) = @_;
     return 1 if $self->SUPER::parse_cmdline_option($opt);

scripts/dpkg-source.pl

@@ -521,6 +521,48 @@ sub setopmode {
     $options{opmode} = $opmode;
 }
 
+sub print_option {
+    my $opt = shift;
+    my $help;
+
+    if (length $opt->{name} > 25) {
+        $help .= sprintf "  %-25s\n%s%s.\n", $opt->{name}, ' ' x 27, $opt->{help};
+    } else {
+        $help .= sprintf "  %-25s%s.\n", $opt->{name}, $opt->{help};
+    }
+}
+
+sub get_format_help {
+    $build_format //= '1.0';
+
+    my $srcpkg = Dpkg::Source::Package->new();
+    $srcpkg->{fields}->{'Format'} = $build_format;
+    $srcpkg->upgrade_object_type(); # Fails if format is unsupported
+
+    my @cmdline = $srcpkg->describe_cmdline_options();
+
+    my $help_build = my $help_extract = '';
+    my $help;
+
+    foreach my $opt (@cmdline) {
+        $help_build .= print_option($opt) if $opt->{when} eq 'build';
+        $help_extract .= print_option($opt) if $opt->{when} eq 'extract';
+    }
+
+    if ($help_build) {
+        $help .= "\n";
+        $help .= "Build format $build_format options:\n";
+        $help .= $help_build || g_("<none>");
+    }
+    if ($help_extract) {
+        $help .= "\n";
+        $help .= "Extract format $build_format options:\n";
+        $help .= $help_extract || g_("<none>");
+    }
+
+    return $help;
+}
+
 sub version {
     printf g_("Debian %s version %s.\n"), $Dpkg::PROGNAME, $Dpkg::PROGVERSION;
 
@@ -566,13 +608,15 @@ sub usage {
   --no-check               don't check signature and checksums before unpacking
   --require-valid-signature abort if the package doesn't have a valid signature
   --ignore-bad-version     allow bad source package versions.")
-    . "\n\n" . g_(
+    . "\n" .
+    get_format_help()
+    . "\n" . g_(
 'General options:
   -?, --help               show this help message.
       --version            show the version.')
     . "\n\n" . g_(
-'More options are available but they depend on the source package format.
-See dpkg-source(1) for more info.') . "\n",
+'Source format specific build and extract options are available;
+use --format with --help to see them.') . "\n",
     $Dpkg::PROGNAME,
     get_default_diff_ignore_regex(),
     join(' ', map { "-I$_" } get_default_tar_ignore_pattern()),