search

ivan-hc / AM

AppImage package manager to install, update (for real) and manage ALL of them (system-wide or locally) thanks to its ever-growing AUR-inspired database listing 2000+ portable apps and programs for GNU/Linux. The first, real centralized repository to manage your AppImages with the ease of APT and the power of PacMan.
https://portable-linux-apps.github.io
GNU General Public License v3.0
363 stars 27 forks source link
appimage appimage-collection appimage-repository cli installer updater

readme

"AM" Application Manager

Database & solutions for all AppImages and portable apps for GNU/Linux!

Istantanea_2024-06-26_17-00-46 png

"AM"/"AppMan" is a set of scripts and modules for installing, updating, and managing AppImage packages and other portable formats, in the same way that APT manages DEBs packages, DNF the RPMs, and so on... using a large database of Shell scripts inspired by the Arch User Repository, each dedicated to an app or set of applications.

The engine of "AM"/"AppMan" is the "APP-MANAGER" script which, depending on how you install or rename it, allows you to install apps system-wide (for a single system administrator) or locally (for each user).

"AM"/"AppMan" aims to be the default package manager for all AppImage packages, giving them a home to stay.

You can consult the entire list of managed apps at portable-linux-apps.github.io/apps.

Main Index

Differences between "AM" and "AppMan"

What programs can be installed

How to update all programs, for real

Installation

Uninstall

Usage (all the available options)

Guides and tutorials

Troubleshooting

Related projects

Differences between "AM" and "AppMan"

"AM" and "AppMan" differ in how they are installed, placed and renamed in the system and how/where they install apps:

Both can be updated using "Topgrade".

Ownership

About "sudo" usage

All options cannot be executed with "sudo".

How apps are installed

At first startup you can indicate any directory or subdirectory you want, as long as it is in your $HOME.

How to use "AM" in non-privileged mode, like "AppMan"

As already mentioned above, at "Ownership" the user who installed "AM" is the sole owner, having write permissions for both /opt/am and for all installed apps.

However, every user of the same system is allowed to use the option --user or appman, to use "AM" as "AppMan" and to install apps locally and withour root privileges:

am --user

To switch "AM" back to "AM" from "AppMan Mode", use the always suggested option --system:

am --system

To perform a test and see if you are in "AppMan Mode" or not, run for example the command am -f to see the list of the installed apps.

In this video I'll install LXtask locally:

https://github.com/ivan-hc/AM/assets/88724353/65b27cf6-edc5-4a4c-b2f9-42e8623dc76f

NOTE: non-privileged users can update their own local applications and modules, but cannot update /opt/am/APP-MANAGER.

It is therefore suggested to use pure "AppMan" instead of the "AppMan Mode" of "AM".

Install "AM"/"AppMan" Back to "Main Index"

What programs can be installed

"AM"/"AppMan" installs, removes, updates and manages only standalone programs, ie those programs that can be run from a single directory in which they are contained. The database aims to be a reference point where you can download all the AppImage packages scattered around the web, otherwise unobtainable, as you would expect from any package manager, through specific installation scripts for each application, as happens with the AUR PKGBUILDs, on Arch Linux. You can see all of them here, divided by architecture.

NOTE that currently my work focuses on applications for x86_64 architecture, but it is possible to extend "AM" to all other available architectures. If you are interested, you can deliberately join this project to improve the available lists.

  1. PROGRAMS, they are taken:

    • from official sources (see Firefox, Thunderbird, Blender, NodeJS, Chromium Latest, Platform Tools...);
    • extracted from official .deb/tar/zip packages;
    • from the repositories and official sites of individual developers.

  2. APPIMAGES, they are taken:

    • from official sources (if the upstream developers provide them);
    • from AppImage recipes to be compiled on-the-fly with pkg2appimage and appimagetool;
    • from unofficial third-party developers, but only if an official release is not available.

  3. FIREFOX PROFILES to run as webapps, the ones with suffix "ffwa-" in the apps list.

  4. THIRD-PARTY LIBRARIES (see here) if they are not provided in your distribution's repositories. These are to be installed in truly exceptional cases.

You can consult basic information, links to sites and sources used through the related command am -a $PROGRAM or appman -a $PROGRAM, or visit portable-linux-apps.github.io/apps.

Back to "Main Index"

How to update all programs, for real

One of the reasons why many users hate Appimages is because they cannot be updated. Or at least not all.

