rinstall

rinstall is an helper tool that installs software and additional data into the system. Many programs often include man pages, documentation, config files and there is no standard way to install them except for using Makefiles or complete build system. However, Makefiles are notoriously complicated to setup; it is especially hard to follow the Directory Variables from the GNU Coding Standard.). Build systems instead cover the installation part but depending on an entire build system to install a shell script or a rust binary is not optimal. You can read more of rinstall rationale here.

rinstall read a declarative YAML file (install.yml) containing the list of the files to install. It then installs the program either system-wide or for the current user (following the XDG BaseDirectories). It reads the default configuration for the system from /etc/rinstall.yml or .config/rinstall.yml, using a default one otherwise.

Features

• List the files to install and their location in a declarative way
• Ensure backward compatibility (no need to update install.yml every new rinstall version)
• Support for both user and system-wide installation
• Works inside the codebase or from the release tarball
• Native support for Rust programs and cargo
• Easy uninstallation of packages
• Allow templating of documentation and man pages
• Support for GNU Directory standard, FHS and XDG BaseDirectories, with optional configuration
• Support most common types of files
• Reproducible installation
• Packagers friendly

Build

To build from source run the following command:

$ cargo build --release

To install rinstall for the current user:

$ ./target/release/rinstall install -y

Usage

If the project has an install.yml file present, either in the root directory or in the .package directory, it supports installation via rinstall.

Run rinstall as your user to see the changes that will be done to the filesystem:

$ rinstall install

After having reviewed the changes, add -y or --yes to perform an user installation:

$ rinstall install --yes

The same apply for performing a system-wide installation, enabled by adding the flag --system. To list the changes made to the filesystem, run rinstall in dry mode (i.e. without the flag--yes):

$ rinstall install --system

To accept the changes, run again the command and append the flag -y or --yes. You need to run the command as root to apply the changes to the filestem.

# rinstall install --system -y

Uninstall

When a package gets installed, a file with the suffix .pkg will be created inside $localstatedir/rinstall (by default /usr/local/var/ rinstall for system installations and $HOME/.local/share/rinstall for user installations). This file will contain the list of installed files, allowing the the uninstall subcommand to revert the installation of a package:

$ rinstall uninstall wpaperd
Would remove /home/danyspin97/.local/bin/wpaperd
Would remove /home/danyspin97/.local/bin/wpaperctl
Would remove /home/danyspin97/.local/share/bash-completion/wpaperd.bash
Would remove /home/danyspin97/.local/share/licenses/wpaperd/LICENSE.md
Would remove /home/danyspin97/.local/share/rinstall/wpaperd.pkg

Packagers

rinstall support the packagers use-case out of the box. When calling rinstall inside a package specification (i.e. spec file, PKGBUILD, ebuild), add the --packaging flag and it will enable all relevant flags and ask you the needed information:

$ rinstall install --packaging --destdir mydestdir
>>> Package rinstall
Would install target/release/rinstall -> mydestdir/usr/local/bin/rinstall
Would install target/release/man/rinstall.1 -> mydestdir/usr/local/share/man/man1/rinstall.1
Would install README.md -> mydestdir/usr/local/share/doc/rinstall/README.md
...

Release tarballs

rinstall supports installing from release tarballs (i.e. the tarballs published on Github for each release containing a compiled version of the program).

To allow a program to be installed from a release tarball create a .tarball empty file during the generation and include install.yml. rinstall will then assume that all the files are in the top directory and proceed to install them as usual; this means that for Rust programs, the executables will be searched in the top directory instead of target/release. Please assure that all the files listed in install.yml are included in the tarball.

Configuration

The installation directories chosen by rinstall can be configured by adding and tweaking the file rinstall.yml under the sysconfdir. By default, /etc/rinstall.yml and $HOME/.config/rinstall.yml will be used respectively for the root user and the non-root user.

The root configuration should already be installed by the rinstall package of your distribution and it can also be found in the config/root/ directory of this repository; the non-root user configuration can be found in the config/user/ directory. All the placeholders will be replaced at runtime by rinstall.

Additionally, a different configuration file can be passed by using the --config (or -c) command line argument. All the values can also be overridden when invoking rinstall by using the respective command line arguments.

The configuration is a YAML file that can contain the following keys. If any of them is missing, a default value will be used instead.

• bindir
• libdir
• datarootdir
• datadir
• sysconfdir
• localstatedir
• runstatedir
• systemd_unitsdir

In addition, the system-wide configuration can contain the following keys:

• prefix
• exec_prefix
• sbindir
• libexecdir
• includedir
• docdir
• mandir
• pam_modulesdir

Please refer to the Directory Variables for their usage.

If any key is missing,

Placeholders in configuration

Root user configuration

In the configuration you may want to set a value based on another directory set prior. For example you may want bindir to be a directory bin relative to the exec_prefix directory. rinstall supports placeholders in the configuration to allow this:

exec_prefix: /usr/local
bindir: @exec_prefix@/bin

The root user configuration allows for the following placeholders:

• @prefix@, supported by all values
• @exec_prefix@, supported in bindir and libdir
• @localstatedir@, supported in runstatedir
• @datarootdir@, supported in docdir and mandir
• @libdir, supported in pam_modulesdir and systemd_unitsdir

Non-root user configuration

Non-root user configuration relies on XDG Directories, so it allows placeholders that refer to these values. The placeholders will be replaced by the environment variable and, if it is not set, it will fallback on a default value:

datadir: @XDG_DATA_HOME@
sysconfdir: @XDG_CONFIG_HOME@

The non-root user configuratione supports for the following placeholders:

• @XDG_DATA_HOME@, supported in datarootdir and datadir
• @XDG_CONFIG_HOME@, supported in sysconfdir and systemd_unitsdir
• @XDG_STATE_HOME@, supported in localstatedir
• @XDG_RUNTIME_DIR@, supported in runstatedir
• @sysconfdir@, supported in systemd_unitsdir

<pkg-name>

An additional placeholder used when configuring the directories is <pkg- name>; this will automatically be replaced by the package name used inside install.yml. Some directories (e.g. docdir use this placeholder by default). Manually set the directories to remove it.

Writing install.yml

To support rinstall, place an install.yml file into the root of your project. It shall contain the rinstall version to use and the packages to install. Each package shall contain the entries of the files to install, divided by their purpose/destination.

Example file for a program named foo written in Rust that only install an executable with the same name:

rinstall: 0.1.0
pkgs:
  foo:
    type: rust
    exe:
      - foo

install.yml examples

• kanidm
• wpaperd
• dog in openSUSE
• myxer in openSUSE

rinstall version

each rinstall release will have a respective version of the spec file; each version might support new entry types but it might remove support for some as well. rinstall will support older releases, along with all its entry types which were allowed.

Packages

rinstall support the installation of multiple packages from the same repository. Put all the packages under a unique name inside the key pkgs in the install.yml file (even if there is only one package):

rinstall: 0.1.0
pkgs:
  foo:
    type: rust
    exe:
      - foo
  bar:
    type: rust
    exe:
      - bar
  bar-c:
    include:
      - bar.h

Entries

Each entry list a file to install and it shall either be a string or a struct containing the following data:

• src: the source, containing the location to the file that will be installed. Unless noted, it shall always be relative to the project