s4-snapshot qt-free project

seb3773 · 2026-05-22 16:29

Hello Q4OS Team!
It took a lot of time—sorry about that—but I’m starting to see the light at the end of the tunnel!

The backend port (+ tools + CLI with this new backend + GUI with this new backend) is almost complete. I’m now in the testing phase, which isn’t going very fast since I’m currently traveling and only have my small laptop for testing, with limited space available—not ideal at the moment!

I’ve uploaded all the work to GitHub. I’ve tried to document as exhaustively as possible what was done, how, why, and the API of the new Qt-free backend. I’ve done my best to make this thorough and hope the approach will suit you and can serve as a foundation to move forward (and for a native TQt3 interface!).

Basically, the "core design" let's say of the engine's backend migration, is to split system operations into immutable structural representations (WorkCppPlan) compiled by WorkCppPlanner, and then running them via WorkCppExecutor, doing this, the project gains some benefits, especially testability because unit tests can simulate massive system actions (copying /, executing commands) and verify the resulting WorkCppPlan sequence step-by-step without executing any destructive system calls; and thread safety too: the execution plan is a read-only sequence, preventing typical concurrent race conditions when communicating back to the Qt GUI via progress/abort signals.

Work planner                          unit tests
     !                                     !
 compile                             inspects & asserts
     !-------------------------------------!
                          !
                     WorcCppPlan                        WorkCppExecutor
                          !                                     !
                  immutable list of                       Iterates & Execute
                          !-------------------------------------!
                                               !
                                        WorkCppPlanStep

I’ve also made some proposals for improvements (when everything will be validated and ok) — please feel free to share your feedback, which will be invaluable
The project is, let’s say, in a functional state "a priori", but the status is highly "beta" for now. Several things still need to be validated before it’s production-ready, but we’re very close to the final goal—it’s just a matter of fixing any remaining bugs or discrepancies, if there are any left.

Available here: https://github.com/seb3773/s4-snapshot-qt-free/

note: this post is intended for Q4OSTeam in the first place, but of course everyone welcomed to contribute to this topic and/or project on github. Testers & coders are welcome :-)

Last edited by seb3773 (2026-05-22 16:33)

q4osteam · 2026-05-22 16:44

Wow, what a complex approach We will review the code and post a feedback as possible.

seb3773 · 2026-05-22 16:53

q4osteam wrote:

what a complex approach

Yes, it's true the architecture might seem complex at first glance, as it moves away from the imperative script style in favor of a declarative Planner/Executor pattern. However, I didn’t make this choice—which might seem questionable—by chance (it involved a lot of thought and many porting attempts that were quickly abandoned because they were impractical to test). In my opinion, this choice brings three major benefits:

* Absolute system safety (we know exactly what the program will do before it does it).

* Full offline testability without root (the entire ISO creation logic is covered by in-memory unit tests, guaranteeing zero regressions).

* Complete CLI independence from Qt, making the tool extremely lightweight, portable, and ready to be integrated into chroots or minimal system installers.

...quick answer, but I’ll try to elaborate a bit more in another post.

q4osteam · 2026-05-22 16:59

seb3773 wrote:

Complete CLI independence from Qt, making the tool extremely lightweight, portable, and ready to be integrated ...

+1

Backend/frontend architecture gives the code and the complete project versatility and clarity, Our plan is to move all Q4OS GUI tools that way as time permits.

seb3773 · 2026-05-22 17:10

q4osteam wrote:

Our plan is to move all Q4OS GUI tools that way as time permits.

Very good, it's the best way to go I think too !

About s4 port, at first glance, it's true that moving from classic imperative sequential code (where the GUI and system calls are intertwined) to a decoupled and declarative architecture might seem like "over-engineering"... But I haven't found a better way to meet strict requirements for system robustness, portability, and testability.

"Declarative Architecture (Planner-Executor)": In the old Qt codebase, business logic (deciding what to do) and system actions (mounting folders, copying files, running mksquashfs as root) were merged. Classic system script.