This project was born to dispel this myth and to solve the problem. And the solution is much more trivial than you expect.

There are several methods to update apps, here are the most common ones, in order of priority:

NOTE, fixed versions will be listed with their build number (e.g. $PROGRAM-1.1.1) or will be added only upon request.

How to update all installed apps

Option -u or update updates all the installed apps and keeps "AM"/"AppMan" in sync with the latest version and all latest bug fixes.

https://github.com/ivan-hc/AM/assets/88724353/f93ca782-2fc6-45a0-a3f2-1fba297a92bf

  1. To update only the programs, use am -u --apps / appman -u --apps
  2. To update just one program, use am -u $PROGRAM / appman -u $PROGRAM
  3. To update all the programs and "AM"/"AppMan" itself, just run the commandam -u / appman -u
  4. To update only "AM"/"AppMan" and the modules use the option -s instead, am -s / appman -s

NOTE, non-privileged users using "AM" in "AppMan Mode" cannot update /opt/am/APP-MANAGER (points 3 and 4). See "How to use AM in non-privileged mode, like AppMan".

How to update everything using "Topgrade"

Keeping your system up to date usually involves invoking multiple package managers. This results in big, non-portable shell one-liners saved in your shell. To remedy this, Topgrade detects which tools you use and runs the appropriate commands to update them.

Install the "topgrade" package using the command

am -i topgrade

or

appman -i topgrade

Visit github.com/topgrade-rs/topgrade to learn more.

NOTE, "AppMan" users must install appman in ~/.local/bin to allow updates via Topgrade. See "How to install AppMan".

Back to "Main Index"

Installation

This section explains how to install "AM" or "AppMan".

If you don't know the difference, please read "Differences between "AM" and "AppMan"" first.

Core dependences

Below are the essential system dependencies that you must install before proceeding:

Dependency only for "AM"

NOTE: use "AppMan" for non privileged use or if you prefer to gain administration privileges using alternative commands such as doas or similar.

Extra dependences (you may not need them)

The following are optional dependencies that some programs may require:

Proceede

How to install "AM"

"AM" is ment to be installed at system level to manage apps.

The script "INSTALL" is the one that take care of this.

Using "Wget"

wget https://raw.githubusercontent.com/ivan-hc/AM/main/INSTALL
chmod a+x ./INSTALL
sudo ./INSTALL

or directly

wget https://raw.githubusercontent.com/ivan-hc/AM/main/INSTALL && chmod a+x ./INSTALL && sudo ./INSTALL

Using "GIT"

git clone https://github.com/ivan-hc/AM.git
cd AM
chmod a+x INSTALL
sudo ./INSTALL

Structure of the "AM" installation

In both cases, the "INSTALL" script will create:

NOTE, if you don't feel comfortable having to always use root permissions, the installation method for "AppMan" is totally different. If you are interested, go to the next paragraph, else Back to "Main Index" or jump to "Usage (all the available options)".

How to install "AppMan"

"AppMan" can be used in different places, being it portable.

However, to be easily used its recommended to place it in your local "$PATH", in ~/.local/bin.

Use "AppMan" in "$PATH"

To do so, you must first enable that "$PATH":

To do all this quickly, simply copy/paste the following command:

mkdir -p ~/.local/bin && echo 'export PATH=$PATH:$(xdg-user-dir USER)/.local/bin' >> ~/.bashrc && wget https://raw.githubusercontent.com/ivan-hc/AM/main/APP-MANAGER -O appman && chmod a+x ./appman && mv ./appman ~/.local/bin/appman

Use "AppMan" in "Portable Mode"

"AppMan" can run in any directory you download it, copy/paste the following command to download "APP-MANAGER", rename it to appman and make it executable:

wget https://raw.githubusercontent.com/ivan-hc/AM/main/APP-MANAGER -O appman && chmod a+x ./appman

Structure of the "AppMan" installation

Unlike "AM" which needs to be placed in specific locations, "AppMan" is portable. The modules and directories will be placed in the directory you chose:

Back to "Main Index"

Uninstall

Note, before you remove your CLI, use the option -R to remove the apps installed using the following syntax:

am -R {PROGRAM1} {PROGRAM2} {PROGRAM3}...

or

appman -R {PROGRAM1} {PROGRAM2} {PROGRAM3}...

to have a list of the installed programs use the option -f or files (syntax am -f or appman -f).

See also "How to update or remove apps manually".

Back to "Main Index"

USAGE

 am {OPTION}

 am {OPTION} {ARGUMENT}
Click here to see the full list of options ___________________________________________________________________________ ## OPTIONS (standard, for both "AM" and "APPMAN") ___________________________________________________________________________ ___________________________________________________________________________ `-a`, `about` SYNOPSIS: `-a {PROGRAM}` DESCRIPTION: Shows more info about one or more apps, all the pages are downloaded from https://portable-linux-apps.github.io ___________________________________________________________________________ `-b`, `backup` SYNOPSIS: `-b {PROGRAM}` DESCRIPTION: Save the current version of one or more apps, each snapshot is stored into a dedicated directory, under $HOME/.am-snapshots/$PROGRAM To restore the snapshots see the "-o" option. ___________________________________________________________________________ `-c`, `clean` SYNOPSIS: `-c` DESCRIPTION: Removes all the unnecessary files and folders. ___________________________________________________________________________ `-d`, `download` SYNOPSIS: `-d {PROGRAM}` `-d --convert {PROGRAM}` DESCRIPTION: Download one or more installation scripts to your desktop. With the option "--convert" its converted to a standalone local installer, but AM requires AppMan to be installed to add custom directory settings. ___________________________________________________________________________ `-f`, `files` SYNOPSIS: `-f` `-f --byname` `-f --less` DESCRIPTION: Shows the list of all installed programs, with sizes. By default apps are sorted by size, use "--byname" to sort by name. With the option "--less" it shows only the number of installed apps. ___________________________________________________________________________ `-h`, `help` SYNOPSIS: `-h` DESCRIPTION: Prints this message. ___________________________________________________________________________ `-H`, `--home` SYNOPSIS: `-H {PROGRAM}` DESCRIPTION: Set a dedicated $HOME directory for one or more AppImages. ___________________________________________________________________________ `-i`, `install` SYNOPSIS: `-i {PROGRAM}` `-i --debug {PROGRAM}` `-i --force-latest {PROGRAM}` DESCRIPTION: Install one or more programs or libraries from the list. With the "--debug" option you can see log messages to debug the script. For more details on "--force-latest", see the dedicated option, below. ___________________________________________________________________________ `-l`, `list` SYNOPSIS: `-l` DESCRIPTION: Shows the list of all the apps available in the repository. ___________________________________________________________________________ `-o`, `overwrite` SYNOPSIS: `-o {PROGRAM}` DESCRIPTION: Overwrite the existing version of the app with a snapshot saved previously (see the option "-b", above). ___________________________________________________________________________ `-q`, `query` SYNOPSIS: `-q {KEYWORD}` `-q --pkg {PROGRAM1} {PROGRAM2}` DESCRIPTION: Can be used to search for keywords and terms in the list of available applications packages to display matches. This can be useful if you are looking for applications having a specific feature. Add the suboption "--pkg" to search only the names of one or more apps. ___________________________________________________________________________ `-r`, `remove` SYNOPSIS: `-r {PROGRAM}` DESCRIPTION: Removes one or more apps, requires confirmation. ___________________________________________________________________________ `-R` SYNOPSIS: `-R {PROGRAM}` DESCRIPTION: Removes one or more apps without asking. ___________________________________________________________________________ `-s`, `sync` SYNOPSIS: `-s` DESCRIPTION: Updates this script to the latest version hosted. ___________________________________________________________________________ `-t`, `template` SYNOPSIS: `-t {PROGRAM}` DESCRIPTION: This option allows you to generate a custom script from a list of different templates that may be vary according to the kind of app you want to upload to the "AM" repo, and the source where it is available. You can install it using the `am test /path/to/your-script` command. ___________________________________________________________________________ `-u`, `-U`, `update` SYNOPSIS: `-u` `-u apps` `-u {PROGRAM}` DESCRIPTION: Update all the apps (and "am" itself) or just one. If you add the "`--apps`" suboption you only update apps. ___________________________________________________________________________ `-v`, `version` SYNOPSIS: `-v` DESCRIPTION: Shows the version. ___________________________________________________________________________ `--disable-completion` SYNOPSIS: `--disable-completion` DESCRIPTION: Disable bash-completion. ___________________________________________________________________________ `--disable-sandbox` SYNOPSIS: `--disable-sandbox {PROGRAM}` DESCRIPTION: Disable the sandbox for the selected app. ___________________________________________________________________________ `--enable-completion` SYNOPSIS: `--enable-completion` DESCRIPTION: Enable bash-completion to complete a keyword with the "TAB" key, using the names of all installable applications available. ___________________________________________________________________________ `--force-latest` SYNOPSIS: `--force-latest {PROGRAM}` `-i --force-latest {PROGRAM}` DESCRIPTION: Downgrades an installed app from pre-release to "latest". This can be used with "-i" to force the installation of apps from "latest". Many scripts point to "releases" to find the latest build for GNU/Linux if the developer has not uploaded one in "latest". ___________________________________________________________________________ `--launcher` SYNOPSIS: `--launcher /path/to/${APPIMAGE}` DESCRIPTION: Embed one or more local AppImages in the applications menu. I suggest dragging the files into the terminal to get the desired effect. Launchers are located in ~/.local/share/applications/AppImages by default. ___________________________________________________________________________ `--rollback`, `downgrade` SYNOPSIS: `--rollback {PROGRAM}` DESCRIPTION: Download an older or specific version of the software you are interested in (only works with Github). ___________________________________________________________________________ `--sandbox` SYNOPSIS: `--sandbox {PROGRAM}` DESCRIPTION: Run an AppImage in a sandbox using Aisap. ___________________________________________________________________________ `apikey` SYNOPSIS: `apikey {Github Token}` `apikey delete` DESCRIPTION: Get unlimited access to https://api.github.com using your personal access tokens. The configuration file named "ghapikey.txt" will be saved in '$AMPATH' . Use the command "'$AMCLI' apikey delete/del/remove" to remove the file. __________________________________________________________________________ `dev`, `devmode` SYNOPSIS: `dev off` `dev on` DESCRIPTION: View the installer output during installation, use "on". It can be disabled with "off" or with the "`-s`" and "`-u`" options. __________________________________________________________________________ `lock` SYNOPSIS: `lock {PROGRAM}` DESCRIPTION: Lock the selected app to the current version installed, this only works if exists a dedicated "AM-updater" installed with the app. __________________________________________________________________________ `neodb` SYNOPSIS: `neodb` `neodb --silent` DESCRIPTION: Add third-party repos to extend the existing database. Use "--silent" to hide messages about third-party repos in use. __________________________________________________________________________ `newrepo` SYNOPSIS: `newrepo {URL}` `newrepo off` `newrepo on` DESCRIPTION: Set the variable "$AMREPO" to a new custom repository. Use "off" to restore the default one or overwrite it with a new one. __________________________________________________________________________ `nolibfuse` SYNOPSIS: `nolibfuse {PROGRAM}` DESCRIPTION: Convert an installed Type2 AppImage to a Type3 AppImage. Type3 AppImages does not require libfuse2 installed. __________________________________________________________________________ `unlock` SYNOPSIS: `unlock {PROGRAM}` DESCRIPTION: Unlock updates for the selected program. This option nulls the option "lock" (see above). ___________________________________________________________________________ ___________________________________________________________________________ ## EXTRA OPTIONS __________________________________________________________________________ `--system` SYNOPSIS: `--system` DESCRIPTION: Switch "AM" back to "AM" from "AppMan Mode" (see --user). __________________________________________________________________________ `--user`, `appman` (only available for "AM") SYNOPSIS: `--user` DESCRIPTION: Run "AM" as an unprivileged user making it act as "AppMan". __________________________________________________________________________
Install "AM"/"AppMan" Back to "Main Index"

Guides and tutorials

This section is committed to giving small demonstrations of each available option, with videos:

Install applications

Option -i or install, usage:

am -i $PROGRAM

or

appman -i $PROGRAM

in this video I'll install AnyDesk and LXtask:

https://github.com/ivan-hc/AM/assets/88724353/c2e8b654-29d3-4ded-8877-f77ef11d58fc

Back to "Guides and tutorials" Back to "Main Index"

List the installed applications

Option -f or files, it shows the installed apps, the version, the size and the type of application:

https://github.com/ivan-hc/AM/assets/88724353/a11ccb22-f2fa-491f-85dd-7f9440776a54

By default apps are sorted by size, use "--byname" to sort by name. With the option "--less" it shows only the number of installed apps.

am -f
am -f --byname
am -f --less

or

appman -f
appman -f --byname
appman -f --less
Back to "Guides and tutorials" Back to "Main Index"

List and query all the applications available on the database

Options -l or list shows the whole list of apps available in this repository.

Option -q or query shows search results from the list above.

https://github.com/ivan-hc/AM/assets/88724353/2ac875df-5210-4d77-91d7-24c45eceaa2b

Back to "Guides and tutorials" Back to "Main Index"

Update all

Option -u or update updates all the installed apps and keeps "AM"/"AppMan" in sync with the latest version and all latest bug fixes:

