From e0336eb8139246c42253f40b3d5e43d2020ed262 Mon Sep 17 00:00:00 2001 From: thomas Date: Wed, 11 Aug 2021 17:11:18 +0200 Subject: [PATCH 1/5] prun: Add documentation in markdown format Manual pages can be generated with: pandoc --standalone --to man prun.md -o prun.man.1 --- prun/pman.md | 37 ++++++++++++++++++ prun/prun.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++ prun/ptype.md | 42 +++++++++++++++++++++ 3 files changed, 181 insertions(+) create mode 100644 prun/pman.md create mode 100644 prun/prun.md create mode 100644 prun/ptype.md diff --git a/prun/pman.md b/prun/pman.md new file mode 100644 index 0000000..8518d23 --- /dev/null +++ b/prun/pman.md @@ -0,0 +1,37 @@ +% PTYPE(1) | Mariux Tools Documentation + +NAME +==== + +**pman** - view manual pages installed in Mariux packages. + +SYNOPSIS +======== + +| **pman command** + +DESCRIPTION +=========== + +**ptype** 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: + +SEE ALSO +======== + +**prun(1)**, **ptype(1)**, **man(1)** + + diff --git a/prun/prun.md b/prun/prun.md new file mode 100644 index 0000000..ba36071 --- /dev/null +++ b/prun/prun.md @@ -0,0 +1,102 @@ +% 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: + +AUTHORS +======= + +D.Buczek, P.Marquardt, M.Tolzmann + +SEE ALSO +======== + +**ptype(1)**, **pman(1)**, **bash(1)**, **ld.so(8)** + + diff --git a/prun/ptype.md b/prun/ptype.md new file mode 100644 index 0000000..72c7d74 --- /dev/null +++ b/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: + +SEE ALSO +======== + +**prun(1)**, **pman(1)** + + From d841b64c7b2b7c3c2416406e17ca468063e08f59 Mon Sep 17 00:00:00 2001 From: Donald Buczek Date: Thu, 12 Aug 2021 10:39:06 +0200 Subject: [PATCH 2/5] Add build/install logic for prun manpages --- .gitignore | 1 + Makefile | 16 +++++++++++----- install.sh | 4 ++++ 3 files changed, 16 insertions(+), 5 deletions(-) diff --git a/.gitignore b/.gitignore index 2f683ef..41c83a2 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ setuid/setuid +prun/*.1 diff --git a/Makefile b/Makefile index 9810ebc..481b18e 100644 --- a/Makefile +++ b/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 $(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,7 @@ install: DESTDIR="$(DESTDIR)" \ ./install.sh -.PHONY: all install - +.PHONY: all install clean +%.1: %.md + pandoc --standalone --to man $< -o $@ diff --git a/install.sh b/install.sh index 4668108..385614b 100755 --- a/install.sh +++ b/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 From fad0b5454a6d4788d9133a348e7039197b22316b Mon Sep 17 00:00:00 2001 From: Donald Buczek Date: Thu, 12 Aug 2021 12:11:38 +0200 Subject: [PATCH 3/5] Makefile: Shut up "make clean" Use `-f` flag of `rm` to avoid error messages from `make clean` when the targets files don't exist. --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 481b18e..164c794 100644 --- a/Makefile +++ b/Makefile @@ -69,7 +69,7 @@ manpages += prun/prun.1 prun/pman.1 prun/ptype.1 all: $(manpages) clean: - @rm $(manpages) + @rm -f $(manpages) install: all @prefix="$(prefix)" usr_prefix="$(usr_prefix)" usrlocal_prefix="$(usrlocal_prefix)" \ From d7d563834ade87882828968acde738307ef06f5a Mon Sep 17 00:00:00 2001 From: Donald Buczek Date: Thu, 12 Aug 2021 12:14:04 +0200 Subject: [PATCH 4/5] Makefile: Avoid running "pandoc" as root --- Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/Makefile b/Makefile index 164c794..e984744 100644 --- a/Makefile +++ b/Makefile @@ -87,4 +87,5 @@ install: all .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 $@ From 52b24e5857ac9bb7cd14b4db2f7e830843e1a504 Mon Sep 17 00:00:00 2001 From: thomas Date: Mon, 16 Aug 2021 13:49:47 +0200 Subject: [PATCH 5/5] prun man pages: cleanup Remove authors from prun.md, reformat Remove copy-and-paste errors in pman.md --- prun/pman.md | 4 ++-- prun/prun.md | 8 +------- 2 files changed, 3 insertions(+), 9 deletions(-) diff --git a/prun/pman.md b/prun/pman.md index 8518d23..ae747a8 100644 --- a/prun/pman.md +++ b/prun/pman.md @@ -1,4 +1,4 @@ -% PTYPE(1) | Mariux Tools Documentation +% PMAN(1) | Mariux Tools Documentation NAME ==== @@ -13,7 +13,7 @@ SYNOPSIS DESCRIPTION =========== -**ptype** uses the PATH set in the package wrapper and tries to find a manual page in the package directory. +**pman** uses the PATH set in the package wrapper and tries to find a manual page in the package directory. EXAMPLES ======== diff --git a/prun/prun.md b/prun/prun.md index ba36071..b9cc124 100644 --- a/prun/prun.md +++ b/prun/prun.md @@ -17,8 +17,7 @@ Runs applications, scripting languages, compilers, etc., from a dedicated direct 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. +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. @@ -89,11 +88,6 @@ BUGS See GitHub Issues: -AUTHORS -======= - -D.Buczek, P.Marquardt, M.Tolzmann - SEE ALSO ========