Structure and Build Documentation

[prajjwald]

Hi All,

I learned about SpiralLinux recently, thought it was cool, and decided to tinker around a bit to understand how it works underneath the hood.

Maybe I haven't looked hard enough yet, but as I couldn't find the kind of documentation I was looking for in the github repository/wiki, I decided to play around a bit more, and I created this repository to document my ongoing learning about SpiralLinux.

I apologize if there is already pre-existing documentation that makes this unnecessary - I'm just starting to look around this project, and might have missed things. However, as I'm a very visual person in terms of learning/understanding concepts, I definitely wanted to have a visual representation of the folder structure, which at a minimum, might be helpful to some people.

Will keep updating my repository, but can move/contribute to a more appropriate location if anyone has suggestions.

Here's an example diagram of the folder structure for plasma that I've documented:

[geckolinux]

Hi there @prajjwald , thanks a lot for sharing that, it's very well done. You're right that I've never taken the time to thoroughly document the build process, because the project is mainly directed at the end user and I just upload the build recipe tarballs to Github for the sake of transparency. But of course I'm happy for people like yourself to delve deeper into the process.

This is the most detailed explanation that I remember posting about how the build process works:
https://github.com/orgs/SpiralLinux/discussions/228#discussioncomment-4809266

Also in the "Special thanks" section of the SpiralLinux website there is a link to the full live-build manual:
https://live-team.pages.debian.net/live-manual/html/live-manual/index.en.html
And this practical example is what really got me started with creating SpiralLinux:

• https://github.com/nodiscc/debian-live-config
• https://debian-live-config.readthedocs.io/en/latest/custom.html

The spiral executable script at the root of each edition's directory is a simple addition I made to automate the repetitive steps of launching the build process. And it came especially handy for this latest series of 12.x releases, because there are a number of serious bugs in the Debian 12 version of live-build, one which I can't work around so I had to use a Debian 11 system with the older version of live-build to build the SpiralLinux 12.x ISOs from Debian 12, but that in turn led to a few other incompatibilities. So I worked around those with a very crude hack via the firmwarelist.sh and live-build_memtest.patch files that you found, which are used to patch or replace components of the live-build scripts on the build system.

package-lists, which may be for additional repositories

This is where all of the packages that should be installed into the final ISO are enumerated. The repositories are specified first in the auto/config file (which gets copied from auto/hdd or auto/iso) and also in the archives/ directory, and there are several stages of live-build and live-config (during boot process of the live ISO) where the /etc/apt/sources.list file gets written, but since I need some very specific formatting and commenting for it to work optimally out-of-the-box with Synaptic I override some of those, it might be a bit of a hack but it "works" for the final ISO.

the chroot section seems to have a mini-tree for different files that might be copied over to the install - that's my guess as of now

Right. Files that are present in config/includes.chroot/ get copied into the filesystem that becomes the live ISO; and they will replace files that were already installed in the previous DEB packages installation stage.

[prajjwald]

Thanks a lot for the detailed response @geckolinux !

I'll be slowly reading the links you provided, chipping away at the documentation and my own understanding, mostly over the weekends (no hard promises, I do tend to get distracted easily, but this is very cool).

My thought process so far is:

• It will probably help the overall user-base and potential contributors/tweakers (including myself) if the structure is well documented. At any point in time, if my local exploration docs look good enough to merge into the main wiki, I'll be happy to (let me know if there are any tweaks that could make the documentation more acceptable to what you'd like to see in the wiki - I'm open to some amount of structural reformatting if it is useful. At this point, they clearly are not there yet.
• There is definitely a lot of knowledge you've put into this repository aside from the packaging. I noticed comments on pipewire optimization in a separate thread for example. Same with user permission relaxation. These would be amazing to document/explain. I'll try to slowly see what I can discover if I don't get distracted 🙂.
• Ideally - this might help people setup replicable CI/CD processes to build their local builds (apologies again if I missed this again and this already exists, as you implied by the existence of the spiral script).
• In an exciting new world, if users had the option to specify their own customization urls on top of a base spirallinux build repository (this one, or if someone has their own opinionated customizations inspired by yours, they can use their own).

[geckolinux]

I noticed comments on pipewire optimization in a separate thread for example. Same with user permission relaxation. These would be amazing to document/explain.

Ah, yes, I do try to comment my modifications in the build scripts and in the modified config files themselves. Let me know if anything isn't clear or needs to be expanded on.

Ideally - this might help people setup replicable CI/CD processes to build their local builds (apologies again if I missed this again and this already exists, as you implied by the existence of the spiral script)

The spiral script is really quite crude and simple. I don't really know much about CI/CD processes, I just spin up a bunch of Debian 11 VMs in the cloud and then run (as root) apt install live-build rsync nginx qemu-system-x86 patch in each VM, and then rsync the SpiralLinux recipe directories from my local computer into the VM, and then cd into the recipe folder and run ./spiral .