Now: separation of the Planning phase (pure in-memory engine that generates a list of abstract steps) and the Execution phase (the interpreter that actually applies these steps to the system) (SoC)

Native Dry-Run mode and safety: because of this separation, implementing a simulation mode (dry-run) or validating the safety of commands before executing them with root privileges becomes much easier. The executor can analyze the entire plan and ensure its consistency before making any physical changes to the disk

We can now test 100% without root privileges. Not that matters much but... testing an ISO creation tool is complex and destructive in my opinion: (ideally live environment, root rights for mounts, and actual filesystem modifications... not very easy for me on the limited machine where the project is). To simplify this, there's an implementation of deterministic unit tests: by having the "Planner" emit data structures (WorkCppPlan), we can test the entire build logic (exclusion conditions, compression formats, replacement chains) in ultra-fast, in-memory unit tests, without ever executing real commands and without root access (root access which isn't necessarily a problem in itself, but safer without)

Non-regression guarantee ("oracle"): temporary implementation of "Qt oracles" allows comparing the behavior of the new C++ version bit by bit against the old Qt version. This is what allows tracking and fixing very subtle logical divergences before even deploying the code to production. My goal was to provide a version that "responds" EXACTLY like the original in terms of log outputs, messages, etc... This seemed imperative to me before even thinking about any improvement. If I get 100% exact and compliant behavior: we're good

Complete independence from Frameworks (Qt-Free) was mandatory as you said: Linking a low-level system utility (which you might want to use in CLI, possibly in minimal installation environments or chroots) to a heavy framework like Qt poses dependency, maintenance, and memory footprint problems. (not to mention the hell of porting to another framework)

Now we should have (hopefully) lightness and resilience: the core of the program is now "freestanding" (independent of Qt):
It can run on any minimal Linux system without requiring the installation of heavy graphical libraries.
This allows, as planned and desired, a total decoupling of GUI / CLI: The graphical interface is now just a simple visual "shell" that "consumes" the C++ engine. The business logic no longer depends on graphical event loops, which eliminates potential bugs related to interface threads or indirect memory leaks from Qt. I think we also normally gain robustness in flows (I18n, standardized parsers)

*To compensate for the absence of Qt, robust building blocks have been recreated:

-A standardized command line parser (CommandLineParserStd) that presumably perfectly emulates Qt's robust behavior while remaining standard C++
-A clean internationalization management (I18nCli) based on deterministic key-value pairs, avoiding proprietary binary formats to be manipulated outside of Qt tools.

There you go, I hope this presents the project better and makes things clearer

q4osteam · 2026-05-25 14:38

We are trying to build project according instructions https://github.com/seb3773/s4-snapshot-qt-free/ however rhe build fails:

>s4-snapshot-qt-free$ ./build_cli_qtfree.sh
==========================================
S4 Snapshot - Build Qt-Free CLI
==========================================

Target: iso-snapshot-cli (Qt-free)
Build directory: build-make
Parallel jobs: 1

Step 1/3: Configuring...
-- The CXX compiler identification is GNU 14.2.0
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++ - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
CMake Error at CMakeLists.txt:86 (add_subdirectory):
The source directory

/home/adminu/seb/s4-snapshot-qt-free/libs/i18n_keyval

does not contain a CMakeLists.txt file.

-- Configuring incomplete, errors occurred!

------

Building with Debhelper framework fails too:
$ debuild -i -us -uc -b
see the logfile attached

Attachments:

debld.log, Size: 58.16 KiB, Downloads: 49

seb3773 · 2026-05-25 19:58

My bad !
It was caused by an incorrectly configured Git submodule.
The `libs/i18n_keyval` library was originally committed as a git submodule reference, but the project was missing the `.gitmodules` file. On my local environment, the library was already present, so CMake worked correctly. However, on a fresh clone, Git only created an empty `libs/i18n_keyval` directory, which caused CMake to fail because `CMakeLists.txt` was missing !

I fixed the issue by properly registering the submodule with:

git submodule add --force https://github.com/stefandevai/i18n_keyval libs/i18n_keyval
This created the missing `.gitmodules` file and allows Git to fetch the library correctly.