https://github.com/ivan-hc/AM/assets/88724353/f93ca782-2fc6-45a0-a3f2-1fba297a92bf

See "How to update all programs, for real".

Back to "Guides and tutorials" Back to "Main Index"

Backup and restore installed apps using snapshots

Backup

Option -b or backup creates a copy of the installed app into a dedicated directory under $HOME/.am-snapshots:

https://github.com/ivan-hc/AM/assets/88724353/ae581bc0-f1c5-47da-a2c4-3d01c37cc5a4

Each snapshot is named with the date and time you have done the backup. To restore the application to a previous version, copy/paste the name of the snapshot when the -o option will prompt it.

Restore

Option -o or overwrite lists all the snapshots you have created with the option -o (see above), and allows you to overwrite the new one:

https://github.com/ivan-hc/AM/assets/88724353/f9904ad2-42ec-4fce-9b21-b6b0f8a99414

Back to "Guides and tutorials" Back to "Main Index"

Remove one or more applications

Option -R removes the selected apps without asking (to have a prompt, use -r or remove):

https://github.com/ivan-hc/AM/assets/88724353/4d26d2d7-4476-4322-a0ab-a0a1ec14f751

Back to "Guides and tutorials" Back to "Main Index"

Convert Type2 AppImages requiring libfuse2 to Type3 AppImages

Option nolibfuse "just tries" to convert old Type2 AppImages asking for "libfuse2" into new Type3 AppImages:

https://github.com/ivan-hc/AM/assets/88724353/06b8e946-ef02-4678-a5a0-d8c2c24c22f9

First the selected program type is checked, if it is a Type2 AppImage, it will be extracted and repackaged using the new version of appimagetool from https://github.com/probonopd/go-appimage :

I suggest anyone to contact the developers to update the packaging method of their AppImage!

NOTE, the conversion is not always successful, a lot depends on how the program is packaged. The conversion occurs in two steps:

  1. if in the first case it succeeds without problems, the package will be repackaged as it was, but of Type 3;
  2. if the script encounters problems (due to Appstream validation), it will attempt to delete the contents of the /usr/share/metainfo directory inside the AppImage, as a workaround.

If also the second step does not succeed either, the process will end with an error and the AppImage will remain Type2.

Back to "Guides and tutorials" Back to "Main Index"

Integrate local AppImages into the menu by dragging and dropping them

If you are a user who is used to dragging your local AppImages scattered around the system and if you are a user who likes clutter and wants to place their packages in different places... this option is for you.

The option --launcher allows you to drag and drop a local AppImage to create a launcher to place in the menu, like any other classic AppImage helper would... but in SHELL.

This option also allows you to create a symbolic link or a shell script that calls your AppImage, to place in "~/.local/bin", so that you can call it from the terminal:

How to create a launcher for a local AppImage
am --launcher /path/to/File.AppImage

or

appman --launcher /path/to/File.AppImage
How to remove the orphan launchers

In case you move your AppImages somewhere else or remove them, use the following otion -c or clean to get rid of all the orphaned launchers and dead symlinks and scripts you created earlier:

am -c

or

appman -c

In the first video it shows three AppImages first positioned in one directory and then moved to another, in order to show you both how launchers are created (option "--launcher") and how to remove them (option "-c" , started first with the AppImage packages in the starting directory and then with the aforementioned moved elsewhere). The second video is a close-up on the terminal, to see in detail how the "--launcher" option works:

Video 1

https://github.com/ivan-hc/AM/assets/88724353/25d9df2b-3c4d-4494-8bbc-12e6ab2371fd

Video 2

https://github.com/ivan-hc/AM/assets/88724353/97c2b88d-f330-490c-970b-0f0bb89040dc

AppImages from external media

Another peculiarity concerns the use of the -c option on launchers created on AppImage packages placed on removable devices:

