swirlbuild(7) Miscellaneous Information Manual swirlbuild(7)

swirlbuild — rudimentary (UNOFFICIAL) package build system for Debian Stable

TABLE OF CONTENTS

(If you read this in a browser, this is an HTML version of swirlbuild 's intro manpage. Links to system manual pages will not work).

swirlbuild is a thin layer between dh_make(1), pbuilder(8) and apt-ftparchive(1) to allow creating and building minimally viable Debian packages, without the usual paperwork and directory dance that comes with the official method. It also maintains a local (file:///) repository to install packages easily. Only Debian Stable is supported.

swirlbuild totally integrates itself inside the Debian packages management system, and does not need a bootstrap, just some Debian packages installed and the swirlbuild tree.

It is heavily influenced by OpenBSD's ports collection, while some hints were taken from Alpine's Abuild and CRUX's ports.

The heavy lifting is done by:

dh_make(1)
creates all the necessary paperwork needed to reduce ours.
pbuilder(8)
build packages in a chroot; when building with swirlbuild, no development packages will be installed on your system.
you(4)
While swirlbuild simplifies a lot the creation of Debian packages, you will still have to do some work. If you do not feel confortable with that, you may have a look at the effing package management (fpm) , that is easier but less flexible out of the box.

See MOTIVATIONS on why I ended up creating this, and CAVEATS because it is a rudimentary system, and may not fit your use case.

SWIRL means SoftWare In OuR LAN. An obvious reference to Debian's swirl logo and swirlbuild ´s MOTIVATIONS. swirlbuild is not a Debian-backed software, and is totally unofficial.

Because "ports" means something else in Debian's jargon than the usual BSD meaning of "ports", the recipe to build a package is called a swirl.

swirlbuild needs sudo(8) and your current user must be able to use it to be root at least for running pbuilder(8) For more informations see the Debian wiki documentation about this.

You usually do this once by machine.

Assuming you have downloaded swirlbuild from our repository in your home directory:

$ cd swirlbuild
$ ./infrastructure/bin/deploy builder

There you will be asked to validate the installation of some packages, sadly it is always too many but it is not our fault ;) An empty repository will be created in ~/swirlbuild/repository and an entry in /etc/apt/sources.list.d will be added for it. Also a pbuilder(8) base chroot will be created.

First thing first: you should ALWAYS ensure that your system is up to date before running buildswirl(1).

We will start with swirls/oksh because it is simple; it is the OpenBSD version of the Korn Shell. Do not move from your ~/swirlbuild directory and run this:

$ sudo apt update

If you have a recently installed Debian, apt(8) will complain about permissions. It is because Debian made a change to $HOME permissions for newly created users. See Debian bug report 1014901.

You can ignore the warning, chmod(1) 0755 your $HOME, and many more options. Let's continue to the installation and the test of that oksh swirl:

$ sudo apt upgrade
$ ./buildswirl swirls/oksh

You will be met by a wall of text. Your password may be asked by sudo(8) for pbuilder(8) use. Grab a coffee/tea and/or feel yourself like a hacker.

Hopefully the build has ended. swirlbuild never installs packages by itself.

$ sudo apt update
$ sudo apt install oksh
$ oksh
oksh> echo $OKSH_VERSION
7.2
oksh> exit
$ sudo apt remove oksh

The documentation for buildswirl(1), and the whole swirlbuild system can be installed on your system just like this:

$ cd ${HOME}/swirlbuild && ./buildswirl swirls/swirlbuild-docs

HTML versions of the manpages are also available in /usr/share/doc/swirlbuild-docs/html.

Through the documentation, you may see references to $SWIRLBUILD, which has to be replaced by where you have put the swirlbuild tree on your computer.

There are many ways to deploy swirlbuild across the network. We will take something you have already probably experienced for that: rsync(1) coupled with ssh(1).

Let's say we have a desktop machine, where you have built some packages, and you want them to be installed on the laptop machine.

This is implied that the two machines have the same architecture, see Multi Architecture about why. First we will copy swirlbuild from desktop to laptop:

laptop$ cd; rsync -av --delete -e ssh desktop:~/swirlbuild .

Then we deploy swirlbuild as a "user". Note that you can totally "upgrade" later to "builder" by running the script again.

laptop$ cd swirlbuild && ./infrastructure/bin/deploy user

As you have noticed, this only adds an /etc/apt/sources.list.d entry for your repository. Now it is the same thing as the desktop machine:

laptop$ sudo apt update; sudo apt upgrade; sudo apt install oksh; oksh

There are other ways indeed, like using a webserver for example, but that is up to you.

Please check out swirlbuild(5), especially "USUAL WORKFLOW", where I describe the creation of the unmaintained-swirls/badwolf swirl.

It is recommended to build a basic Debian package before starting, see the packaging intro.

On top of that, all that is required is:

Veracrypt :) As you probably know, Veracrypt will never be included in Debian, unless there is a radical license change. There is a whole story behind on how it snowballed to this project, but it is not interesting in a technical document.