I also updated all build scripts (`build_cli_qtfree.sh`, `build_gui.sh`, `build_tests.sh`, and `build_cli_qt.sh`) so they now check for `libs/i18n_keyval/CMakeLists.txt` instead of only checking if the directory exists

If the file is missing, the scripts now automatically run git submodule update --init --recursive
If initialization fails or the project is not inside a Git repository, an error message will be displayed and how to fix it

The changes are already staged in Git.

On your side, you should only need to update the repository and rebuild with git pull && ./build_cli_qtfree.sh

Sorry for that, tell me if it works now.

q4osteam · 2026-05-26 11:20

Yes, build is now successful Testing run failed, see attachments

Attachments:

s4-cli.png, Size: 84.56 KiB, Downloads: 32

s4-gui.png, Size: 105.6 KiB, Downloads: 33

seb3773 · 2026-05-26 11:56

Thanks a lot for the detailed feedback, I think i know where the probleme is And also want to apologize for not explaining the intended testing workflow more clearly on my side...

I'm nearly sure the issue actually comes from how the project is designed internally: both the CLI and GUI expect their helper binary to be installed in the system under `/usr/lib/<appname>/helper`.

For example:

* `iso-snapshot-cli` expects `/usr/lib/iso-snapshot-cli/helper`
* `s4-snapshot` expects `/usr/lib/s4-snapshot/helper`

In your test, I believe the binaries were launched directly from the build directories after compilation. Because of that, when the application tried to perform operations requiring elevated privileges, it attempted to start the helper from `/usr/lib/...`, but the helper was not installed there yet (or the 'legacy' version was still present). This caused the helper launch to fail immediately with error code 127.
Unfortunately, the current error handling interprets this as a missing privilege escalation, which explains the misleading administrator privilege message. In the GUI case, the abrupt termination path can also trigger a Qt cleanup crash, resulting in the segmentation fault you observed.

The intended workflow for testing is actually much simpler:
After compiling successfully (for example with `./build_cli_qtfree.sh`), you must run:
./install_for_testing.sh

The script will:
* safely back up existing installed binaries to `/tmp`
* install the freshly compiled helper to the correct `/usr/lib/...` location
* install the matching CLI binary into `/usr/bin`
Once this is done, both the CLI and GUI should run correctly without the privilege error or GUI crash.

So the problem was not with your testing procedure itself — I simply did not explain clearly enough that this project currently relies on a temporary installation step even during local testing.

Thanks again for the report
I will be able to do "real" tests too this week so this will be easier to correct/validate everything than relying only on unit tests...

q4osteam · 2026-05-26 12:27

$ ./install_for_testing.sh
$ sudo /home/adminu/s4-snapshot-qt-free/build-make/iso-snapshot-cli --file my-system.iso
It gets better with "./install_for_testing.sh", but still doesn't run, see the attachment

Attachments:

runcli.log, Size: 4.23 KiB, Downloads: 45

seb3773 · 2026-05-26 13:12

Understood, your run logs pinpoint exactly what is happening under the hood
The backup pipeline was completing successfully up to step 13, where it stopped with the message: "This operation requires administrator privileges...etc..."

This message is actually a bit of a legacy "misdirection." During step 13, the backend attempts to invoke the script "installed-to-live" with root privileges. Because you were already running with sudo, the helper process launched successfully, but it couldn't find the installed-to-live binary on the system. It returned an exit code 127 (Command not found), which the main program mistakenly intercepted as a privilege elevation error...

As s4-snapshot is designed to run inside Q4OS/MX and acts as an orchestrator, it relies on the host distribution's pre-existing system scripts and templates to do the heavy lifting of building the live ISO:

