README

grmpf

The Generic Repository and Miscellaneous sources Packagey Frobnicator

Description

grmpf is a package manager for unpackaged software.

It is currently still a work in progress, and so is this readme file.

The basic idea is to have a simple installation manager, which can install software from different, but unpackaged, sources like github or web pages either locally into ~/.local or globally into /usr/local. Where grmpf is exceeding the capabilities of a simple make install is that grmpf can also check for updates and update the installed software. Just like a package manager would.

Building and installing

grmpf is developed on linux. Other unixen may also work, I have not tested this. Windows will definitely not work.

In order to install grmpf, either clone the repo or download and unpack the tarball of the latest tag. Then enter the source directory and type

$ make bootstrap

grmpf will now install itself using itself. You can verify that this worked by typing

$ grmpf list

The output should be something like

grmpf   v0.9.4  local

Principles of operation

grmpf works by installing each downloaded software into a directory under $PREFIX/lib/grmpf, where $PREFIX is the installation prefix directory. For global installations, this is /usr/local, and for per-user installations it is ~/.local.

For a package pkg, a directory $PREFIX/lib/grmpf/pkg is created, which holds the management data, and within this directory another directory called package is created, which holds the actual software. This directory $PREFIX/lib/grmpf/pkg/package is known as the package dir. The idea is that everything that makes up the software, including configuration files, is stored in the package dir, and the installation consists of creating symbolic links within $PREFIX/bin, $PREFIX/lib and so on to things stored in the package dir.

packages are described using grmpfiles, which are yaml files. These are described in a separate document [doc/grmpfiles.md]. Also check out the grmpfiles folder in the source tree, especially example.grmpf for a heavily commented example using most options. grmpfiles may be used from your local disk or from a url. This allows a software project to provide a grmpfile for installation that can then directly be used from the url where it is stored. For example, my project exdehl now comes with a grmpfile, that allows you to install exdehl by entering

grmpf install https://codeberg.org/gnarz/exdehl/raw/branch/main/exdehl.grmpf

More info on some specific aspects is given below where the subcommands are described.

Using grmpf

grmpf has a few subcommands that do the work. The basic format is:

grmpf cmd [options] [arguments]

The commands are:

install grmpfile+  install one or more packages
remove pkg+        uninstall one or more packages
pin pkg+           pin a package to it's currently installed version
unpin pkg+         remove a pin on a package
check pkg*         check whether packages have updates
update pkg*        update packages for which there are updates
list               list installed packages
info pkg*          get information about packages
bootstrap          install grmpf using itself
version            display grmpf version
help               display this help

options are:

-v, --verbose      run verbosely
-q, --quiet        run quietly
-r, --reinstall    same as remove followed by install (install only)
-f, --force        enforce operation (remove and update only)
-a, --all          execute in any environment (not for install)
-g, --global       execute in global environment
-l, --local        execute in local (per user) environment.
-V, --version no   target version to install, if not latest (install only)
-h, --help         Prints this help

Info on the subcommands follows.

install

install [-v|-q] [-l|-g] [-V version] [-r] grmpfile+

install one or more packages. With the -l flag, the package is installed in the local prefix, and with the -g flag, it is installed in the global prefix. Note that when using -g, you will most probably have to call grmpf with sudo.

Using the -r flag is akin to first uninstalling and then reinstalling a package.

Each grmpfile argument may be either a path to a local file, a url, or a -. In the latter case, the grmpfile is read from stdin. This allows for example the use in a shell script with the grmpfile being provided in a HEREDOC instead of a separate file.

The installation process follows the sections in the grmpfile, see [doc/grmpfile.md] for details. In broad terms, it goes like this:

After installation, the data from the grmpfile is stored in the packages manifest, along with some information about what was installed where. For all further operations on the package, like check, update or remove, this copy of the original grmpfile data is used.

remove

remove [-v|-q] [-a|-l|-g] [-f] pkg+

uninstall one or more packages. With the -l flag, the package is removed from the local prefix, with -g it is removed from the global prefix, and with the -a flag, it is removed from any or both prefixes.

Normally when uninstalling, all the links that were created during the installation process are removed, and then the directory under $PREFIX/lib/grmpf where the package is stored is removed. Then, the remove script is run, if there is one.

However, it may happen that you have remains of a package that was either unsuccessfully removed or installed and thus is not in a state that it can be processed by the standard remove process. In this case, you can call remove with the -f flag. This will remove the directory unter $PREFIX/lib/grmpf where the package is stored, and then search $PREFIX for any symlinks pointing tnto the removed directory and remove those as well. Depending on the size of $PREFIX, this may take some time and it is intended as a last resort rather than a “normal” way of removing packages. In this case, the remove script is also run after the removal of the package data, if the manifest could still be found and there is a remove script.

pin

pin [-v|-q] [-a|-l|-g] pkg+

pin a package to it’s currently installed version. The -a/-l/-g flags work as for remove.

unpin

unpin [-v|-q] [-a|-l|-g] pkg+

remove a pin on a package. The -a/-l/-g flags work as for remove.

check

check [-v|-q] [-a|-l|-g] pkg*

check whether packages have updates. The -a/-l/-g flags work as for remove. If the pkg argument is omitted, all packages are checked. Otherwise, only those listed with the check argument are checked.

update

update [-v|-q] [-a|-l|-g] [-f] pkg*

update packages for which there are updates. The -a/-l/-g flags work as for remove.

The update process goes like this:

update may be called with the -f flag in order to force an update, regardless of whether a new version is available or not.

list

list [-a|-l|-g]

list installed packages, together with the installed version and the install location (local or global). The -a/-l/-g flags work as for remove.

info

info [-a|-l|-g] pkg*

get information about packages. For each package listed, grmpf shows it’s name, currently installed version, whether an update is available, and the path to the installation. The -a/-l/-g flags work as for remove.

A note on security

While a certain effort is made to detect unannounced sudo commands, it is still very much possible that the install script in a grmpfile may hide a call to sudo and do nefarious things. Always check the grmpfiles to be sure. Also, you should probably not allow sudo without password. Like, ever.

Then again, you are installing software from some uncurated source on the internet, so you hopefully know what you are doing. Also, you will most probably be creating most of the grmpfiles you use yourself, so there’s that.

Once a software is installed, grmpf will use the original grmpfile for all further actions like update and remove. The grmpfile will not be modified or downloaded again, unless you force a reinstall.

More information

check out the doc directory for more information. The following files are available: