Jelmer Vernooij:
Hi Niels,
[... past correspondence removed ....]
> Part of the challenge here is that I'm still trying to figure out
exactly what we can do here as well.
Hi Jelmer
I have news on what is possible. It is not directly what you asked for,
but I think you will find it interesting.
$ apt satisfy 'debhelper (>= 13.13), dh-debputy (>= 0.1.18)'
$ git clone https://salsa.debian.org/debian/debhelper && cd debhelper
# or another package of choice
$ debputy tool-support annotate-debian-directory
{
"result": [
{
"path": "debian/changelog",
"binary-package": "debhelper",
"file-categories": [
"ppf-file"
],
"documentation-uris": [
"man:dh_installchangelogs(1)"
]
},
{
"path": "debian/copyright",
"binary-package": "debhelper",
"install-path": "/usr/share/doc/debhelper/copyright",
"install-pattern": "usr/share/doc/{owning_package}/copyright",
"file-categories": [
"ppf-file"
],
"documentation-uris": [
"man:dh_installdocs(1)"
]
},
{
"path": "debian/debhelper.docs",
"binary-package": "debhelper",
"install-path": "/usr/share/doc/debhelper",
"config-features": [
"dh-docs-only",
"dh-dollar-subst",
"dh-executable-config",
"dh-filearray",
"dh-install-list-fixed-dest-dir"
],
"install-pattern": "usr/share/doc/{owning_package}",
"file-categories": [
"pkg-helper-config"
],
"documentation-uris": [
"man:dh_installdocs(1)"
]
},
[...]
{
"path": "debian/debhelper.install",
"binary-package": "debhelper",
"config-features": [
"dh-dollar-subst",
"dh-executable-config",
"dh-filedoublearray",
"dh-glob-after-execute",
"dh-install-list-dest-dir-like-dh_install",
"dh-late-glob",
"dh-partial-glob",
"dh-exec-rename"
],
"file-categories": [
"pkg-helper-config"
],
"documentation-uris": [
"man:dh_install(1)"
]
},
[...]
],
"reference-datasets": [
"config-features",
"file-categories"
]
}
# Reference data accessible as JSON via:
$ debputy tool-support export-reference-data --output-format=json
# or in terminal as ASCII art text:
$ debputy tool-support export-reference-data config-features
The output works the "same" whether the package is built using `dh` or
`debputy`. For many files, they will only be tagged if the relevant
helper is active (only applies to dynamically resolved files, static
files like `debian/debputy.manifest` is always tagged even though
debputy is not used). Output for classic debhelper or helper-less
packages is ... not tested at all and probably not helpful. For classic
debhelper, I support it will be okayish but not fully aligned with the
tools used in d/rules. For helper-less, you will probably not get a lot
of useful output.
With this output, you will get insights into:
1) Which files in debian is or might be picked up by some tool. It also
lists (to the Janitor) irrelevant files, because the underlying code
can also be used find documentation for known packaging files.
2) Where a file like debian/pam is installed in the package, `debputy`
will attempt to provide you resolve the path for you assuming it was
given a pattern for it in the `install-path` attribute. Note
especially debian/pam is exciting because the path changes in compat
13 and I think you will like this one. These are tagged with
`ppf-file`
3) With files debian/docs, `debputy` will provide you with the dest
directory for the file (usr/share/doc/<package-name>) via the
`install-path`. Additionally, the `config-features` will enumerate
known tags for the file. The description for these tags are in the
reference data ("config-features").
4) Some files will appear multiple times if they are processed multiple
times (such as, debian/changelog, which will be installed once per
package).
5) `debputy` will resolve *obvious* uses of `dh $@ --with foo` for you.
Sequences in Build-Depends will also be resolved. Sequences not
installed will work but cause reduced data availability and an
"issues" section in the json file (which in some cases will tell you
which sequences are missing, so you can install them and re-run the
tool).
The [debhelper-documentation plugin] is probably the most interesting
source of data for you. Most likely, it will also be the one with the
most omissions/bugs that will annoy you. Feel free to provide patches
for it.
`debputy --plugin ./path/to/debhelper-documentation.json ...` should be
helpful for testing a local copy (shadowing the installed version). If
new rulesets are needed, this will require a patch to `debputy`. Feel
free to file an issue at https://salsa.debian.org/debian/debputy.
One notable omissions are the `dh_installsystemd` helpers because their
use of `package@.foo` violate the `package.foo` patterns, which is super
annoying. Currently, `debputy` does not support those and therefore I
omitted `dh_installsystemd` entirely for now until I heard whether this
was something you wanted to invest in.
Feedback welcome.
Best regards,
Niels
[debhelper-documentation plugin]:
https://salsa.debian.org/debian/debhelper/-/blob/main/debhelper-documentation.json?ref_type=heads
