1 README

uqjau: framework of mostly bash and some perl: scripts, script
functions, and script m4 macros for a range of simple purposes,
divided into "packages" (directories) by category.

It's a personal project; I'm the primary user.  uqjau is a
"grab bag" of tools created over many years, that I install either below
~ or /usr/local on UNIX and cygwin hosts.  

Been shell script writing since 1988; using GNU/Linux since 1996;
still have much to learn.  Constructive review of this code
appreciated. I tried to follow good practices and believe there
are some interesting shell scripting code idioms.


There are almost 200 script or script function files, here are my
current favorites:

  jobmon:
    Wrapper to run and log (STDOUT/STDERR/exit code/duration)
    of another script.  Useful for cron jobs. Logs files self-purged.

  fileutils-misc.shinc:
    bash file related functions for interactive or script use.
    sf(): find files in dirs given, sort by time, default to CWD
    _isonlydirs: return 0 if a tree is nothing but empty subdirs

  bash_common.shinc:
    script initialization, functions, and signal handlers
    to be sourced by bash scripts

  _bg:
    Run simple command in background in separate
    process session.  Will not be seen by your shell as a job.  Log
    STDOUT and STDERR to file. Simple command => exactly 1 command
    and it's args.  Useful when 'at and batch' are not available.

  backupall:
    tar backup of local filesystems, rewind and read each
    tape file. A log is created.  Remote tape drive supported.

  key2agent:
    Loads private ssh key specified to your ssh agent,
    supplying passphrase taken from encrypted file, starting an ssh
    agent if needed.  Uses keychain which gracefully handles case
    where key already loaded.

Design:

- Directory layout and tool configuration was influenced by
  'slashpackage': http://cr.yp.to/slashpackage.html. It has a
  directory named  'commands' that you may place in your
  PATH; containing only symbolic links to scripts.

- No requirement for record on file system or in env vars of
  where install tree is. Scripts figure this out. Does not
  depend on a fixed name for top dir in install tree.

- The goal was to write the scripts so that the 'commands'
  dir does not have to be in the PATH - scripts that are the
  exception, are not located in the uqjau tree, but depend on
  files in it.  Scripts w/in the uqjau tree as a rule should not
  assume that the 'commands' dir is in the PATH.

- After a script determines path to root of the uqjau
  install dir, it may source supporting (dependency) files in
  the uqjau tree.

- Scripts should not depend on pre-existing exported env vars, so cron
  jobs that run scripts should work w/o wrapper scripts.

- Scripts may only be invoked by: their basename ( assuming
  the 'commands' dir is in the PATH ); by the fully qualified
  pathname to the 'commands' or 'scommands' dir; or by
  ./COMMANDBASENAME - only if current working dir is the
  'commands' dir.  This limitation in the last case is due to
  the logic used in most scripts that try to determine the
  install dir for uqjau.

- As a rule bash scripts use 'set -eu', so any failed command
  or undefined env variable aborts the script.  Exit codes
  from these scripts and script functions are generally 
  meaningful; ie 0 => success.

    TBD: 'set -e' usage in my code needs to be reviewed in light of
 
      http://lists.gnu.org/archive/html/bug-bash/2012-12/msg00094.html
      http://lists.gnu.org/archive/html/bug-bash/2012-12/msg00102.html

- As a rule 1st line of scripts is:

    #!/usr/bin/env bash

  So the interpreter (in this case bash), may be installed
  anywhere, as long as it is in the PATH.  Also makes testing
  new versions of bash (for ex) easier.