installtool: clarify roles, then name, implement and document properly

[ndim]

As we discovered in https://github.com/socratools/socranop/issues/63, the socranop installtool socranop-installtool plays different roles, and the naming of these roles and therefore the actual roles are confusing. We should name things better, and fix the issues caused by the unclear roles.

• Run after pip install socranop to complete the installation (socranop-installtool --post-install)

  • copies a number of files to well known locations (e.g. icon files)
  • creates and writes a number of files adapted for its socranop installation to well known locations (e.g. D-Bus service file, desktop file for the GUI, udev rules file)
  • "if necessary", move privileged writing of files to a shell script to be run with sudo after inspection of the script by the user
  • "if necessary", run commands telling the system about the files it has just written (at this time, only one udevadm trigger command for each of the three supported USB devices) Incidentally, the command running part only happens in the sudo script which the socranop-installtool --post-install run generates, and therefore can only be executed after socranop-installtool has finished.

  A more accurate name for this would be --post-pip-install.

• Run before pip uninstall socranop to prepare the uninstall (socranop-installtool --pre-uninstall)

  • remove a number of files from well known locations (e.g. icon files)
  • remove a number of files from well known locations (e.g. D-Bus service file, desktop file for the GUI, udev rules file)
  • "if necessary", move privileged removing of files to a shell script to be run with sudo after inspection of the script by the user
  • "if necessary", run commands telling the system about the files it has just removed (TODO udevadm trigger commands for each of the three supported USB devcies) Incidentally, the command running part only happens in the sudo script which the socranop-installtool --pre-install run generates, and therefore can only be executed after socranop-installtool has finished, i.e. after the files have actually been removed.

  A more accurate name for this would be --pre-pip-uninstall.

• Run while building an OS binary package like *.rpm, *.deb, an AUR package, etc. Confusingly, this is also called socranop-installtool --post-install at this time, but with --chroot CHROOT attached.

  • copies a number of files to well known locations (e.g. icon files)
  • creates and writes a number of files adapted for its socranop installation to well known locations (e.g. D-Bus service file, desktop file for the GUI, udev rules file)
  • as all writing happens into a chroot buildroot, we expect to have the necessary privilege to write to that buildroot
  • TODO: Unclear what to do about the udevadm trigger commands. Perhaps write them to a script which the package can then ship or copy and run post package install, post package uninstall, and post package update (in case the udev rules file has changed from the old to the new package)?

  A more accurate name for this could be... --package-build-install, or... --FIXME?

Probably more aspects to follow.

[ndim]

So...

socranop-installtool
====================

Help with the parts of socranop installation and setup, and reversing installation and setup, which exceed Python's builtin install and uninstall capabilities. This comprises

  * checking library dependencies are installed
  * bash completion files for the executables
  * D-Bus service file
  * Man page files
  * XDG desktop and icon files
  * Linux udev rules file

Arguments:
  -h, --help    Show help text and exit
  -V, --version Show software version and exit
  -n, --dry-run Do not actually do anything, just show what would be done.

socranop-installtool post-pip-install
-------------------------------------

To be run after `pip install socranop`, `pip install --user socranop`, and similar `pipenv` and `pip` based installations.

Arguments:
  --no-launch  Do not launch the socranop D-Bus service. Optional argument.
  --sudo-script FILENAME
               The FILENAME to write the sudo script to, with commands to be run by privileged users. Optional argument.

socranop-installtool pre-pip-uninstall
--------------------------------------

To be run before `pip uninstall socranop`, `pip uninstall --user socranop`, and similar `pipenv` and `pip` based uninstalls.

Arguments:
  --sudo-script FILENAME
               The FILENAME to write the sudo script to, with commands to be run by privileged users. Optional argument.

socranop-installtool package-build-install
------------------------------------------

To be run while building a package, namely in the install part of the package where the software is installed into the package buildroot chroot environment.

Arguments:
  --chroot CHROOT  The package buildroot chroot environment. Mandatory argument.

[ndim]

Here is a section on

Why socranop-installtool?

The stock python packaging infrastructure has between no and limited support for installing configuration and resource files into well-known system directories where they configure system services to integrate a python application like socranop with the system.

For socranop, there are two classes of these configuration and resource files:

• Files installed verbatim (partially supported by setuptools)

  While we could use something like

  data_files=[
      ('share/icons/hicolor/16x16/apps', ['socranop/data/xdg/io.github.socratools.socranop.16.png']),
      ...
      ('share/icons/hicolor/scalable/apps', ['socranop/data/xdg/io.github.socratools.socranop.svg']),
  ],

  to install some data files for pip install and pip install --user type installs, this does not install any files for pip install -e . development installs.

  Additionally, data_files are installed into the data directory which is .../share, so this does not help with udev rules which go either into /etc/udev/rules/ or into /usr/lib/udev/rule.

  The file sets we need to deal with here

  • bash completion files
  • udev rules files
  • XDG icon files

• Files needing adaptation (not supported by setuptools at all)

  Some configuration and resource files need some adaptation:

  • D-Bus .service file (installation path)
  • Man pages (installation path, package version)
  • XDG .desktop file (installation path)

  setuptools does not support such text substitutions at all.

While there might be a way to hook substitution and install location support into the more modern python packaging which uses pyproject.toml with a backend other than setuptools, those do appear to support editable development installations at all.

While there is https://pypi.org/project/install-freedesktop/ which works for .desktop files and icon files, it does not with all types of installations either or do adaptations for any other files besides .desktop.

So we put the content substitutions and the file installations into our own installation tool and called it socranop-installtool.