This is very useful if you have large AppImage packages that you necessarily need to place in a different partition.

Back to "Guides and tutorials" Back to "Main Index"

Sandbox an AppImage

Since version 6.12, "AM"/"AppMan" uses Bubblewrap for sandboxing AppImage packages, thanks to "Aisap", a highly intuitive and configurable command line solution.

The option "--sandbox", which since version 5.3 was using Firejail, has taken on a completely different appearance and usability, thanks to the intense work of @Samueru-sama, who managed to extend and enhance "Aisap", making it extremely easy to use in our project, to the point of making us forget that we are using a command line utility.

Bubblewrap is an highly used sanboxing solution, used in multiple projects for GNU/Linux, including Flatpak.

In this sense, "Aisap" may be considered a reference point for the future of AppImages sandboxing!

How to enable a sandbox

This method works as follows:

am --sandbox $APP

or

appman --sandbox $APP

The "aisap" package installed is required, whether it is available system-wide ("AM") or locally ("AppMan"), the important thing is that the "aisap" command is in $PATH. If it is not present, "AM"/"AppMan" will ask you if it can proceed with the installation before continuing.

We will first compile the Aisap script in a non-privileged, easy-to-access directory, before being placed in $PATH (see step 2, below).

  1. Once started, you will be asked whether to enable the sandbox (default "Y") or not (type "N"):
    • the main XDG directories (Pictures, Videos, Documents...) will be listed, answer whether to authorize access (type "Y") or not ("N", default);
    • at the end, choose whether to specify some directories to access (default "N"), and if "Yes", write the path.
  2. Now that the script is complete, it should be placed in $PATH. "AM" users will need to authorize writing to /usr/local/bin by entering their password. "AppMan" users do not have these problems;
  3. To allow Aipman take care of the AppImage, the latter be set to "not executable" and the related AM-updater will also have its chmod command set from a+x to a-x.
  4. Now your AppImage is in a sandbox!

NOTE, the default location for the sandboxed homes is at $HOME/.local/am-sandboxes, but that location can be changed by setting the $SANDBOXDIR environemt variable.

How to disable a sandbox

To remove the sandbox just run the command of the AppImage with the flag "--disable-sandbox", like this:

$APP --disable-sandbox

Sandboxing example

In the video below we will use "Baobab" (GTK3 version), a disk space analyzer, available in the database as "baobab-gtk3".

Among the XDG directories we will authorize "Images" (Pictures) and "Videos" (Videos), while manually we will authorize "Public". The test will be carried out in normal mode, then in sandbox and again without sandbox:

https://github.com/ivan-hc/AM/assets/88724353/dd193943-7b08-474a-bbbb-4a6906de8b24

About Aisap sandboxing

For more information about "Aisap", visit https://github.com/mgord9518/aisap

Available profiles are listed at https://github.com/mgord9518/aisap/tree/main/profiles

To learn more about permissions, see https://github.com/mgord9518/aisap/tree/main/permissions

EXTRA: The behavior of this option can be tested in a completely standalone way by consulting the repository of its creator, at Samueru-sama/aisap-am

Back to "Guides and tutorials" Back to "Main Index"

How to enable bash completion

Bash completion is enabled in "AM" on first installation, while the "AppMan" one requires to be enabled manually.

For both there are two options:

The file used by "AM" is "/etc/bash_completion.d/am-completion.sh", so the root password is required to use the options. The file used by "AppMan" instead is "$HOME/.bash_completion".

Both use the keywords to be completed listed within the "list" file, generated from the options list and the applications list.

https://user-images.githubusercontent.com/88724353/155971864-783c098c-e696-47b5-aaa8-85dab6ab3b46.mp4

A more detailed guide on how to create your own bash completion script for your project is available here.

Back to "Guides and tutorials" Back to "Main Index"

How to update or remove apps manually

Inside each installed applications directory, there are two scripts called "AM-updater" and "remove", and their purpose is indicated in their name:

Downgrade an installed app to a previous version

Use the --rollback option or downgrade in this way:

am --rollback ${PROGRAM}

This only works with the apps hosted on Github.

https://github.com/ivan-hc/AM/assets/88724353/8f286711-7934-461a-8bc2-b3a3e1d5f269

Back to "Guides and tutorials" Back to "Main Index"

Create and test your own installation script

