Home

Awesome

ArchImage is the bundling of Arch Linux packages into an AppImage using JuNest.

This allows you to use the latest programs from Arch Linux and AUR on every distribution, old or newer.

Being this a container into an AppImage, it has its own "bubblewrap" or "proot" to work using its inbuilt resources, including GLIBC, so it can run also on 10+ years old GNU/Linux distributions:

Index

Installation

Usage

Tutorial

Compared to classic AppImage construction

Files removed by default

Drafts

Troubleshooting

Credits

Related projects

Installation

Download the main script and made it executable:

wget https://raw.githubusercontent.com/ivan-hc/ArchImage/main/archimage-cli
chmod a+x ./archimage-cli

USAGE:

archimage-cli [OPTION]
archimage-cli [OPTION] [PROGRAM]

OPTIONS:

-h,--help		Shows this message.
-v,--version	Shows the version.
-b,--build		Create the script to build the AppImage.
-s,--sync		Update archimage-cli to the latest version.
Back to "Index"

What to do

To prevent problems of any kind, dedicate a single directory to the created script, proceed as follows:

  1. create the script;
  2. create an empty directory, the name must not contain spaces, for example "tmp" or "test";
  3. move the script you created to the directory in step 2;
  4. open a terminal in the directory created in step 2;
  5. run the script inside the directory, like this: ./sample-junest.sh

EXAMPLE

In this video I will show all the steps that I will describe in this section (Archimage 3.4.2):

https://github.com/ivan-hc/ArchImage/assets/88724353/d7ecb9e5-1db7-4d5c-ae6b-374b6c32e87c

What NOT to do

Here's what absolutely NOT to do when running a script you created:

Follow the steps at "What to do" and watch the "video example" above.

Referenced issues https://github.com/ivan-hc/ArchImage/issues/19 and https://github.com/ivan-hc/ArchImage/issues/23
Back to "Index"

Step by step guide

Before proceeding, make sure you have understood "What to do" and above all "What NOT to do"!

  1. Create the script, use the option -b or --build, example with "firefox" (see the above "video"):
./archimage-cli -b firefox
  1. The script will ask you if you want to specify the name of the binary or leave blank if the name is the same of [PROGRAM]. Being the executable /usr/bin/firefox of "firefox" named "firefox", press ENTER to leave blank. Some apps, have a different name for their executable (for example "handbrake" have /usr/bin/ghb, so just write "ghb" for it). If you're not sure about thename of the main executable, use https://archlinux.org/packages/ or read the PKGBUILD if the app is hosted on the AUR. By default, the script will use "yay" to install all the programs in JuNest.
  2. The script will ask you to add a list of additional packages you want to include into the AppImage (with the syntax app1 app2 app3...), leave blank if no dependency is needed.
  3. The next questions are about implementing or not all dependences, choose "Y" to bundle all the dependences, or "N" to do this in other steps.
  4. This phase, shown in the video, has a last message asking you to use a standard configuration with the following defaults if you press "Y":
  1. Run the script.

Requirements of an AppImage

To be valid, an AppImage must contain, in the root of the .AppDir directory:

  1. a valid .desktop file (the application one is selected by default, otherwise a custom one is created);
  2. an icon, whose name (without extension) must correspond to the "Icon=" entry of the .desktop file at point 1;
  3. the binary file must be contained in the $PATH (/usr/bin) of the AppImage, and must correspond to the "Exec=" entry of the .desktop file at point 1.

If this requirement is not met, no AppImage will be created.

Archimage structure

An Archimage is a Type3 AppImage, i.e. one that does not require libfuse2 to function.

Unlike many other AppImages, its structure, other than the requirements above, resembles a $HOME directory:

App.AppDir/
  |
  |_/App.desktop
  |
  |_/app.png
  |
  |_/.cache/
  |
  |_/.local/share/junest/
  |
  |_/.junest/

Hidden directories are those used in a normal Junest installation:

The Archimage is first built, and then reassembled with only the essential files indicated in the script you created.

Test the AppImage

Once the script has finished and the AppImage has been created, run the AppImage from the terminal, and check that there are no errors (e.g. libraries not found, missing dependencies...):

./Sample-1.2.3-x86_64.AppImage

For more verbose output, use LD_DEBUG, like this:

LD_DEBUG=libs ./Sample-1.2.3-x86_64.AppImage

to see the missing libraries, or

LD_DEBUG=files ./Sample-1.2.3-x86_64.AppImage

to see the missing files.

I redirect you to the guide on the usage of LD_DEBUG, at https://www.bnikolic.co.uk/blog/linux-ld-debug.html

Dotfiles tip

To not flood your $HOME with dotfiles, I recommend creating a .home directory with the same name as the AppImage:

mkdir Sample-1.2.3-x86_64.AppImage.home
./Sample-1.2.3-x86_64.AppImage

I suggest you empty it or remove/recreate it at the end of each test, in order to rewrite the dotfiles using a clean configuration.

Repeat the build

If you encounter any problems after testing, manually edit the script by adding dependencies or keywords in the respective listed variables, then run the script again to build the AppImage.

./sample-junest.sh

This will repeat the construction of the AppImage starting from the shortcomings of the Arch Linux container.

On-screen messages will tell you what's happening.

Wait until the end and try the AppImage again.