The other reason why I wanted this is avoiding appimages, snaps, flatpaks for software not included in Debian (for various reasons).

I looked around, and did not like the other solutions. I am a former OpenBSD user and wanted a small ports tree back, while keeping Debian.

I have a script that rsync(1) my desktop PC home directory from my laptops one, and then do the apt(1) upgrade thing. This explains why swirlbuild has been made this way and not meant as a "system" package building system.

I do not expect anyone but me using it, but documenting it like I would has been an amazing rubber duck.

My goal for swirlbuild is to be simple to use and maintain the source code. This clashes with being as featureful as other build systems.

  • swirlbuild is a solo work, and as I am writing this, I am its only user. You may use it in a way I did not planned and meet a bug. Features have been heavily tested as they have been implemented, but many are barely used as well.
  • swirlbuild only supports Debian stable.

    Debian Testing with pinning *may* work, but there is no guarantee.

  • While C and C++ are fully supported, other programming languages may require more work on your part, especially if an external module is not available as a package.

    Golang and Python are usually well supported and examples are provided in unmaintained-swirls. Rust status is well ... you can do it, but debcargo(1) is probably a better option.

  • swirlbuild does not support multipackages (-dev/-doc/-bin). I do not like this feature in Debian, excepted for debug symbols that swirlbuild provides by the way. The same can be said about Suggests and Recommends. Also implementing them does not play well with swirlbuild ´s goals to stay simple.
  • swirlbuild uses a networked version of pbuilder(8). This is intended mostly for golang and rust packages, to avoid packaging too many crates/modules.
  • swirlbuild features an almost fully staged build process, but is split between swirlbuild stages and debhelper(1) stages.

Copying the swirlbuild tree minus the repository content and building software on the foreign architecture machine works as expected.

Making a mixed architectures repository is discouraged and not supported. swirlbuild creates simple repositories that are not adapted for that, and as such has no support for architecture independant packages.

Do not get confused between bugs and misuse. swirlbuild has no checking mechanism, so it is easy to do so.

Yet feel free to report them, including your swirl if relevant, because there are.

buildswirl(1), the user manual.

swirlbuild(5), the reference manual to work on swirls.

I do not think there will be any contributor. But just in case... For swirlbuild itself, try to respect the weird coding style. I prefer test(1), over [ ], and real tabs and stuff. Sorry. Try to not do lines longer than 90 characters. I will correct the style if I see something I do not like, but please try to avoid wasting too much of my time.

Changes in features must be documented, which may be problematic because we are using OpenBSD's mdoc(7) (package: mandoc) and not man(7). I will take care of that if needed.

Adding a "contrib-swirls" may be a thing with a bit more stricter acceptability rules than Void Linux.

swirlbuild itself is licensed under the zlib license. You can find a copy of it in $SWIRLBUILD/LICENSE.

swirlbuild is not a Debian project, is not endorsed by Debian, and must be considered as "non-free" as defined in the Debian Policy.

Any package built by swirlbuild MUST come with a copy of the source code license, located in /usr/share/doc/<PKGNAME>/copyright, as detailed in swirlbuild(5). There is no exception to that. For speed reason, we do not use something like decopy(1).

The swirlbuild project is the association of individuals working on the official swirlbuild repository.

This section exists just to shield to a certain extent the swirlbuild project against regrettable situations like the openbsd-wip vs Pale Moon joust.

  • If your software licensing is misrepresented in swirlbuild, please open an issue. Note that the swirlbuild project does not redistribute neither ready to use packages of your software nor sources from your software by itself. We only redistribute our own code and assets under the zlib license to the public.
    To clarify, the swirlbuild project just redistributes recipes to build and operate your software on our operating system.
  • In case you think we are violating any conditions of redistribution and/or modification of your software, please open an issue explaining clearly what are the issues and the steps we should proceed on to comply.
  • We may ask the intellectual property (IP) holder of the software to intervene when special permissions are required.
  • If we agree to disagree on how to settle the situation, the swirl corresponding to your software will be deleted.
May 13, 2025 Debian Stable