▲ 116 points
back
26 comments
This is awesome, well, useful. I have a package I'd like to have in Debian, and I am willing to maintain it, but getting startet is just ... complex.
The whole Debian package infrastructure is remarkable complete and capable, but it's dense and the documentation is not great. The git-buildpackage is barely documented, at least not in a manor which where a newbie can just build a package and be sure that an upgrade will work in the future.
I think this is a good starting point https://mentors.debian.net/
Also personally I'd avoid using git buildpackage at the beginning since it's rather complicated and not everyone uses it (although those who do are very vocal!)
You don't need git at all, but if you want something easier, create a repo on salsa and keep the debian/ directory there and that's it.
Can't agree more!!
10 years ago, when I wanted to package my utility, there were 3-4 documentation snippets, each of which usually used different set of utilities.
- Should I create the package boilerplate with dh_make or debmake? The structure they create differs.
- What's the name of command which I use to update the version in changelog? deb... no, dh_... no, ... it's `dch`!
- You manage patches with `quilt`, but where do I get `dquilt` mentioned in the documentation? It's not in any package! Oh, it just an alias you should grab from `Chapter 3. Modifying the source` documentation and add into your .bashrc! And also `~/.quiltrc-dpkg`, or nothing would work.
- Packaging: dpkg-buildpackage, debmake, or maybe pbuilder?
- How do I append CFLAGS? It's DEB_CFLAGS_MAINT_APPEND, thanks dh_make comment inside the rule file! Too bad if you've created the structure with debmake!
- dpkg-gensymbols: warning: some new symbols appeared in the symbols file
- dh_missing: error: missing files, aborting
But to Debian's credit, once you've done everything more or less correctly, you can use all the power of the build system. It's very easy to cross-compile software, just a matter of a single command. On other systems it's usually much harder.
Compare with Arch, e.g., https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=gf2-g..., where you just run `makepkg` or `makechrootpkg -r ~/archroot` (setup is just `mkdir -p ~/archroot ; mkarchroot ~/archroot/root base-devel`). The wiki is also wonderful (even for general-linux/non-Arch-specific information) -- informative and to-the-point.
To be fair, if all you want is a package with Debian you can do that too. Just copy files in to a dir(like package() in your Arch example), write a 10 line DEBIAN/control in there(like the preamble in your Arch example), and call "dpkg-deb --build". The linked document is describing something different, joeyh has a short "why?"¹ from years ago that may be helpful.
What is different in OP that makes that approach not suitable? The git upstream? In the AUR example I gave, pkgver() auto-updates $pkgver, which will show up in version control. You can run `makepkg -defo` (or -dfo I forget which rn) to just run pkgver().
Or use FPM and ignore all the official rules. It will still work. https://github.com/jordansissel/fpm
And will arch tell you that the package has updated the configuration and that you might want to review your canges with the changes from the new version?
Will it automatially restart the .service file of the daemon you just upgraded? Will it autodetect which python modules it requires to install?
Arch/pacman will tell you config changes. There is even an utility called pacdiff to review all of them at once. It will not restart service files since it is a more hands-on distro. Since Arch is a quick rolling-release distro, it is better to reboot your system since ABI stability is not guaranteed.
Arch/pacman packages are quite simple which makes the maintenance burden less. However, when compared to more mainstream distros like OpenSUSE and Fedora, Debian's package recipes are more unwieldy and arcane. Why do we need to put things in the upstream source in the first place? Why do we use scripts that don't make sense and full of legacy in 2025?
I deal with Yocto almost daily, still most Debian packages are a mistery to me. Don't even mention things like getting an almost upstream Linux kernel (like a vanilla release + some patches on top) to be ported as a normal Debian package.
Is telling systemd to reload .service files after changing them a "script that doesn't make sense" to you?
Makes plenty of sense to me.
90% of the scripts are to do that, or to recompile .pyc files when you install a new module or when you install a new version of python.
Arch tries to generally avoid changing "default" behavior. Systemd doesn't automatically do that, so Arch won't ship systemd like that. Arch also generally avoids shipping with timers enabled.
Out of lazyness or out of actual usefulness to the users?
A little of column A, a little of column B. Arch is very much a distro developed for the packagers. OTOH, as someone who often has to dive into the details regardless of distro, I generally appreciate the plain-vanilla approach to arch's packaging (since I can just set the package up as opposed to undoing whatever helpful defaults and changes Debian's decided to add).
I personally (using Arch, btw) definitely prefer Arch's behaviour. If I update or install a daemon, I generally want to configure it before (re)starting it.
Arch does reload service files (not user ones though) IIRC. I also disagree with GP, I don't reboot, I use needsrestart and/or my own logic (simple grep for "(deleted)" within proc maps and then show cmdline).
1. If you mean merging package/upstream config with user/system modified config, yes, run pacdiff
2. Use needsrestart (isn't this what Debian uses also?)
3. I don't package python things, I wouldn't know. Maybe, maybe not.
Do the above have different trade offs that are not best fit for everyone? Yes, of course. I used Debian for about a decade, and Arch for almost as long, and have found everything clear and well documented. All the various functionality I want is typically implemented by a simple tool designed for that one job, with a nice wiki page/entry that I could find trivially.
I did not write my post in order to start a "distribution debate". I had the sense that the contents of debian/ in the OP were not fully given, because there was a lot there, and I wanted to know if that was true, and if so, why. Having a pretty short and self-explanatory single file alternative to look at might prompt someone to pipe up and say "look, the Debian equivalent is short/long/simple/complex" in a clear way, which would be interesting because I consider such Arch examples to be near ideal.
The DEB format is powerful and has a lot of conveniences for Debian Developers (eg, it does lots of things automatically for you to reduce boilerplate).
Unfortunately, it’s not easy to discover what automatic things are happening and what they’re doing. (If you look at the debian files for a package without packaging knowledge, you often can’t tell how the package is made. Arch Linux PKGBUILD files for example are much easier to understand without prior knowledge.)
This isn’t necessarily a problem, but the documentation is poor as well, which means the barrier to entry is artificially high.
At least that was my impression from a few years ago. Maybe things are better now.
Just gonna share a tool I found recently that is really awesome for making debs, Debcraft (https://salsa.debian.org/debian/debcraft). It uses podman to isolate the build environment. The author of OP is also a major contributor, even though he barely mentions Debcraft in the post.
sbuild is the tool used by the Debian community and all the Debian infrastructure to do this. Uses schroot under the hood, and is what you want instead of docker and friends 99% of the time anyway.
Git clone from salsa [& making my changes,] then running `debcraft build` was a hell of a lot easier than even just reading the documentation for all the different ways to build debs. I don't want to be an expert in debian build and packaging systems, I just want to make a few debs for my lan, ideally without clobbering the build box in ways I don't really understand. I can't overstate how debcraft allowed me to glide over all that complexity and focus on the task I actually care about.
Both sbuild and Debcraft essentially still run a minimal hermetic Debian environment without network access inside them. The fact that sbuild exists is not a reason to not try out Debcraft. However the selling point in Debcraft is not that it has the build environments, but much more.
Another way to do it; run debuild, fix the error, repeat. Then run lintian, fix the errors, repeat. Then upload to mentors, file a sponsor request, fix their comments, repeat. Then it gets a sponsored upload, but rejected with comments by ftp-masters, fix the errors repeat. Then it gets accepted, but users file bug reports, fix the error, repeat.
I've always been intimidated by the number of little tools and configuration options when building Debian packages. In the end, it's not very hard, and the format is quite reasonable, it just feels more complicated than it is.
I'm maintaining cargo-deb that builds a .deb from a Rust/Cargo binary project with no configuration needed.
The main source of complexity isn't the .deb format, but the tooling and infrastructure around the format. It's mired in overcomplexity, and it's very much still in a '90s mindset of building locally with multiple layers of Perl-based tools. If it was rethought to be git-native using docker images or equivalent then it could be of equivalent simplicity to other contemporary systems. When I look at what you can do with the FreeBSD ports and Poudriere or with Homebrew and other systems, I see how much of the complexity has been added incidentally and incrementally, with good intentions, but a radical rethink of the basic workflows are necessary to consolidate and simplify them.
[I used to maintain sbuild and was the author of schroot back in the day]