1 files changed, 175 insertions, 0 deletions
diff --git a/dh_debputy b/dh_debputy
new file mode 100755
index 0000000..4b9edee
--- /dev/null
+++ b/dh_debputy
@@ -0,0 +1,175 @@
+#!/usr/bin/perl
+
+=encoding UTF-8
+
+=head1 NAME
+
+dh_debputy - build Debian binary packages using debputy
+
+=cut
+
+use strict;
+use warnings;
+use Debian::Debhelper::Dh_Lib;
+
+our $VERSION = DH_BUILTIN_VERSION;
+
+=head1 SYNOPSIS
+
+B<dh_debputy> [S<I<debhelper options>>] [B<--destdir=>I<directory>] [S<B<--> I<params>>]
+
+=head1 DESCRIPTION
+
+B<dh_debputy> is a tool for integrating B<debputy> with debhelper as an interim solution
+until B<debputy> covers enough features to be a standalone packaging tool.
+
+The B<debputy> toolstack can built I<any> deb without requiring root or fakeroot.  It is
+always possible to use B<Rules-Requires-Root: no> with B<dh_debputy>/B<debputy> (given no
+non-debputy parts of F<debian/rules> or the upstream build system require root).
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<--destdir=>I<directory>
+
+Use this if you want the generated F<.deb> files to be put in a directory
+other than the default of "F<..>".
+
+=item B<--plugin=>I<name>
+
+Have `debputy` load the given I<name>.  The I<name> can be a name, in which case
+the plugin must be installed into the proper plugin path (and in that case, you can
+I<often> just have a build dependency on B<< debputy-plugin-I<name> >> ).
+
+Alternatively, the I<name> can be a path (must contain B</> and should end with
+B<.json> or B<.json.in>).  In this case, that file is loaded as a plugin.  This
+case is useful for plugin providers to use their own plugin.
+
+=item B<--> I<params>
+
+Pass I<params> to L<dpkg-deb(1)> when it is used to build the
+package.
+
+Restrict I<params> to compression options as the B<dpkg-deb> options may be
+emulated and not all of the B<dpkg-deb> parameters are supported.
+
+=back
+
+=head1 FILES
+
+=over 4
+
+=item F<debian/debputy.manifest>
+
+Please see F</usr/share/doc/dh-debputy/MANIFEST-FORMAT.md.gz>.
+
+If you are converting your first package, you may want to read
+F</usr/share/doc/dh-debputy/GETTING-STARTED-WITH-dh-debputy.md.gz> first.
+
+Unlike most debhelper like tools, this file is per source package rather than
+per binary package.  Therefore, you I<cannot> use F<< debian/I<package>.debputy.manifest >>
+to provide a specialized manifest for I<package>.  Instead, all the needed parts
+should be written into the manifest itself.
+
+=back
+
+=cut
+
+my (@plugins, $integration_mode);
+
+init(options => {
+	"destdir=s"          => \$dh{DESTDIR},
+	"plugin=s"           => \@plugins,
+	"integration-mode=s" => \$integration_mode,
+});
+
+# Set the default destination directory.
+if (! defined $dh{DESTDIR}) {
+	$dh{DESTDIR}='..';
+}
+
+my $debputy_cmd = $ENV{'DEBPUTY_CMD'} // 'debputy';
+
+my @debputy_cmdline = ($debputy_cmd);
+for my $plugin (@plugins) {
+	push(@debputy_cmdline, '--plugin', $plugin);
+}
+push(@debputy_cmdline,
+	'internal-command',
+	'dh-integration-generate-debs',
+);
+push(@debputy_cmdline, "--integration-mode=${integration_mode}")
+	if defined($integration_mode);
+for my $package (@{$dh{DOPACKAGES}}) {
+	push(@debputy_cmdline, '-p', $package);
+}
+push(@debputy_cmdline, $dh{DESTDIR});
+if (@{$dh{U_PARAMS}}) {
+	push(@debputy_cmdline, '--', @{$dh{U_PARAMS}});
+}
+doit(@debputy_cmdline);
+
+=head1 ON DEB ASSEMBLY
+
+The B<dh_debputy> will often use B<dpkg-deb> for assembling the output. However, there are a few cases
+where B<dpkg-deb> does not have the required features for 100% rootless assembly and B<debputy> will
+use a different assembly method when needed.  Generally, this special-case only triggers with
+B<Rules-Requires-Root: no> I<and> when using a feature that requires root with B<dpkg-deb> (such as
+static file ownership).
+
+If you experience, that a B<dh_debputy> produced binary via its internal assembly method that
+is B<not> 100% bit-for-bit reproducible with the equivalent B<root> + B<dpkg-deb> built deb
+and that is not caused by an inaccurate manifest in your end, please file a bug.  See the
+subsection L</How to ensure the dpkg-deb assembly method is being used> for how you
+control which assembly method is being used.
+
+By producing exactly the same deb as B<dpkg-deb> would have with B<fakeroot>, we reduce the risk of bugs
+or bad behaviour during installation.
+
+Note that 100% bit-for-bit reproducible is not compared to debhelper.  Packages generated by debputy may
+differ from those built by debhelper. As an example, auto-generated shell snippets for maintainer scripts
+identifies the tool that generated them and it would be wrong for debputy to identify itself as debhelper
+in this case. This in turn creates a minor difference between packages generated by the two tools.
+Consider using B<diffoscope> to compare your B<debhelper> generated deb to your B<debputy> generated debs.
+
+=head2 How to ensure the dpkg-deb assembly method is being used
+
+The B<debputy> tool stack has two assembly methods: B<dpkg-deb> and the internal B<debputy> method.
+
+By default, the B<dpkg-deb> is used. The B<debputy> tool will only switch to its internal method when:
+
+=over 4
+
+=item -
+
+The package uses a feature that requires (fake)root when assembly via B<dpkg-deb>. At the time of
+writing, this is only triggered by having static ownership in the deb (paths where ownership such as
+B<root:tty> is recorded directly in the F<data.tar>), AND
+
+=item -
+
+The package does not run nor permit B<debputy> to use (fake)root.  This part comes down to
+B<Rules-Requires-Root>. When set to B<no>, B<debputy> will automatically fallback to the
+internal method as necessary.
+
+If you would like to avoid using root during package assembly but also do not want a custom
+assembly method, then you can set B<Rules-Requires-Root: debputy/deb-assembly> and B<debputy>
+will always use B<dpkg-deb> for the assembly.  However, depending on your version of B<dpkg-dev>
+you may run into L<#1036865|https://bugs.debian.org/1036865>.  In that case, you will have to
+choose between using classic root (B<Rules-Requires-Root: binary-targets>) or the internal
+rootless assembly method.
+
+=back
+
+=head1 SEE ALSO
+
+L<debhelper(7)>
+
+This program integrates into the debhelper suite.
+
+=head1 AUTHOR
+
+Niels Thykier <niels@thykier.net>
+
+=cut