- installed-to-live (provided by the s4-remaster package): A 1,000+ line Bash script responsible for setting up virtual bind mounts (/.bind-root), resetting user accounts, and rewriting system configurations for the live environment.
(it's possible to 'integrate' this in the backend, we need to discuss this later)
- ISO Templates (provided by the s4-iso-template package, ~25MB): The essential bootloader files, initrd templates, and system structure required to make a bootable CD/USB image.

I have updated configure.sh script to conducts "pre-flight" checks specifically for these critical live system dependencies. If they are missing, it will clearly flag them in the summary and guide you on what packages are missing.

Since I assume you are testing on Q4OS (maybe on a VM?), you just need to make sure these two packages are installed on on the test environnment: s4-remaster & s4-iso-template

So:
./configure.sh
./install_for_testing.sh
and try to run the backup command again:
sudo iso-snapshot-cli --file my-system.iso

Didn't catch this error as the legacy s4-snapshot and associated dependencies are already on my dev machine...

By the way, this brings up an interesting architectural choice for the project:

The shared dependency approach (Current/Philosophical): Keeping s4-remaster and s4-iso-template as external package dependencies: the safest way, aligning with standard Debian/Q4OS packaging principles. Since other system utilities (like Live Remaster or Persistence Config) also share installed-to-live, keeping it in a central package should prevent duplicate code and ensures that system-wide fixes automatically benefit all tools.

The all in-one : bundling the installed-to-live script and the 25MB boot templates directly into the s4-snapshot repository to make it a fully self-contained package. But it comes with a risk of code divergence when system-level scripts are updated downstream.(if it happens)
What are your thoughts on this ?... For now, installing s4-remaster and s4-iso-template on your Q4OS test env. will solve this problem.

seb3773 · 2026-05-26 13:42

ok, I just rethought all this, and actually I wonder if the approach of integrating these elements into the current project might not make sense after all. We're talking about a tool for Q4OS (and possibly therefore in a more "broad" way for Debian-based distributions - if reasonably not too far from official Debian).
Focusing on this point, and on the fact that the s4 "legacy" still has a lot of "traces" of its MX specificity (which the backend port doesn't really change), we could therefore see this differently:
"Freeing ourselves from" MX dependencies might be a good idea. Two options are available to us:

Direct porting to C++ in the backend (this would be my first choice personally)
-> Advantages : security & robustness : No more calls to system() or exec of external scripts that can be hijacked, because everything is done via native Linux system calls (mount(), umount2(), file manipulation via std::filesystem).
We could thus intercept each mount or write failure precisely and return clear error codes to the user interface.
And a single compiled binary does "everything", which eliminates problems with missing or incorrectly installed scripts.
The only downside would be a relative loss of immediate flexibility : If we want to correct a path on the fly on an ISO being built, we can no longer quickly edit a Bash script, we have to recompile. But this isn't very constraining either I think.
or more simply integrating and renaming the Bash script (pragmatic in the short term)
We copy the script into our repo under a unique name (for example s4-installed-to-live or s4-live-setup) and we can customize too it if needed since it will be a different version specific to s4 of the possibly installed mx installed-to-live.
No conflict : Renaming guarantees it will never interfere with the MX package if it's present.
Flexibility : Bash script readable and modifiable on the fly.
** Integrating s4-iso-template into the tool's repo would be interesting for several technical reasons :
Visual and identity customization (Q4OS / other Debian) : The upstream MX/antiX templates may contain their logos, their GRUB/Syslinux welcome screens, and their graphical choices. By integrating these templates (the .gz files and directory structures) directly into the project, we could clean up and customize the templates specifically for Q4OS/derivatives.

boot code cleanup : possibility to simplify and optimize the startup configuration files (grub.cfg, ...) to make them cleaner and lighter.
Generic Debian portability : by "purging" antiX/MX specifics, we could design 'Debian standard' templates for example, which could potentially allow S4-Snapshot to work on any Debian system or close derivative, greatly expanding the project's scope.

Last edited by seb3773 (2026-05-26 14:01)

q4osteam · 2026-05-27 11:38

seb3773 wrote:

... we could design 'Debian standard' templates for example, which could potentially allow S4-Snapshot to work on any Debian system or close derivative, greatly expanding the project's scope.

Yes, that's the goal.

seb3773 · 2026-05-27 13:11

q4osteam wrote:

seb3773 wrote:
... we could design 'Debian standard' templates for example, which could potentially allow S4-Snapshot to work on any Debian system or close derivative, greatly expanding the project's scope.
Yes, that's the goal.

Ok ! Let's go ! Will begin to work on this tonight
Just need your answer on this:
Direct porting to C++ in the backend of the installed-live-script OR integrating and renaming the Bash script ? (given pros/cons of each approach)

Last edited by seb3773 (2026-05-27 13:14)

q4osteam · 2026-05-27 15:41

seb3773 wrote:

Ok ! Let's go ! Will begin to work on this tonight
Just need your answer on this:
Direct porting to C++ in the backend of the installed-live-script OR integrating and renaming the Bash script ? (given pros/cons of each approach)

Great Porting to C++ is better in terms of speed, efficiency, and easy, well designed code structuring. The downsides may include architecture dependency, increased complexity and binary executables.

q4osteam · 2026-07-18 09:59

We've noticed that you're creating quite a few nice TDE-based applications for Debian and Q4OS. We'd recommend making them more accessible to Q4OS users by providing .qsi installers, along with brief, easy-to-understand descriptions and a few screenshots on your GitHub project pages. That way, anyone can install and try your applications with just a few clicks

seb3773 · 2026-07-21 12:51

q4osteam wrote:

We've noticed that you're creating quite a few nice TDE-based applications for Debian and Q4OS. We'd recommend making them more accessible to Q4OS users by providing .qsi installers, along with brief, easy-to-understand descriptions and a few screenshots on your GitHub project pages. That way, anyone can install and try your applications with just a few clicks

Yes, I finally found some time to finalize a few small projects and post them on GitHub, with a few more still to come. Since these are applications I use daily, I like to test them in "real-world" conditions for a while before sharing them here
Providing .qsi files is a great idea—I should have thought of it earlier ! I had looked into the available options at the time, and it’s indeed a very relevant "apt overlay." I’ll take the time to create .qsi files for the already posted projects and will systematically do so for future ones. Thanks for the reminder!

On another note, I’ve also made significant progress on the s4 snapshot qt free project. I’ve eliminated dependencies on installed-to-live and fully integrated the templates into the binary using a simple, custom compression system that decompresses quickly at runtime. This completes the binary’s (cli or gui) autonomy—it now embeds everything and remains within a "reasonable" size ratio (~40-60 MB). I’ve also slightly modified the Debian installer integration: it’s no longer required on the host machine and is automatically injected into the ISO.
The GUI version should be functional, but I still need to run a few tests and refine it. Feel free to let me know if the direction/strategy I’m using still aligns with your expectations. In any case, we’re very close to the finish line As soon as all of this is "validated" and fully functional, I’ll code a TQt3 GUI—I already have some ideas for something simple and effective.

Q4OS Forum

#1 2026-05-22 16:29

s4-snapshot qt-free project

#2 2026-05-22 16:44

Re: s4-snapshot qt-free project

#3 2026-05-22 16:53

Re: s4-snapshot qt-free project

#4 2026-05-22 16:59

Re: s4-snapshot qt-free project

#5 2026-05-22 17:10

Re: s4-snapshot qt-free project

#6 2026-05-25 14:38

Re: s4-snapshot qt-free project

#7 2026-05-25 19:58

Re: s4-snapshot qt-free project

#8 2026-05-26 11:20

Re: s4-snapshot qt-free project

#9 2026-05-26 11:56

Re: s4-snapshot qt-free project

#10 2026-05-26 12:27

Re: s4-snapshot qt-free project

#11 2026-05-26 13:12

Re: s4-snapshot qt-free project

#12 2026-05-26 13:42

Re: s4-snapshot qt-free project

#13 2026-05-27 11:38

Re: s4-snapshot qt-free project

#14 2026-05-27 13:11

Re: s4-snapshot qt-free project

#15 2026-05-27 15:41

Re: s4-snapshot qt-free project

#16 2026-07-18 09:59

Re: s4-snapshot qt-free project

#17 2026-07-21 12:51

Re: s4-snapshot qt-free project

Board footer