Run the tests until you get the desired result.

Back to "Index"

Tutorial

This is a step-by-step tutorial on how to create an Archimage correctly. To write this one I tried to help a user into a comment, so I decided to publish it here too, with the same videos in real time.

In this example I'll build "Signal", available in Arch Linux as "signal-desktop", in "extra" (not an AUR package).

To create the basic script I'll use a standard configuration:

  1. name: signal-desktop
  2. name binary: leave blank, its the same
  3. dependences: none
  4. include all dependences: y
  5. use defaults: y

like this:

https://github.com/user-attachments/assets/06308a6d-24db-417f-917c-8e1a9d78fe0b

Once I created the script, I create a "tmp" directory (you can name it the way you want) and I put the script into it.

I run the script and after 2 minutes I got the AppImage.

The AppImage is 296 MB. Here is what happens when I run it:

https://github.com/user-attachments/assets/b0d6474c-c7bc-4df0-bc91-bcde8d764176

as expected, it does not work at first attempt. To fix it you can start to read the logs and see what files are missing, like this

https://github.com/user-attachments/assets/fed38d05-bf11-4804-9846-93e55e14e6b0

it is looking for a missing module named "xapp-gtk3-module", contained into a package to search on Google (or in my case via "Startpage"), in this case the package is "xapp". You can enter the page of the package and read the content, under "Package content".

All you need to do is to take note of the missing package and then add to dependences, like this:

https://github.com/user-attachments/assets/bbe35505-d8f9-489c-9e31-ef5713a7cc3c

and as you can see, "xapp" is downloaded and then it wil be extracted with all the other packages listed during this process in the "deps" directory.

Now the AppImage is increased of 0,1 MB, let we see if it works...

https://github.com/user-attachments/assets/5c832f45-e3fa-4a10-8b16-69f381492685

also this time it is not working, but I've found that there is a missing library "libgnomekbdui", contained in the "libgnomekbd" package... so I'll do the same as I did with xapp.

Now the package is 296,2 MB... let we see if it runs...

https://github.com/user-attachments/assets/bad4d6cc-a16c-498b-a9fa-528894c3cb8f

this time it is missing the library "libudev.so", I'll add the keyword "libudev" to $LIBSAVED, to fetch all files under /usr/lib containing this keyword, for this will be added all depending libraries and it too will be bundled in the AppImage.

In case it is not saved, search the package containing that library as I did with "xapp" and "libgnomekbd".

Now the package is 296,3 MB... let se again:

https://github.com/user-attachments/assets/bf6ff485-80b7-4c33-a753-19e8c2a08d74

Magic!

If the app works, you are good with it. Anyway it is still suggested to find missing libraries t mede it work as better as you can.

If you feel that the package is too big, use a tool like Baobab or "du" to find the big files or the ones that you think are unneeded.

You can also disable/comment the rsync command referencing to the content of the "deps" directory, not to include them all, and add only the keyworkd of missing libraries you will see usind LD_DEBUG, one by one.

To test the debloating, sun theAppRun script into the AppDir directory, it will run the program as it were the AppImage. Try to move elsewhere all files you think are unneeded, run the AppRun and see if it works. It the app still works without the files and directories you moved, take note of what you can remove and add the commands in the script, maybe under the "_remove_more_bloatwares" function.

If you do all this correctly, the package will be even smaller.

Back to "Index"

Compared to classic AppImage construction

In the past AppImages were built using .deb packages or guessing instructions to make them work. With the "ArchImage" method all you have to do is the reverse, i.e. "delete" what is no longer needed.

For example, an OBS Studio ArchImage equals 650MB in total, I managed to get it to 260MB by removing what wasn't necessary, while now (since Archimage2.x was released) is about 180MB.

This is a list of the AppImages I've built until I wrote this brief guide:

Advantages

Disadvantages

Drafts

You can download some experimental scripts made with this tool and to which I have not dedicated a repository (also because I have too many) at the following link:

https://github.com/ivan-hc/ArchImage/tree/main/drafts

in my experiments, if I uploaded them here, it means that they work quite well or at least start the graphical interface. I have not looked into their operation. If you want, you can download them and modify them to your liking, or even open a dedicated repository.

Files removed by default

After the line "# REMOVE SOME BLOATWARES" I added a list of functions that you can use with Archimage 2.x and above. You can edit the script as you like to add/remove files in case they are not enough for your experiments.

Back to "Index"

Troubleshooting

  1. If the AppImage is already bundled, extract the AppImage using ./*.AppImage --appimage-extract
  2. Execute the AppRun file:
./AppRun

In case you wont to parse dotfiles in your $HOME directory, use the AppDir itself as a custom $HOME, like this:

cd ./*.AppDir
HOME="$(dirname "$(readlink -f $0)")"
./AppRun

It is now possible to read errors related to the application.

For more verbose output, use LD_DEBUG, like this (for example, to know what are the missing libraries):

LD_DEBUG=libs ./AppRun

I redirect you to the guide on the usage of LD_DEBUG, at https://www.bnikolic.co.uk/blog/linux-ld-debug.html

See also

If you have any doubts you can open an issue or search for a solution among the existing ones (here).

Back to "Index"

Credits

This project wont be possible without:

Related projects

ko-fi.comPayPal.me"Index"