Option -t or template allows you to create an "AM" compatible installation script using a "templates" that can be used by both "AM" and "AppMan". In fact, all AppMan does is take the installation scripts from this database and patch them to make them compatible with a rootless installation.

The syntax to follow is this

am -t $PROGRAM

or

appman -t $PROGRAM

The available options are as follows:

  1. Create a script for an AppImage package
  2. Build an AppImage on the fly using appimagetool and pkg2appimage
  3. Download and unpack a generic archive (ZIP, TAR...)
  4. Create a custom Firefox profile

To learn more about a specific option, use the index below

Otherwise, go directly to the last paragraphs, which are

Istantanea_2024-06-17_21-35-26 png

Option Zero: "AppImages"

The easiest script to create is certainly the one relating to AppImages, the "Zero" option.

  1. Enter the URL of the site
    • if the AppImage is hosted on github, it will quickly detect the URL
    • if the AppImage is not hosted on github,it will ask you to add a description of the app
  2. Detecting the correct URL
    • if the app is hosted on github, it will ask you if you want to add/remove keywords to use in grep, to detect the correct URL, else press ENTER
    • if the app is not hosted on github, add a one-line command to detect the latest version of the app (advanced)

In this video I'll create 2 installation scripts:

https://github.com/ivan-hc/AM/assets/88724353/b6513e8a-17ab-4671-baf7-d86183d57c11

Option One: "build AppImages on-the-fly"

This was one of the very first approaches used to create this project. Before I started building AppImage packages myself, they were first compiled just like using any AUR-helper.

The syntax seems simple, but you have to know what you're building.

You'll need to decide what kind of AppImage you want to build on the fly, whether to include a custom AppRun, "libunionpreload", and detect system libraries.

It will be used as the Debian base, but you can manually modify the script to suit your needs.

In this example I'll create the script for Abiword with "AM" and I'll install it using AppMan:

https://github.com/ivan-hc/AM/assets/88724353/6ae38787-e0e5-4b63-b020-c89c1e975ddd

Option Two: "Archives and other programs"

Option two is very similar to option zero. What changes is the number of questions, which allow you to customize both the application's .desktop file and the way a program should be extracted.

This script also supports extraction of 7z, tar and zip files, if those archives are downloaded instead of a standalone binary.

By default, the install script does not have a launcher and icon. To create one, press "Y", otherwise, press "N" or leave it blank. This is useful if you want to load scripts or tools that can be used from the command line.

This option may be used also for AppImages, if you need to customize the launcher.

Tu add an icon, you need an URL to that, but if you don't have one, just leave blank. The script will download an icon from portable-linux-apps.github.io if it is hosted there, when running the installation script.

In this example, I'll use OBS Studio AppImage.

https://github.com/ivan-hc/AM/assets/88724353/ce46e2f2-c251-4520-b41f-c511d4ce6c7d

Option Three: "Firefox profiles"

Option 3 creates a launcher that opens Firefox in a custom profile and on a specific page, such as in a WebApp. I created this option to counterbalance the amount of Electron/Chrome-based applications (and because I'm a firm Firefox's supporter).

How an installation script works

The structure of an installation script is designed for a system-wide installation, with "AM", since it is intended to be hosted in the database. But every path indicated within it is written so that "AppMan" can patch the essential parts, to hijack the installation at a local level and without root privileges:

  1. In the first step, the variables are indicated, such as the name of the application and a reference to the source of the app (mostly used in --rollback or downgrade);
  2. Create the directory of the application;
  3. The first file to be created is "remove", to quickly remove app's pieces in case of errors;
  4. Create the "tmp" directory, in which the app will be downloaded and, in the case of archives, extracted;
  5. Most scripts contain a "$version" variable, a command to intercept the URL to download the app. If the URL is linear and without univoque versions, "$version" can be used to detect a version number. Then save the value into a file "version" (this is important for the updates, see point 7);
  6. Downloading the application (and extract it in case of archive);
  7. Create the "AM-updater" file, the script used to update the app. It resumes points 4, 5 and 6, with the difference that the "$version" variable we have saved at point 5 is compared with a new value, hosted at the app's source;
  8. Creation/extract/download launcher and icon, the methods change depending on the type of application. For AppImages they are extracted from the package.

How to test an installation script

To install and test your script, use the command

am -i /path/to/your-script

or

appman -i /path/to/your-script

To debug the installation, add the option --debug, like this

