Synth: easily build Linux-distributions.

Luis Lavaire
Jul 21 · 3 min read


Almost all Linux distributions have reinvented the wheel when it comes to the technologies and methodology used for building their ISO images. I also did (again), but I hope to have done it better. Perhaps we needed a standardized way to do it?

The approach most teams choose is to write a set of scripts that build their ISOs. It works, sure; but it works in a suboptimal way. That’s what even I chose the first time, but soon I realized that the little script was growing bigger and bigger, to a point that it was moderately difficult to maintain (this is what I’m talking about). And this error-prone, soon-unmaintainable code is what made me think that we needed to simplify the process of generating ISO images.

That is why I developed synth. I hope not only we, Nitrux (❤), find this project useful, but also other developers.

Photo by Tachina Lee on Unsplash

So, what is synth? synth is a script that reads a descriptive configuration (not shell variables) file and builds an ISO image based on those specifications: It is easier to maintain than piles of executable code. At first glance, you may be astonished, but if you think about it, all you need is to provide the most remarkable aspects of the system you want to build. If you want to see a proof, here’s how a configuration file that uses all the available options look like:

synth configuration file.

The synth-file is organized based on keys, like PACKAGES and BASE. You can split lines by appending a comma (,) to the end of a line. Entry names can be left alone in a line. Comments start with a # and extend to the end of the line.

Let’s explain what does each key is for:

  • BASE: This is the only entry that cannot be omitted. It specifies the content with which the image will be populated initially. You can use Docker images or local or remote compressed tar archives. For the last two, you must prefix the path with either @LOCAL: or @URL: respectively. This image should have your repositories enabled, as otherwise you don’t have any other means of supplying your packages. The intention is that
  • UPDATES_URL: A URL providing a .zsync file. This is for compatibility with znx updates.
  • PACKAGE_MANAGER: In case no packages are specified, you can omit this entry; otherwise, here you specify the package manager present in the base image. Currently apt, pacman, and apk are supported. Pull requests are welcome!
  • PACKAGES: The packages that synth will install.

The values for the next entries must have the following syntax: /path/in/root:/destination/in/ISO.

  • KERNEL: A list of the kernel(s) that the image will have. synth will look for it after installing packages.
  • INITRAMFS: A list of the initramfs that the image will have. synth will look for it after installing packages.
  • GRUB_CONFIG: GRUB2 configuration files. synth will look for them after installing packages.
  • GRUB_THEME: An optional GRUB2 theme. synth will look for it after installing packages.

Apart from the ISO image, synth will also generate a sha256 hash and a .zsync file for the ISO file. With those, you’ll be left ready to deploy your ISO image. Happy hacking!


We’re a thriving company making dreams come true. One byte at a time.

Luis Lavaire

Written by

I am a UNIX hacker. I love writing POSIX shell scripts.✞



We’re a thriving company making dreams come true. One byte at a time.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade