From cc4f8a723916f6eb609df15eeadff00074d7a511 Mon Sep 17 00:00:00 2001 From: TopchetoEU <36534413+TopchetoEU@users.noreply.github.com> Date: Sun, 16 Mar 2025 03:00:11 +0200 Subject: [PATCH] update readme --- README.md | 45 ++++++++++++++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index aa5c8a9..082302a 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,51 @@ # Slimpack -My shot at creating a lighter flatpak client with (almost) no containerization of the applications. +A pragmatic and minimalistic repacker of flatpak applications without (much) isolation. ## Why? -Some might be big proponents of the whole isolation thing, but I believe that only works in theory with simple apps, as anyone who has tried to get anything running under flatpak can tell you. In my humble opinion, isolation offers too little security benefits for the heaps of problems it creates - yet again, we are solving a problem that really wasn't a problem. To be more precise, the following are some major issues with flatpak, which isolation creates: +Some might be big proponents of the whole isolation thing, but I believe that linux is in the unique position where isolation doesn't really *work* on the desktop. Why? Because to have isolation, you need to have a way to talk to the outside world. On phones, this happens trough well-established APIs that the vendors provide the programmers, because of which isolation on mobile works. However, on linux, there isn't really a standardized set of APIs to do desktop apps. You have KDE and Gnome's takes on them, but no one unified standard. This of course means that if we ever wish to containerize, we need to create APIs for KDE, Gnome and whatever comes next. -- You need to do a lot of fiddling before you get the themes right -- Basic UI features (like drag-n-drop) just don't work -- You get mysterious "file doesn't exist" errors -- Flatpak just straight up installs 3 other distros to run your apps, which takes up A LOT of space -- Apps usually come with enough permissions to be unsafe, but not enough permissions to work properly, partially due to laziness and the shitty permission system flatpaks have -- The CLI is TREMENDOUSLY bad +Flatpak's take on this conundrum, of course, is as dreadful as possible - not only are they not solving the issues, they refuse to recognize that there's an issue at all! Furthermore, the tooling around flatpak is simply, and without any doubt, a whole new level of terrible. -However, flatpak did one thing - it created a network. If you want to publish an application, probably the easiest way to do so is to do it using flatpak. This has resulted in a lot of apps being published exclusively for flatpak. However, we don't have to deal with this whole debacle, as we can just create and use an alternative client that just runs the apps, but outside of their designated containers. At the end of the day, we are still distributing files, just with some permissions metadata sprinkled in. +However, flatpak did one thing - it convinced a lot of developers they were the only place you should be publishing your apps. This means that flathub is one of, if not the most valuable assets to the linux desktop ecosystem. If only we could run those apps like any sane person would - natively... -This project aims to do just that - be the minimalistic client that allows you to just run the darn flatpak app, without having to fiddle with flatseal for 2 hours. +This is where this project comes in. Slimpack aims to be a small tool that allows you to repackage a flatpak package into a self-contained executable, that runs pretty much natively. No longer do you have to fiddle with flatseal for 2 hours just to run a darn electron app. ## Why not? -This project is VERY early stage. You are expected to know what you're doing, and you will brick your system if you don't. At the very least, you are expected to take a quick look trough the code. The whole process of running an app using this client is very manual, but will improve in the future, to a point where you can just integrate it into discover or another client of your choosing. +This project is VERY experimental, employing a custom filesystem, which has bricked my whole OS I/O, until I restart. You are expected to know what you're doing, and even if you do, expect stuff to go south. ## How? Since the flagship flatpak client needs to download the apps from a repository, we can do that too. In short, this project implements a simple OSTree client (without all the BS the flagship client comes with) that can successfully list the remote refs (apps) and download any given app (and its metadata). -The other big (and not yet implemented) part of the project is the actual repacking of the app. In short, each app has dependencies and a specific runtime it demands to be present. The original flatpak client will 1. download the runtime (for all intents and purposes a distro) and 2. download all the dependencies it has. This client in stark contrast will only download the dependencies and PRAY to the lords that the correct runtime libraries are already present on the host. +The other big part of the project is the actual repacking of the app. In short, each app has dependencies and a specific runtime it demands to be present. The original flatpak client will 1. download the runtime (for all intents and purposes a distro) and 2. download all the dependencies it has. This client in stark contrast will only download the dependencies and will assume that the libraries, packaged by flatpak's runtimes are present on the host. -The last thing this project does is create a *light* container around the application, so that the application-specific dependencies and the app itself can be layered on top of the existing system. Now, don't be mistaken, I'm not doing this because it's the most minimalistic way to do it, but because flatpak basically REQUIRES this architecture. However, the container won't isolate the container any further. In the future, a more configurable isolation might be created, but for the moment, I'm trying to achieve the bare minimum. +When this program repacks a flatpak, it will get put in a self-contained executable as a squashfs image. When the executable gets run, the application will get run in a *VERY* light container, which only layers the squashfs on top of the container (unfortunately, using the currently employed methods, there are *some* limitations, but everything that ran under flatpak *should* run here, too). + +Now, don't be mistaken, I'm not containerizing because it's the best solution (the best solution is called AppImage), but because flatpak basically REQUIRES its own view of the filesystem (namely the /app folder). However, we don't isolate more than absolutely necessary, because the whole point is to run the programs as natively as possible. ## Usage -First of all, you need to build the project. This is done via the `make` command. You will need lua 5.4, curl, zlib and some sort of cc installed. The executable will be `dst/slimpack`. +First of all, you need to build the project. This is done via the `make` command. You will need lua 5.4, curl, zlib and some sort of cc installed. The executable will be `dst/slimpack`. Feel free to copy it to `./local/bin/` or `/usr/local/bin/` -TODO: add actual usage when the tool is done lol +The CLI of slimpack works in a very simple way - first, you specify the generic options (for now, only --repo is available), followed by the action. Each action has its own options and then its own subaction and so on. + +In syntax form, it looks like this: + +`[--global-opt-1 --global-opt-2 ...] [--action-opt ...] [--subaction-opt ...]` + +Sometimes, if an action is final, it might just take a plain argument (like how `pack` will just take one argument which is the ref to pack) + +### Querying + +The first action is `query`. It groups all operations that are related to asking questions about a flatpak remote. + +To find a ref, you can use `slimpack query search `. This is case-insensitive, but you need to be careful with dashes and underscores. Usually, you will care about one result - `app/.../x86_64/stable`. The rest, for all intents and purposes, may be ignored. + +To find out more info about a ref, you can do `slimpack query info `. This will print some information about the package, like its version, license, dependencies, etc. + +### Packaging + +The star of the show is the packaging - this will take a flatpak package and repack it into a self-contained executable (not too unlike AppImage). To repack a package, run `slimpack pack -o `. This will eventually, after a lot of stdout spam, write an executable file to "output-filename". When run, it will just run the flatpak application without (a lot of) containerization, without any fuss.