am -i --debug /path/to/your-script

or

appman -i --debug /path/to/your-script

Third-party databases for applications (NeoDB)

"AM"/"AppMan" can be extended by adding new application databases using a configuration file named "neodb".

For more details, see the full guide at https://github.com/ivan-hc/neodb

Install "AM"/"AppMan" Back to "Guides and tutorials" Back to "Main Index"

Troubleshooting

An application does not work, is old and unsupported

Use the -a option and go to the developer's site to report the problem. The task of "AM" is solely to install / remove / update the applications managed by it. Problems related to the failure of an installed program or any related bugs are attributable solely to its developers.

Cannot download or update an application

There can be many reasons:

Back to "Troubleshooting" Back to "Main Index"

Cannot mount and run AppImages

If by running it in the terminal you get an error message about "FUSE" or "libfuse"/"libfuse2" missing, take a look at the official documentation:

https://docs.appimage.org/user-guide/troubleshooting/fuse.html

If your distro does not provide libfuse2, you can install it using the command:

am -i libfuse2

or

appman -i libfuse2

NOTE, in AppMan you still need to use your password (sudo) to install the library at system level, in /usr/local/lib

Alternatively you can use the "nolibfuse" option to "try" to convert old Type2 AppImages to Type3, so as not to depend on libfuse2. In most cases it works, but sometimes it can give errors, depending on how the package was manufactured.

However, I suggest contacting the upstream developers to convince them to upgrade their packages to Type3.

Back to "Troubleshooting" Back to "Main Index"

Spyware, malware and dangerous software

Before installing any application, try to know where it comes from first. This program provides you with two basic options for this purpose:

“AM” and AppMan are just tools to easily install all listed programs, but what you choose to install is your complete responsibility. Use at your own risk!

Back to "Troubleshooting" Back to "Main Index"

Stop AppImage prompt to create its own launcher, desktop integration and doubled launchers

Some developers insist on creating Appimages that create their own launcher on first launch (like WALC and OpenShot). If the official solution proposed here doesn't work, you have two options to escape this trouble: "-H" and "--sandbox".

1. Option "-H" or "home": create a .home directory for the AppImage

Use the option -H, then launch the app and accept the request. Dotfiles and launcher will be saved in the $APP.home near the AppImage:

am -H $APP
$APP

or

appman -H $APP
$APP

you can also use the AppImage's builtin option --appimage-portable-home from the terminal:

$APP --appimage-portable-home

This method works in the 99% of cases.

2. Option "--sandbox": run the AppImage into a Aisap/bubblewrap sandbox

Use the option --sandbox, then launch the app and accept the request. Dotfiles and launcher will be saved in the dedicated sandbox:

am ---sandbox $APP
$APP

or

appman --sandbox $APP
$APP

This is the best method, since you decide wheter to allow the use of user's directories or not.

For more details, see "Sandbox an AppImage".

Back to "Troubleshooting" Back to "Main Index"

The script points to "releases" instead of downloading the latest stable

This is a choice I made as many developers have abandoned support for AppImage or GNU/Linux in general. My aim here is to introduce you to other developers' applications, then it's up to you to contact them, support them, help improve the software through forks and pull requests, opening issues and encouraging developers to keep the software in the format you prefer.

In case you are sure that the upstream developer will maintain the package for each stable release, you can fix this in several ways:

Method 1: Direct installation by combining -d and -i options

am -d $PROGRAM
sed -i 's#releases -O -#releases/latest -O -#g' $(xdg-user-dir DESKTOP)/$PROGRAM
am -i $(xdg-user-dir DESKTOP)/$PROGRAM

Method 2: "Downgrade" the installed app to "latest"

Use the option --force-latest to patch the AM-updater and perform the "update"/"downgrade":

am --force-latest $PROGRAM

or do it manually:

sed -i 's#releases -O -#releases/latest -O -#g' /opt/$PROGRAM/AM-updater
am -u $PROGRAM

Wrong download link

The reasons may be two:

Back to "Troubleshooting" Back to "Main Index"

Related projects

External tools and forks used in this project

My other projects

You can support me and my work on ko-fi.com and PayPal.me. Thank you!

© 2020-present Ivan Alessandro Sala aka 'Ivan-HC' - I'm here just for fun!

ko-fi.com PayPal.me Install "AM"/"AppMan" "Main Index"