Merge pull request #201 from mariux64/add-prun-documentation

prun: Add documentation in markdown format

.gitignore

@@ -1 +1,2 @@
 setuid/setuid
+prun/*.1

Makefile

@@ -64,13 +64,18 @@ INSTALL=install -v
 INSTALL_PROGRAM = $(INSTALL)
 INSTALL_DATA = $(INSTALL) -m 644
 
-all:
-	@echo 'Nothing to be done. Ready for "make install"'
+manpages += prun/prun.1 prun/pman.1 prun/ptype.1
 
-install:
+all: $(manpages)
+
+clean:
+	@rm -f $(manpages)
+
+install: all
 	@prefix="$(prefix)" usr_prefix="$(usr_prefix)" usrlocal_prefix="$(usrlocal_prefix)" \
 	root_exec_prefix="$(root_exec_prefix)"         root_bindir="$(root_bindir)"    root_sbindir="$(root_sbindir)" \
 	usr_exec_prefix="$(usr_exec_prefix)"           usr_bindir="$(usr_bindir)"      usr_sbindir="$(usr_sbindir)" \
+	usr_mandir="$(usr_mandir)" \
 	usrlocal_exec_prefix="$(usrlocal_exec_prefix)" usrlocal_bindir="$(usrlocal_bindir)" usrlocal_sbindir="$(usrlocal_sbindir)" \
 	sysconfdir="$(sysconfdir)"                     systemdunitdir="$(systemdunitdir)" \
 	udev_rulesdir="$(udev_rulesdir)"               udev_helperdir="$(udev_helperdir)" \
@@ -79,6 +84,8 @@ install:
 	DESTDIR="$(DESTDIR)" \
 	./install.sh
 
-.PHONY: all install
-
+.PHONY: all install clean
 
+%.1: %.md
+	@if [ "$$UID" = 0 ]; then echo "Please build (\`make\`) as non-root before running \`make install\` as root" >&2;exit 1;fi
+	pandoc --standalone --to man $< -o $@

install.sh

@@ -21,6 +21,7 @@ fi
 : ${usr_exec_prefix:=$usr_prefix}
 : ${usr_bindir:=$usr_exec_prefix/bin}
 : ${usr_sbindir:=$usr_exec_prefix/sbin}
+: ${usr_mandir:=$usr_exec_prefix/man}
 
 : ${usrlocal_exec_prefix:=$usrlocal_prefix}
 : ${usrlocal_bindir:=$usrlocal_exec_prefix/bin}
@@ -223,6 +224,9 @@ install_data mxshadow/mxshadow.conf                       "$DESTDIR$sysconfdir/m
 install_data mxshadow/mxshadow.service                    "$DESTDIR$systemdunitdir/mxshadow.service"
 install_data misc_etc_files/nsswitch.conf                 "$DESTDIR$sysconfdir/nsswitch.conf"
 install_exec vmcontrol/vmcontrol.pl                       "$DESTDIR$usr_bindir/vmcontrol.pl"
+install_data prun/prun.1                                  "$DESTDIR$usr_mandir/man1/prun.1"
+install_data prun/ptype.1                                 "$DESTDIR$usr_mandir/man1/ptype.1"
+install_data prun/pman.1                                  "$DESTDIR$usr_mandir/man1/pman.1"
 
 postinstall
 exit

prun/pman.md

@@ -0,0 +1,37 @@
+% PMAN(1) | Mariux Tools Documentation
+
+NAME
+====
+
+**pman** - view manual pages installed in Mariux packages.
+
+SYNOPSIS
+========
+
+| **pman command**
+
+DESCRIPTION
+===========
+
+**pman** uses the PATH set in the package wrapper and tries to find a manual page in the package directory.
+
+EXAMPLES
+========
+
+**display manpage found in /pkg/stellarium-0.21.0-0/share/man/man1**
+: pman stellarium
+
+
+BUGS
+====
+
+**pman** is very naive in looking up man pages, so your mileage may vary.
+
+See GitHub Issues: <https://github.molgen.mpg.de/mariux64/mxtools>
+
+SEE ALSO
+========
+
+**prun(1)**, **ptype(1)**, **man(1)**
+
+

prun/prun.md

@@ -0,0 +1,96 @@
+% PRUN(1) Version n/a | Mariux Tools Documentation
+
+NAME
+====
+
+**prun** - Run Mariux packages (reads 'Package RUN').
+
+SYNOPSIS
+========
+
+| **prun package command** [COMMANDOPTION]...
+
+DESCRIPTION
+===========
+
+Runs applications, scripting languages, compilers, etc., from a dedicated directory.
+
+The main usage is to run software in a specific version, or to provide a given environment. See **EXAMPLES** below.
+
+There are some advantages over so called 'virtual environments' and the like. Packages are immutable, once installed they never change, thereby increasing the chances that an old program/script will also run in a few years. The packages also use a standardized call procedure, independent of personal (un-)settings, thus an existing pipeline may be shared between different users.
+
+The whole 'magic' behind **prun** is, that it transparently sets the PATH variable and possibly LD_LIBRARY_PATH for the actual call without spoiling the default environment.
+
+EXAMPLES
+========
+
+
+**Run R-Studio with a brand new R version**
+
+: prun R-4.1.0-0 rstudio
+
+**Use an ancient python to run an unmaintained script**
+
+: prun python-2.7.13-2 /project/cruft/bin/old_script.py
+
+**Run nvidia nvcc from cuda-11.3 and list supported architectures**
+
+: prun cuda-11.3 nvcc --list-gpu-code
+
+**Start a plain shell with gcc-10.2 in the PATH**
+
+:  prun gcc-10.2.0-0 bash --norc
+
+**Or just show the manual page for gcc-10.2**
+
+:  prun gcc-10.2.0-0 man gcc
+
+**Create an own alias for a scripting language**
+
+: alias myperl='prun perl-5.18.2-0 perl'
+
+**Use prun in a script shebang**
+
+: `#! /usr/bin/prun perl-5.18.2-0 perl`
+
+**Alternatively using source**
+
+:  An alternative way to set a distinct environment is to source the profile from /pkg/FooBar-12.3.
+But beware, such a source command should **never** make it into the **\~/.bashrc** - in the worst case it may inhibit your login!
+(N.b. the alias method mentioned above is safe)
+
+\ 
+: source /pkg/gcc-10.2.0-0/profile
+
+
+FILES
+=====
+
+*/package/FOO* or */pkg/BAR*
+
+:   Mountpoint (top directory) for selected package.
+
+*/package/FOO/profile* or */pkg/BAR/profile*
+
+:   Contains settings for PATH, libraries, and possibly other stuff.
+
+*/usr/local/package/lib/\**
+
+:   Primary wrappers for individual packages.
+
+*/usr/local/package/admin/config*
+
+:   Definition of binaries provided and optional shortcuts.
+
+
+BUGS
+====
+
+See GitHub Issues: <https://github.molgen.mpg.de/mariux64/mxtools>
+
+SEE ALSO
+========
+
+**ptype(1)**, **pman(1)**, **bash(1)**, **ld.so(8)**
+
+

prun/ptype.md

@@ -0,0 +1,42 @@
+% PTYPE(1) | Mariux Tools Documentation
+
+NAME
+====
+
+**ptype** - small **type** like tool for Mariux packages.
+
+SYNOPSIS
+========
+
+| **ptype command**
+
+DESCRIPTION
+===========
+
+Similar to **type** or **which**. **ptype** gives information about a package binary. **type** would only tell something about the package wrapper, and not about the package where the real program is. 
+
+```
+
+  #> type snakemake
+  snakemake is /usr/local/package/bin/snakemake
+
+  #> ptype snakemake
+  snakemake is /pkg/python-3.8.9-1/bin/snakemake  ...
+               ... (/usr/local/package/lib/python.profile)
+
+
+```
+
+BUGS
+====
+
+**ptype** only handles true wrapper scripts from /usr/local/package/bin, not the aliases. I.e. **ptype R** works, **ptype R4** not.
+
+See GitHub Issues: <https://github.molgen.mpg.de/mariux64/mxtools>
+
+SEE ALSO
+========
+
+**prun(1)**, **pman(1)**
+
+