From e0336eb8139246c42253f40b3d5e43d2020ed262 Mon Sep 17 00:00:00 2001 From: thomas Date: Wed, 11 Aug 2021 17:11:18 +0200 Subject: [PATCH] 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)** + +