Add xtask to generate manpages

[epilys]

For information about the cargo xtask workflow pattern see: https://github.com/matklad/cargo-xtask

This PR adds an xtask crate with only one task, mangen, which generates a ROFF manual page under target/dist/man directory for the vhost-device-sound and vhost-device-scmi binaries.

The manual pages are placed in target/dist/man/vhost-device-sound.1 and target/dist/man/vhost-device-scmi.1.

Future support for other crates in this repository is possible and provisioned for.

Fixes #687
Fixes #697

Demo: Rendered man pages as plain text

Generate the manpages:

$ cargo xtask mangen
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.04s
     Running `target/debug/xtask mangen`
Generated the following manual pages:
/path/to/rust-vmm/vhost-device/target/dist/man/vhost-device-sound.1
/path/to/rust-vmm/vhost-device/target/dist/man/vhost-device-scmi.1

Plain text rendered with:

man -l /path/to/rust-vmm/vhost-device/target/dist/man/vhost-device-sound.1 | xclip

vhost-device-sound(1)

vhost-device-sound(1)                                                                                                        General Commands Manual                                                                                                        vhost-device-sound(1)

NAME
       vhost-device-sound - A virtio-sound device using the vhost-user protocol.

SYNOPSIS
       vhost-device-sound <--socket> <--backend> [-h|--help] [-V|--version]

DESCRIPTION
       A virtio-sound device using the vhost-user protocol.

OPTIONS
       --socket=SOCKET
              vhost-user Unix domain socket path

       --backend=BACKEND
              audio backend to be used

              [possible values: null, pipewire, alsa]

       -h, --help
              Print help

       -V, --version
              Print version

VERSION
       v0.2.0

EXAMPLES
       Launch the backend on the host machine:

       host# vhost-device-sound --socket /tmp/snd.sock --backend null

       With QEMU, you can add a  virtio  device that uses the backend's socket with the following flags:

       -chardev socket,id=vsnd,path=/tmp/snd.sock \ -device vhost-user-snd-pci,chardev=vsnd,id=snd

REPORTING BUGS
       Report bugs to the project's issue tracker: https://github.com/rust-vmm/vhost-device

                                                                                                                             vhost-device-sound 0.2.0                                                                                                       vhost-device-sound(1)

man -l /path/to/rust-vmm/vhost-device/target/dist/man/vhost-device-scmi.1 | xclip

vhost-device-scmi(1)

vhost-device-scmi(1)                                                                                                         General Commands Manual                                                                                                         vhost-device-scmi(1)

NAME
       vhost-device-scmi - vhost-user SCMI backend device

SYNOPSIS
       vhost-device-scmi <-s|--socket-path> [-d|--device] [--help-devices] [-h|--help] [-V|--version]

DESCRIPTION
       vhost-user SCMI backend device

OPTIONS
       -s, --socket-path=SOCKET_PATH
              vhost-user socket to use

       -d, --device=DEVICE
              Devices to expose

       --help-devices
              Print help on available devices

       -h, --help
              Print help

       -V, --version
              Print version

VERSION
       v0.3.0

EXAMPLES
       The daemon should be started first:

       host# vhost-device-scmi --socket-path=scmi.sock --device fake,name=foo

       The QEMU invocation needs to create a chardev socket the device can use to communicate as well as share the guests memory over a memfd:

       host# qemu-system \
           -chardev socket,path=scmi.sock,id=scmi \
           -device vhost-user-scmi-pci,chardev=vscmi,id=scmi \
           -machine YOUR-MACHINE-OPTIONS,memory-backend=mem \
           -m 4096 \
           -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on \

REPORTING BUGS
       Report bugs to the project's issue tracker: https://github.com/rust-vmm/vhost-device

                                                                                                                             vhost-device-scmi 0.3.0                                                                                                         vhost-device-scmi(1)

[epilys]

I just realized the man pages don't/won't include an EXAMPLES section, oops.

I think we can either do it in this PR or on a followup PR to reduce iterations

[stsquad]

This all looks fine to me but I think we should fix the EXAMPLES generation in this series and probably also add a CI job to generate the manpages. I assume this would be in this repo only as I guess the libraries and common CI code don't need to?

[epilys]

The manpages now include an EXAMPLES section as parsed from the crate's README. It's crude but it works.

[dorindabassey]

wdym here? can you add an example?

[epilys]

that the generated CLI flags will only mention pipewire/alsa if the related features are enabled respectively. It's basically a way to select the vhost-device-sound {pipewire,alsa} features.

[dorindabassey]

Thank you for this tool.
seems this PR needs more test coverage.

[dorindabassey]

Hi @epilys, would you be open to adding a man-page for vhost-device-gpu in this PR? No worries if it's out of scope or if you'd prefer it to be handled separately. see related issue - #824

[stefano-garzarella]

Thank you for this tool. seems this PR needs more test coverage.

maybe we can exclude xtask crate from the coverage, I mean something like this (untested):

diff --git a/coverage_config_x86_64.json b/coverage_config_x86_64.json
index 79c169f..733dd59 100644
--- a/coverage_config_x86_64.json
+++ b/coverage_config_x86_64.json
@@ -1,5 +1,5 @@
 {
   "coverage_score": 86.60,
-  "exclude_path": "",
+  "exclude_path": "xtask",
   "crate_features": ""
 }

[stefano-garzarella]

probably also add a CI job to generate the manpages. I assume this would be in this repo only as I guess the libraries and common CI code don't need to?

I was thinking the same, @epilys do you think it's something we can easily do?
Otherwise, we can add a CI job that just checks that man pages are updated.

[epilys]

Hi @epilys, would you be open to adding a man-page for vhost-device-gpu in this PR? No worries if it's out of scope or if you'd prefer it to be handled separately. see related issue - #824

I tried the same way I did it for scmi and sound but it looks like it needs more refactoring and is not as straightforward; the clap arg types depend on other config types such as GpuFlags, GpuConfig, capset, etc.. I think we'd need to refactor them out along with the clap types to a config.rs instead of having an args.rs module like the other crates. WDYT?

[epilys]

probably also add a CI job to generate the manpages. I assume this would be in this repo only as I guess the libraries and common CI code don't need to?

I was thinking the same, @epilys do you think it's something we can easily do? Otherwise, we can add a CI job that just checks that man pages are updated.

Yeah it should be easy. I will do it in a follow-up PR.