[Pkg-rust-maintainers] configure_me man page generation

[Wolfgang Silbermayr]

On 10/18/19 8:24 AM, Martin Habovštiak wrote:

> I'm the author of configure_me (https://github.com/Kixunil/configure_me
> ), a crate that helps with loading application configuration from config
> files, env vars and arguments.
> 
> The crate is capable of generating man pages from the specification. I
> would love to integrate it into Debian ecosystem! I'm now seeking for
> advice on how to do it the best possible way.

Never heard of this crate until now. Looks interesting! Is my
understanding correct that the definition of the configurable fields is
written into a toml file which gets parsed at build time and generates
data structures which are available at runtime?

> Previously the man page was generated by the build script, but after
> some discussion with Rust devs and my own thinking, I decided to
> redesign it and provide a separate tool for generating the man page and
> other files (I plan to do shell completions at some point and I also
> started experimenting with debconf). The tool is nearly finished and I
> plan to release it soon (hopefully today).
> 
> The ideal end result would be if the manpage was generated for all
> dependent packages without any other interaction. I don't think it'd be
> good to tie it to configure_me, but allow other crates to define their
> integrations too. So my idea is this:

So if I understand this correctly, the build script descended into the
dependency tree and collected the configure options of all dependencies?
Or should it just build the artifacts for the crate that is being built?
The latter would of course be much easier to handle (e.g. because
dependencies might get updated and then produce different output than
they did when the crate got built the first time).

> Whenever Cargo.toml contains:
> [package.metadata.debcargo.postbuild-dep]
> crate = foo
> run = { "bar" = ["--arg"] }
> 
> (Alternatively, this could be in debcargo.toml, I'm not sure which is
> better.)
> 
> All it's dependencies will get Build-Depends: foo

In general, we can work with completely custom `debian/rules` files when
using debcargo, which we do in some cases, e.g. to generate manpages by
`help2man`. We define the build-deps in `debcargo.toml`. Until now, we
haven't encountered any problems with that.

So if my assumption from above (regarding the toml file defining the
configurable fields) is correct, then my idea for the tool would be to
package a binary crate for a tool that can convert the toml input into
the other output formats. This tool could be called from within
`debian/rules` with the appropriate parameters.

> The rule to run bar with argument --arg after build is added to rules.
> 
> There's a special exception: if it would cause the dependency to depend
> on itself (if foo itself depends on the crate which specified
> postbuild-dep on foo) debcargo will require the maintainer to resolve
> the situation manually.

> The exception resolves the problem that the man page generator itself
> uses configure_me for its own configuration. This shouldn't be a huge
> issue as for every tool it will happen at most once. In my case, I would
> just include the generated man page in the overlay. 

In the case that the package would get built in the same way as
described above, this is a typical bootstrapping problem. I assume we
would create an initial package without the generated files, and once it
is available in the repos, we would modify it to generate the files and
build-depend on itself. Not sure if we have to expect any problems here
as I have never done something like that. But I'm sure we could get
support by people who are familiar with a procedure like that.

> Note that running built binary from the package would break cross
> compilation. If specifying something like Build-Depends: foo:build-arch
> ![build-arch] was possible, it could be completely automated, but my
> understanding is that nothing like that is possible.

If the tool is available on the host architecture, the above should be
available in cross builds as well.

> I hope it all makes sense to you, please let me know what do you think.

Done :-)

Best regards,
Wolfgang.