Provided by: dh-debputy_0.1.28_all 
NAME
debputy - Manifest style Debian-based package builder
SYNOPSIS
debputy [general options ] command ... [ command options ]
debputy migrate-from-dh [--apply-changes]
[--acceptable-migration-issues=issue[,issue,...]]
debputy check-manifest [--debputy-manifest=path/to/debputy.manifest]
debputy annotate-packaging-files
debputy lint
debputy lsp editor-config NAME
debputy lsp server [--tcp|--ws [--host BIND-ADDRESS] [--port PORT]]
DESCRIPTION
The debputy program is a manifest style Debian-based package builder. This man page
documents some of the user facing commands.
If you are using debputy with a screen reader, consider setting the environment variable
OPTIMIZE_FOR_SCREEN_READER to 1. This will make many debputy commands remove a lot of
irrelevant visual rendering. Especially ASCII art style rendering that will just be
annoying to listen to. Additionally, some output will be described with text to replace
the visual rendering.
Commands
check-manifest
The check-manifest command will cause debputy to parse the manifest and examine it for
obvious mistakes.
Note that the command will not catch all mistakes as some problems can only be
detected during a build. As an example, check-manifest can detect mistyped manifest
variables but not typos in path names for installation rules.
migrate-from-dh
The migrate-from-dh command will attempt to migrate the current package to debputy.
For this command to be successful, it must be run from the root of an unpacked Debian
source package and the package should be using the dh sequencer.
If you are looking to migrate to debputy from dh, you may want to have a look at the
GETTING-STARTED-WITH-dh-debputy.md file (in the source root or in /usr/share/doc/).
That document is a how-to guide that as extended advice on migration from dh.
The migration can rerun with newer version of debputy that might provide more features
since the previous one even inside the same level of adoption. As an example,
debputy/0.1.21 added support for automatic relationship substvars. Re-running the
migrator for an already migrated package can be used to detect any unnecessary
explicit relationship substvars as unnecessary.
The default migration target is based on existing features in the packaging where
present. As an example, a build-dependency on dh-sequence-zz-debputy-rrr will make the
migration tool only run migrators relevant for dh-sequence-zz-debputy-rrr (assuming no
other markers are present). If the migration cannot identify any target markers, it
has a built-in default target. The default target will change over time as debputy and
the migrator mature. The --migration-target option can be used to overrule this
automatic detection. This can be useful both to expand on the migration level without
performing any changes or to choose a non default initial migration level.
Generally, the migration tool can take you from "less adoption" towards "more
adoption" of debputy but not the inverse. As an example, migrating from dh-sequence-
zz-debputy-rrr towards dh-sequence-zz-debputy is supposed, but the reverse is not. Use
of version control is recommended for undoing transition if necessary.
If any migrations involve creating a new or changing an existing
debian/debputy.manifest, the migration tool will first write a draft to
debian/debputy.manifest.new. From there, it may be renamed to debian/debputy.manifest
automatically depending on --apply-changes or --no-apply-changes.
It supports the following options:
--migration-target TARGET-NAME
Explicitly define how far the migration should go. This will override the detected
or built-in default as the desired migration target.
See "INTEGRATION LEVELS" for details about the concrete levels of integration that
can be used.
--acceptable-migration-issues NAME[,...,NAME], --acceptable-migration-issues=ALL
The migration may detect unsupported features in the package. Some, but not all,
of these can be reduced to a warning by passing --acceptable-migration-issues with
the name of the issue as provided in the error message. The special value ALL in
all upper case will cause all issues that can be reduced to a warning to be
reduced to a warning.
This is only useful to reduce issues to warnings if you are reasonable sure that
you can remove the feature or convert it to something that debputy supports.
In some cases, it might be helpful to comment out the offending feature and re-run
the migration rather than using --acceptable.migration-issues. As an example, if a
single line of debian/install file is problematic, commenting it out will have
debputy migrate the rest of the file for you leaving you only to manually migrate
a single line.
--apply-changes, --no-act, --no-apply-changes
These options decide whether the migration tool should perform destructive actions
such as overwriting the existing debian/debputy.manifest and deleting packaging
files that have successfully migrated.
The default is currently to not perform destructive actions as the migration tool
does not detect version control systems. If support for detecting version control
systems is added, this default may change.
Note that the migration may replace debian/debputy.manifest.new regardless of this
option as that is its output for the updated draft manifest.
The --no-act is an alias of --no-apply-changes to match the name that debhelper
commands use.
lint
Note: This subcommand needs optional dependencies to work from Recommends or Suggests
Run the linting tooling for Debian packaging files. This will run a linter to check
the Debian packaging files. This command is useful for CI or for when you cannot use
the language server feature. It provides the same diagnostics as debputy lsp server
would but without requiring an LSP capable editor as intermediate. The output is only
intended for human consumption. Machine readable is not a goal at this time.
Note that at the time of writing, the debputy.manifest file is only partially
supported. If you have debian/debputy.manifest, please also run debputy check-manifest
to get more thorough checks for that file for now. The lint command will inform you
about this issue in the output if a debian/debputy.manifest file is detected.
Some relevant options for this subcommand include:
--auto-fix
If debputy is aware of one "obvious" solution to the issue, just apply it. This
will apply the changes directly to the file. Use of version control for the Debian
packaging is recommended when using this option in case you want to undo the
result.
--spellcheck
Include spellchecking in the linting results. These are by default omitted, since
they are slower and there are often false-positives.
Caveat: Currently, --auto-fix with --spellcheck will auto-correct all spelling
mistakes with a single correction available. This can be suboptimal behaviour in
some cases and therefore combing these options are not always recommended.
--linter-exit-code, --no-linter-exit-code
There is a convention among linter tools to return a non-zero exit code for
"severe issues". The --linter-exit-code will enforce this behaviour while the
--no-linter-exit-code will disable it.
The debputy program will use exit code 2 for "severe issue" as a "linter exit
code" when linting based exit codes are active.
Not having a linter based exit code can be useful if you want to run the tool
programmatically to display the results and you only want the exit code to tell
whether there was a problem providing the results.
If you rely on the exit code, you are recommended to explicitly pass the relevant
variant of the flag even if the current default matches your wishes.
A short comparison of debputy lint vs. other tools:
debputy lsp server
The language server feature from debputy lsp server provides an interactive and
online version of the linting from debputy lint directly in any LSP capable editor
with the proper glue configuration. The LSP feature gives you instant
gratification, some additional editor-only features and interactive choices of
available quickfixes.
The "downside" of the debputy lsp server feature is that it requires a LSP capable
editor and each editor has their own glue configuration. Since the debputy
language server is new, almost no editor has built-in glue configuration meaning
it has a steeper learning curve to get started. Additionally, some times you want
the checks for CI checks or the current state of the package without having to
open each file in an editor. Here debputy lint covers the same issues without the
need for anything else.
lintian
The primary difference between the debputy linter and lintian is that lintian
works on "binary" artifacts. Even the source checks of lintian checks the packaged
version of the source rather than the files you are directly working. This means
that you have to do a package "build" for lintian to spot any changes, which
causes slow feedback loops. Additionally, debputy lint can provide feedback
regardless of whether your package can currently build. Accordingly, you can get
help and hints even for problems that would prevent a package build. By nature of
how lintian works, you can only get hints from lintian on matters that does not
break the package build.
On the flip side, because lintian is checking the assembled artifacts, it can
check for issues that are only visible after a package build. Additionally,
lintian also checks for issues in the upstream sources to some extent. Checking
upstream artifacts and the resulting Debian packages are not in scope for debputy
lint as the debputy lint is intended to be a mirror of the language server
diagnostics.
In summary: Use debputy lint (or debputy lsp server) for short feedback loops. Use
lintian for slower but more thorough checks on resulting packages.
lintian-brush
The lintian-brush has a broader scope than debputy lint. If you are a happy
lintian-brush user, odds are that debputy lint will not do a lot for you. Though,
debputy lsp server might still be relevant as the language server provides
additional editor related features.
lsp server
Note: This subcommand needs optional dependencies to work from Recommends or Suggests
Start the debputy language server (per Language Server Protocol specification).
Many modern editors can delegate language support to a Language Server or indirectly
via other features like supporting youcompleteme (which in turn can delegate to a
language server). The debputy tool provides one for many common packaging formats via
the lsp server subcommand for file formats such as debian/control, debian/changelog
and debian/copyright (DEP-5).
You will often need some editor specific glue configuration to link a given file
format or name to the language server. The debputy lsp editor-config might provide an
example glue snippet for your editor. In that glue configuration, you will need to
provide a command. Often, debputy lsp server will suffice (using the stdio transport).
See debputy lsp server --help for other integration options such as TCP (--tcp) or
websocket (--ws) plus related supporting options.
If you need to debug an issue with the language server, the TCP integration (--tcp)
can be quite helpful. In this mode, you run debputy lsp server --tcp in a terminal
before starting your editor. This means you have direct and unfiltered access to the
debputy command and its output. Remember to update your editor to use TCP integration
rather than stdio integration (and remember to swap back when you are done). Check the
debputy lsp server --help if you need a different bind address for the language
server.
If you can choose the language ID for a given file, you are recommended to use the
file name relative to the source root (such as debian/control). The service does
account for some known variations such as debian-control (as used by eglot from emacs)
and debcontrol (as used by vim). See debputy lsp features for a list of known language
IDs along with their aliases.
When properly set up, the language server will offer a variety of features such as:
- Completion suggestion such as field names or values in deb822 based files.
- Hover documentation for fields in deb822-based files.
- Diagnostics ("linting"). In many cases, debputy will also provide quickfixes for
the issues.
This feature is also (partly) available via the debputy lint command. The primary
limitation in debputy lint is that you cannot interactively choose which quickfix
to apply.
- On save actions (currently only "prune trailing whitespace").
- Folding ranges (multi-line comments).
Note these features are subject to the editor supporting them, correct language IDs
being passed to debputy, etc.
lsp editor-config EDITOR
Provide an example configuration glue for using the debputy lsp server with the given
editor if known.
The snippets are maintained on a basis effort basis for editors without built-in
config glue for the debputy lsp server. Please file an issue (or a merge request) at
<https://salsa.debian.org/debian/debputy> if a snippet needs to be updated, added or
removed.
lsp features
List in a human readable format details about what language IDs are handled by the
debputy lsp server along with what features are provided for each file format/language
ID.
tool-support
These commands are intended for other tools to consume the output. Output is generally
JSON by default or supported via --output-format=json.
export-reference-data [DATASET]
The export-reference-data command export reference data. If provided, only the
named dataset will be exported. Otherwise, all datasets will be exported.
The reference data includes descriptions of the keywords used in the data set,
which is helpful to understand the data.
supports-tool-command <COMMAND>
Tests whether debputy knows about the named command. Returns successfully if known
and unsuccessfully if not known.
annotate-debian-directory
The annotate-debian-directory command will make debputy scan the debian/ directory
for known packaging files and annotate them with information.
Identifying known packaging files is done on a best effort basis and debputy has
the following sources of information:
Data from plugins
Any installed debputy plugin can provide data about known packaging files.
Most of debputy's "built-in" rules are stored in the debputy-documentation or
the debhelper-documentation plugin. These are installed in
/usr/share/debputy/debputy/plugins/ by default. If any of the data in there is
wrong, please file a bug or a bug against the package providing the data
(often debputy or debhelper).
If the plugin provides the relevant data, debputy will expose install-pattern
and install-path, which are best-effort guesses for the file is installed (or
where files listed in it will be installed). Please check the config-features
and file-categories for the file to see when these field are applicable (and
which case it is).
Note that some files can be matched multiple times. As an example
debian/changelog and debian/copyright will generally appear once per package,
because they are installed in each package.
Dynamic data from debhelper(7) (via dh_assistant(1)>)
Additionally, debputy will ask dh_assistant to resolve all relevant helper
commands and their relevant config snippets. This data will be cross
referenced with the plugin provided data where possible. This will detect
files that debputy (and its plugins) does not know about, but it cannot
provide any additional information.
This part requires debhelper (= 13.12~)> to work fully. With older versions,
the output will include am issues denoting that dh_assistant returned non-
zero.
When dh_assistant list-guessed-dh-config-files is missing a file, it is
typically because the command that uses that config file is not
introspectable. Typically, that can be fixed by patching the command to
include a command line a la:
# INTROSPECTABLE: CONFIG-FILES pkgfile(foo)
Assuming the command uses pkgfile($package, "foo") from
Debian::Debhelper::Dh_Lib to look up the config file.
Notable case that will never work is debian/foo.service where there is no foo
package in debian/control but debian/rules calls dh_installsystemd --name foo.
This holds equally for all debhelper config files and related commands.
plugin list [TOPIC]
plugin show TOPIC identifier
These commands provides access to features that are provided by plugins (Note: many
debputy features are plugin provided, so these commands also covers a lot of "built-
in" features).
These commands will access features of all plugins 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.
Many of the list subcommands also provide a csv format. Note this output is not
intended for scripting as the output is subject to change - both in form of format
availability and content. The csv output is intended as an aid to users of screen
readers for which csv files are easier to deal with than visually rendered tables. If
you need a stable format of some particular output, please file a feature request at
<https://salsa.debian.org/debian/debputy/-/issues> or via reportbug debputy.
You can use debputy plugin list --help and debputy plugin show --help to see which
topics are applicable for each subcommand.
Noteworthy topics include:
plugins
This topic provides a listing of all plugins that debputy is aware of.
This topic can only used with plugin list and not with plugin show.
pluggable-manifest-rules (aliases: pmr, p-m-r)
The debputy manifest provides a number of places where the packager can provide a
number of different rules such as install vs. install-doc vs. install-examples
under installations:. These are called pluggable manifest rules and this topic
provides insights to which rules are available where.
When used with list, debputy will list all pluggable manifest rules available.
When used with show, a rule name must be provided and 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 pluggable-manifest-rules install
When a rule name is ambiguous, debputy will ask that you use rule-type::rule-name
instead of just rule-name. As an example:
debputy plugin show pluggable-manifest-rules TransformationRule::remove
debputy plugin show pluggable-manifest-rules DpkgMaintscriptHelperCommand::remove
Note the type names (such as TransformationRule) are currently an implementation
detail and may change in the future.
packager-provided-files (aliases: ppf, p-p-f)
This topic provides details about all "packager provided files". Packager provided
files can be put into debian from where debputy will pick them up and install them
somewhere in the package. While this command shows all possible variants (by their
stems), the used-packager-provided-files topic will list real files matched.
When used with list, debputy will list all the packager provided files that
debputy knows about. When used with show, some additional details will be given.
In a few cases, the packager provided file will be processed first (as an example
debian/symbols will be passed to dpkg-gensymbols and the processed version will
then be installed instead).
used-packager-provided-files (aliases: uppf, u-p-p-f)
This topic provides a list of all packager provided files used in this source
package. This topic differs from packager-provided-files in that it only shows
files in actual use whereas the other topic lists all known stems.
The listing will potentially include files that debputy could have picked up, but
will not do so during a package build because the relevant plugin is not
explicitly requested (typically via a Build-Depends). These cases are placed in a
separate table and will be clearly marked.
This topic can only used with plugin list and not with plugin show.
This topic only works when the command is run from the root of an unpacked Debian
source package (as debputy needs to read debian/control and scan the debian/
directory).
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 dpkg-gencontrol), generate maintscript snippets, or/and declare triggers.
This topic can only used with plugin list and not with plugin show.
manifest-variables
This topic covers 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
debputy plugin list manifest-variables --help to see the filter options).
When used with show VARIABLE, 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 plugin provided variables. Any manifest
variables provided directly in the manifest is not covered by these commands.
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 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
type-mappings
This topic cover type mappings that explains how some non-trivial types are
interpreted. These covers types like FileSystemMatchRule and FileSystemMode, which
are used by other features such as pluggable manifest rules.
When used with show NAME, any plugin provided documentation and example inputs
will be displayed for that rule.
autopkgtest-test-runner
The autopkgtest-test-runner command is intended to be used by autodep8 or from
autopkgtests to run the tests of plugins in installed mode.
internal-command
This is for internal-only usage only. Any subcommand under internal-command may
disappear or change options between any release without any warning.
GENERAL OPTIONS
The following options general options or root level options are available.
-h, --help
Print usage information and exits.
The information printed depends on which subcommands appear prior to this option.
--version
Prints version information and exists.
Cannot be used with subcommands.
-d, --debug
Enable debug logging and raw stack traces on errors.
Some warnings become errors as a consequence.
--no-pager
Some subcommands will in their default output format pipe it to a pager to give you a
more pleasant experience if standard out is a terminal. Examples include many of the
plugin list commands. This option will disable the pager feature.
Most option formats via --output-format will imply --no-pager as well for subcommands
that support that option.
Note: Assuming the environment has no pager configuration at all, debputy will use
less(1) with the LESS environment variable set to -FRMQSX. Notable, the -F option will
cause less to immediately terminate if the output fits on the screen.
--plugin REQUIRED_PLUGIN
This option causes REQUIRED_PLUGIN to be loaded as a part of the commands execution if
the command needs to load plugin data. For commands that load all plugins by default,
this option causes the command to fail if REQUIRED_PLUGIN cannot be loaded. For
commands that are restrictive about which plugins are loaded, subcommand will load
REQUIRED_PLUGIN in addition other plugins that would normally be loaded.
The REQUIRED_PLUGIN can either be a plugin name or a filename. The debputy program
considers parameter with a forward slash as a filename. Otherwise, the parameter is
interpreted as a plugin name. When given a plugin name, debputy will search for the
plugin in its plugin search path and load it from there. When given a file name,
debputy will read that file as a plugin and use the basename minus any .json or
.json.in extension as the plugin name.
For packages that need a plugin that they provide themselves during their build
process, this option can be useful to tell debputy about it. For the build itself,
usually you want to use dh_debputy --plugin path/to/plugin.json. But this option can
still be useful for debputy check-manifest etc.
The other use-case is to load a plugin not installed into the plugin search
directories. Notably, you can use this to shadow an existing plugin, which can be
useful for debugging and developing your plugin changes.
This option cannot be used with bundled plugins. As an example, both --plugin debputy
and --plugin path/to/a/debputy.json will result in an error.
--debputy-manifest FILE
If the command needs to parse a manifest, have it read FILE instead of
debian/debputy.manifest.
Note this is mostly for testing as other features might not work correctly if the
manifest is not aligned with the current working directory.
FILES
debian/debputy.manifest
Please see /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
/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 cannot use debian/package.debputy.manifest to provide
a specialized manifest for package. Instead, all the needed parts should be written
into the manifest itself.
The --debputy-manifest option can be used to have debputy process manifest other than
debian/debputy.manifest, which may be useful for testing or running debputy check-
manifest but not much else.
INTEGRATION LEVELS
The debputy has multiple levels of integrations, which defines how much of the packaging
that debputy is handling relative to the default dh sequence. The following integrations
levels are available:
dh-sequence-zz-debputy-rrr
This integration level replaces the minimal number of commands necessary to provide
Rules-Requires-Root: no support for any package (even those needing static ownership).
The sequence is often compatible with other debhelper sequences. To use this debputy
integration level, any custom file ownership and mode should be migrated to the
debian/debputy.manifest. Custom binary package version (-v to dpkg-gencontrol) is
supported via the manifest.
This migration level corresponds to a Build-Depends on dh-sequence-zz-debputy-rrr.
The following debhelper commands are removed:
- dh_fixperms
- dh_shlibdeps
- dh_gencontrol
- dh_md5sums
- dh_builddeb
Note the following debputy features are disabled in this integration mode:
- Installation rule (the installations keyword in the manifest). Any installation of
content that should go resulting .deb or .udeb should happen via debhelper's
mechanisms such as dh_install.
- Metadata detectors from plugins. Instead, substvars, maintscripts and triggers are
handled and generated per debhelper conventions.
dh-sequence-zz-debputy
With this integration level, debputy will take over all installation of files into the
packages. This will replace basically all commands after the dh_auto_install command
in the standard dh sequence. This also makes the integration level incompatible with
many debhelper add-ons, since they expect to run after dh_auto_install and assume
contents will be materialized into debian/package.
This migration level corresponds to a Build-Depends on dh-sequence-debputy or dh-
sequence-zz-debputy.
SEE ALSO
dh_debputy(1)
AUTHOR
Niels Thykier <niels@thykier.net>