Hi, sbuild's README.Debian dates back to 2006 and mentions features that will be removed with the release of Lenny. I don't know how many people will continue reading after this. The manual pages look like they have been touched since their last copyright date which also dates back to the 2000-and-zero years, but they also mention Debian releases that have been archived for years. And they are not quite helpful with the more modern features such as unshare. I understand that sbuild is a tool that is mainly used by experts that don't need proper docs, but I have for example avoided sbuild for more than a decade because I never took the time to find out which of the external docs that are available might be more helpful than the docs that come with the package. Greetings Marc
Hi Marc, Quoting Marc Haber (2025-02-16 13:31:49) thank you for reaching out. This is very similar to #1080194. The thing I have mostly been working on the past few months was to improve the sbuild-out-of-the-box experience. Ideally, for a first-time user of sbuild, they would have to do only these steps: $ sudo apt install sbuild $ cd ./unpacked-pkg $ subild --chroot-mode=unshare And this will work today. The wiki page describes some of that already, but the goal is to turn the man page into the primary source of documentation and then let the wiki only document crafty hacks on top of that. The above works because recently sbuild gained a chroot manager which will automatically create and upgrade chroot tarballs for you, if you use the unshare backend. This feature is still marked as experimental and in the last few releases I did change some small things here and there as I got feedback from sbuild users in how they would like to use and configure this new functionality. But things are stabilizing. So I intend to do a major rewrite of the first part of the man page for Trixie. If you have any feedback for the sbuild unshare mode and chroot manager, I'd like to hear it. Is there something that you'd like to see in sbuild's README.Debian? Thanks! cheers, josch
I think the man-page for sbuild is no worse than other docs in debian
(which doesnt say much, but i dont think you should worry too much about it
- i started from no knowledge of sbuild and perl and sbuild(1) helped me a
lot!)
The bits i would change are
- dont list every option in SYNOPSIS, and better explain what the input is
-- i think this is the
hardest thing for a newcomer to understand
because even the concept of a .dsc is not
familiar.
- some options are in SYNOPSIS but not described anywhere else (eg --log /
--nolog)
- some options like --archive and --batch and --mode=buildd are not clearly
described
- the links between --clean / --source / --force-orig-source are not
clearly described
- the various binnmu-related options would benefit from an example -- i
assume they may make sense to an expert, but they are a hard read for me.
- several places dont say what the default is
- several places refer to paths but do not say
if it is a path on the host or in the chroot
- some places assume the default is schroot
- change the emphasis from term "external command" to the more standard
"hook"
- list the options in a more logical order
- usual grammar/idiom fixes and removal of duplication
(i have a local patch that makes '--help' more useful as well)
The man-page for sbuild.conf is quite hard to follow because it talks about
all-caps things that are implementation details rather than saying what you
put into the file. i generally dont read this one at all as it is too
confusing. i think a real editor would want to move content between the 2
man-pages, leaving a shorter sbuild.1. But that would be a lot of work.
The other docs and readmes are definitely old as they assume schroot, but
they are so hard ro discover it doesnt hurt! i think you could delete
most.of them.
I'd primarily like to have current information there, maybe a little text about which backends are available, and which one is recommended. I generally try to use a backend that is in wide use and doesn't require too much local configuration, preferably the one that the maintainers of the packages use themselves. The way how sbuild, autopkgtest and piuparts do (not) interface with each other, not being able (or willing) to even share their chroot tarballs, is especially frustrating. There is much more than just calling each other. But autopkgtest is way worse than sbuild is. I just got started with sbuild before moving on to autopkgtest. Thanks for your efforts! Greetings Marc
Hi, Quoting Marc Haber (2025-02-16 20:26:12) this is a difficult problem because each of these tools has different requirements. In a tarball for subild you usually want build-essential installed. A tarball for autopkgtest has to to be set up by running the script /usr/share/autopkgtest/setup-commands/setup-testbed (which installs python3, dpkg-dev and other stuff) and a piuparts chroots should be as minimal as possible. How would you solve this? Thanks! cheers, josch
This is not quite true. autopkgtest-virt-unshare says this: | By default it searches for tarballs in ~/.cache/sbuild to reuse the those created for sbuild. So in some form it has to be prepared to use an sbuild-managed tarball already. And in practice, it seems to work fine for me, provided sbuild keeps its tarball around. I think a lot of people would benefit from tighter integration here, and it seems we are so close ... Chris
Hi Johannes, In an ideal world, the three tools would cooperate and settle on a common tarball, or have automatisms to mutate one tarball into another. Or there would be common code that takes care of maintaining all different tarballs together and automated. The problem is that a user has to take care of all three packages, that all work different, need different syntax, fail differently, and are all differently bad documented. Next best thing would be having a document that tells a user to set up the things in a way that it works. It's an extremely common setup and many people are wasting their time in inventing their own semi-working setup. I would have loved to spend half of this sunday working on adduser instead of trying to grok adduser and autopkgtest. I fully understand that this is neither your fault nor are you in a position to fix this all alone. Thank you for letting me vent. Greetings Marc
Hi Marc, * Marc Haber <mh+debian-packages@zugschlus.de> [2025-02-16 20:54]: I actually recommend to not do any setup and let the tools do it. This works out of the box on trixie: sbuild --chroot-mode=testing --dist=unstable --run-piuparts --run-autopkgtest hello Depending on the network connection downloading the packages can be slow and apt-cacher-ng helps a lot. Having sbuild auotmatically pass it to the tools would be great but I don't have it high on my TODO list. Related, there is also angoing work to improve autopkgtest: https://salsa.debian.org/ci-team/autopkgtest/-/merge_requests/515 Cheers Jochen