=encoding UTF-8

=head1 NAME

debputy - Manifest style Debian-based package builder

=head1 SYNOPSIS

B<debputy> [S<I<< general options >> >] B<command ...> [S< I<< command options >> >]

B<debputy> B<migrate-from-dh> [B<--apply-changes>] [B<--acceptable-migration-issues=>I<issue>[,I<issue>,...]]

B<debputy> B<check-manifest> [B<--debputy-manifest=>I<path/to/debputy.manifest>]

=head1 DESCRIPTION

The B<debputy> program is a manifest style Debian-based package builder. This manpage documents some of the
user facing commands.

=head2 Commands

=over 4

=item check-manifest

The B<check-manifest> command will cause B<debputy> to parse the manifest and examine it for obvious mistakes.

Note that the command will I<not> catch all mistakes as some problems can only be detected during a build. As
an example, B<check-manifest> can detect mistyped manifest variables but not typos in path names for
installation rules.

=item plugin list [I<TOPIC>]

=item plugin show B<TOPIC> B<identifier>

These commands provides access to features that are provided by plugins (Note: many B<debputy> features are
plugin provided, so these commands also covers a lot of "built-in" features).

These commands will access features of all plugins B<available> even if the current package will not activate
all of these plugins. Unless otherwise stated, all output is intended to be human readable rather than machine
readable. Formatting may change between any version.

You can use B<debputy plugin list --help> and B<debputy plugin show --help> to see which topics are applicable
for each subcommand.

Noteworthy topics include:

=over 4

=item plugins

This topic provides a listing of all plugins that B<debputy> is aware of.

This topic can only used with B<plugin list> and not with B<plugin show>.

=item plugable-manifest-rules (aliases: pmr, p-m-r)

The B<debputy> manifest provides a number of places where the packager can provide a number of different rules
such as B<install> vs. B<install-doc> vs. B<install-examples> under B<installations:>. These are called
plugable manifest rules and this topic provides insights to which rules are available where.

When used with B<list>, B<debputy> will list all plugable manifest rules available. When used with B<show>,
a rule name must be provided and B<debputy> will then provide details about the rule. These details include
attributes available (where applicable) and any reference documentation provided by the plugin.

As an example, here is how you get the details about the install rule:

    debputy plugin show plugable-manifest-rules install

When a rule name is ambiguous, B<debputy> will ask that you use B<rule-type::rule-name> instead of just B<rule-name>.
As an example:

    debputy plugin show plugable-manifest-rules TransformationRule::remove
    debputy plugin show plugable-manifest-rules DpkgMaintscriptHelperCommand::remove

Note the type names (such as B<TransformationRule>) are currently an implementation detail and may change in the
future.

=item packager-provided-files (aliases: ppf, p-p-f)

This topic provides a listing of all "packager provided files". Packager provided files can be put into F<debian>
from where B<debputy> will pick them up and install them somewhere in the package.

In a few cases, the packager provided file will be processed first (as an example F<debian/symbols> will be passed
to B<dpkg-gensymb ols> and the processed version will then be installed instead).

This topic can only used with B<plugin list> and not with B<plugin show>.

=item metadata-detectors

This topic provides a listing of all "metadata detectors". These are plugin provided code snippets that scan the
final form of the package and add substvars (for B<dpkg-gencontrol>), generate maintscript snippets, or/and
declare triggers.

This topic can only used with B<plugin list> and not with B<plugin show>.

=item manifest-variables

This topic covers B<plugin provided> manifest variables. The listing will list the common manifest variables by
default along with their values in source context (if possible). Some of the special case manifest variables are
hidden by default (use B<debputy plugin list manifest-variables --help> to see the filter options).

When used with B<show VARIABLE>, B<debputy> will list the reference documentation (if provided by the plugin)
related to the value along with a few other details.

As implied above, this will only show B<plugin provided> variables. Any manifest variables provided directly
in the manifest is B<not> covered by these commands.


=item automatic-discard-rules

This topic covers automatic discard rules, which are rules that automatically filters out (discards) sources
from installation rules by default.  The listing will list all the available automatic discard rules. The
B<show RULE> command will show reference documentation and an example of what the rule reacts to (if these
have been provided by the plugin).

As an example:

    debputy plugin show automatic-discard-rules la-files

=back

=item autopkgtest-test-runner

The B<autopkgtest-test-runner> command is intended to be used by B<autodep8> or from autopkgtests to run the
tests of plugins in installed mode.

=item internal-command

This is for internal-only usage only.  Any subcommand under B<internal-command> may disappear or change options
between any release without any warning.

=back

=head1 FILES

=over 4

=item F<debian/debputy.manifest>

Please see F</usr/share/doc/dh-debputy/MANIFEST-FORMAT.md.gz> for details on the format.

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.

The B<--debputy-manifest> option can be used to have B<debputy> process manifest other
than F<debian/debputy.manifest>, which may be useful for testing or running
B<debputy check-manifest> but not much else.

=back

=head1 SEE ALSO

L<dh_debputy(1)>

=head1 AUTHOR

Niels Thykier <niels@thykier.net>

=cut
