debputy(1) | The debputy Debian packager helper stack | debputy(1) |
debputy - Manifest style Debian-based package builder
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]]
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.
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.
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:
See "INTEGRATION LEVELS" for details about the concrete levels of integration that can be used.
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.
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.
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:
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.
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:
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.
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.
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:
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.
Note these features are subject to the editor supporting them, correct language IDs being passed to debputy, etc.
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.
The reference data includes descriptions of the keywords used in the data set, which is helpful to understand the data.
Identifying known packaging files is done on a best effort basis and debputy has the following sources of information:
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.
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.
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:
This topic can only used with plugin list and not with plugin show.
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.
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).
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).
This topic can only used with plugin list and not with plugin show.
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.
As an example:
debputy plugin show automatic-discard-rules la-files
When used with show NAME, any plugin provided documentation and example inputs will be displayed for that rule.
The following options general options or root level options are available.
The information printed depends on which subcommands appear prior to this option.
Cannot be used with subcommands.
Some warnings become errors as a consequence.
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.
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.
Note this is mostly for testing as other features might not work correctly if the manifest is not aligned with the current working directory.
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.
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:
This migration level corresponds to a Build-Depends on dh-sequence-zz-debputy-rrr.
The following debhelper commands are removed:
Note the following debputy features are disabled in this integration mode:
This migration level corresponds to a Build-Depends on dh-sequence-debputy or dh-sequence-zz-debputy.
dh_debputy(1)
Niels Thykier <niels@thykier.net>
2024-04-10 | perl v5.38.2 |