Auxilium Information and Downloads

Auxilium Introduction

This is the auxilium information and download site.

Auxilium is the latin word for support. The "auxilium" package is an open-source project which contains a collection of bash shell executable and sourceable scripts which support, and make easier, many common Unix/Linux user tasks. All auxilium utilities are written in *bash", the standard Linux interpretive shell language. This facilitates portability (between bash platforms) and ease of installation. Auxilium has no runtime prerequisites other than bash version 4.2 or higher.

The core auxilium utilities include:

• auxenv. Setup, manipulation, and optimization of path-like environment variables such as PATH, MANPATH, and LD_LIBRARY_PATH.

• auxwhere. Find files by filename search through path-like environment variable directories.

• auxsource. An extended version of the bash built-in source command.

• auxalias. Creates static or dynamic aliases for all auxilium sourceable scripts.

• auxchecktap. Scans and checks TAP format unit test result logs, producing a summarized TAP test results log.

• auxguid. Generates a pseudo random 128-bit (32 hex character) GUID/UUID.

• auxilium. Displays version info for auxilium and all of its compoents.

Auxilium Released Downloads

Auxilium Prerequisites

• Requires bash version 4.2 or higher.

Documentation

For convenience the latest version of the user guide is also available online in both HTML and PDF formats:

• Auxilium User Guide (html)
• Auxilium User Guide (pdf)

Version specific auxilium manuals are included in the version specific runtime distribution tar file and also get installed in the <PREFIX>/share/html/auxilium directory. The auxilium user guide is available in that directory in both HTML format (auxilium-user-guide.html) and pdf format (auxilium-user-guide.pdf).

Auxilium Runtime Install

Runtime installation is relatively easy. As an example, below is a sample installation of auxilium 1.0.0, which is pretty much the same for other auxilium versions if you simply adjust the release version number.

1. Download the runtime distribution. There are at least two ways of doing this:

   1. Primary download method: Right-click on the "1.0.0" link on this page at https://ericmotleybytes.github.io/auxilium/ and select "save link as...".

   2. Alternate download method: Use the "wget" program to get the tar file.

      $ wget https://github.com/ericmotleybytes/auxilium\
      /releases/download/1.0.0\
      /auxilium-run-1.0.0.tar.gz

      This will create the file "auxilium-run-1.0.0.tar.gz".

2. Unpack the tar file.

   $ tar -xzf auxilium-run-1.0.0.tar.gz

   This will create a sub-directory called "auxilium-run-1.0.0" which contains additional files and directories.

3. Set the default directory to the "auxilium-run-1.0.0" sub-directory.

   $ cd auxilium-run-1.0.0

4. Use make to install auxilium under your desired directory prefix.

   1. Personal install: To install auxilium under a personal directory, for example under the ~/local directory, issue the following command:

      $ make install PREFIX=~/local

      This installs executable scripts in ~/local/bin, man pages in ~/local/man/man1, html files in ~/local/share/html, and so forth.

   2. System install: To install auxilium under a shared system-wide directory, for example under the /usr/local directory, issue the following command:

      $ sudo make install PREFIX=/usr/local

5. Optionally, although this is highly recommended, setup automatic auxilium alias definitions in the appropriate login script.

   1. Personal setup: Edit your ~/.bashrc file and add the line:

      source ~/local/bin/auxalias

   2. System setup: Edit the /etc/bash/bashrc file and add the line:

      source /usr/local/bin/auxalias

Congratulations! You have now installed auxilium!

If your MANPATH is defined resonably you should be able to see an overview of auxilium by typing:

$ man auxilium

Auxilium Runtime Uninstall

You can also easily uninstall auxilium. As an example, below is a sample uninstall of auxilium 1.0.0, which is pretty much the same for other auxilium versions if you simply adjust the release version number.

1. Set the default directory to the "auxilium-run-1.0.0" sub-directory.

   $ cd auxilium-run-1.0.0

2. Use make to uninstall auxilium under your desired directory prefix.

   1. Personal uninstall: To uninstall auxilium from under a personal directory where it was previously installed, for example under the ~/local directory, issue the following command:

      $ make install PREFIX=~/local

      This remove only auxilium installed files.

   2. System install: To uninstall auxilium under a shared system-wide directory where it was previously installed, for example under the /usr/local directory, issue the following command:

      $ sudo make uninstall PREFIX=/usr/local

3. Optionally, if you edited a login script during installation, your might want to delete or comment out the line you added.

   1. Personal setup: Edit your ~/.bashrc file and remove or comment the line:

      source ~/local/bin/auxalias

      If commented, the line will then look like:

      #source ~/local/bin/auxalias

   2. System setup: Edit the /etc/bash/bashrc file and remove or comment the line:

      source /usr/local/bin/auxalias

      If commented, the line will then look like:

      #source /usr/local/bin/auxalias

4. Set the default directory to the original download directory and delete the tar distribution file and the unpacked files.

   $ cd <download-directory>
   $ rm auxilium-run-1.0.0.tar.gz
   $ rm -rf auxilium-run-1.0.0

You have now uninstalled auxilium.

Usage Examples

auxenv examples

Here are some examples of using auxenv.

• Displaying a pathlike environment variable:

  $ export DEMOPATH="/dir1:/dir2:/dir3"
  $ auxenv show DEMOPATH
  DEMOPATH is set to:
  /dir1:/dir2:/dir3
  Item breakdown:
    1=/dir1
    2=/dir2
    3=/dir3
  $ auxenv dump DEMOPATH
  /dir1
  /dir2
  /dir3

• Prepending a directory:

  $ export DEMOPATH="/dir1:/dir2:/dir3"
  $ auxenv prepend DEMOPATH /dir0
  $ echo "$DEMOPATH"
  /dir0:/dir1:/dir2:/dir3

• Inserting a directory:

  $ export DEMOPATH="/dir1:/dir2:/dir3"
  $ auxenv insert DEMOPATH "/dir1a" before "/dir2"
  $ echo "$DEMOPATH"
  /dir1:/dir1a:/dir2:/dir3

• Erasing a directory by name:

  $ export DEMOPATH="/dir1:/dir2:/dir3"
  $ auxenv erase DEMOPATH "/dir2"
  $ echo "$DEMOPATH"
  /dir1:/dir3

• Erasing a directory by position:

  $ export DEMOPATH="/dir1:/dir2:/dir3"
  $ auxenv erase DEMOPATH @2
  $ echo "$DEMOPATH"
  /dir1:/dir3

• Working with alternate separators:

  $ export DEMOPATH="red|green|blue"
  $ auxenv --ifs="|" show DEMOPATH
  DEMOPATH is set to:
  red|green|blue
  Item breakdown:
    1=red
    2=green
    3=blue

auxsource examples

Here are some examples of using auxsource.

• Sourcing a file somewhere in a PATH directory:

  $ auxsource myfile

• Sourcing a file somewhere in a PATH directory and passing some parameters:

  $ auxsource myfile say "hello world"

• Sourcing a file specified by absolute location and passing parameters:

  $ auxsource /home/alice/mything.bash "more" "parameters"

• Sourcing a file somewhere in a MYPATH directory:

  $ export MYPATH="/home/alice:/home/bob"
  $ export AUXSOURCE_OPTIONS="--env=MYPATH"
  $ auxsource myfile "some" "more parameters"

auxalias examples

Here are some examples of using auxalias.

• Setting up static auxilium aliases to installation in /usr/local:

  $ source /usr/local/bin/auxalias
  $ alias auxenv
  alias auxenv='source /usr/local/bin/auxenv'

• Setting up dynamic auxilium aliases which use PATH:

  $ source /usr/local/bin/auxalias
  $ alias auxenv
  alias auxenv='eval source $(auxwhere auxenv)'

auxwhere examples

Here are some examples of using auxwhere.

• Finding the first instance of a file somewhere in a PATH directory:

  $ auxwhere myfile
  /some/directory/myfile

• Finding all instances of a file somewhere in a PATH directory:

  $ auxwhere --all myfile
  /some/directory/myfile
  /some/other/directory/myfile
  /another/directory/myfile

• Finding the first instance of a file somewhere in a LD_LIBRARY_PATH directory.

  $ auxwhere --env=LD_LIBRARY_PATH libproxy.so.1
  /usr/lib64/libproxy.so.1

• Finding a file and seeing how the file was found using two path-like environment variables.

  $ auxwhere --all --env=PRIMARYPATH --env=SECONDARYPATH myfile.bash
  /some/directory/myfile.bash    (Found via PRIMARYPATH)
  /another/directory/myfile.bash     (Found via SECONDARYPATH)

• Finding a file searching multiple file types and a sub-directory.

  $ auxwhere --env=MANPATH --subdir=.man --type=.1 --type=.1.gz awk
  /usr/share/man/man1/awk.1.gz

auxchecktap examples

Here are some examples of using auxchecktap.

• Scanning a unit test results log file:

  $ auxchecktap example1.taplog
  1..3
  ok 1 [TAPFILE: '/home/tester/test/example1.taplog' 89 tests, 0 errors]
  ok 2 [TAPTOTAL: 1 file, 89 tests, 0 errors]
  ok 3 [TAPGRAND: 1 file, 89 tests, 0 errors]
  1..1
  ok 1 /home/tester/test/auxilium.taplog: 85 tests.
  $ echo "$?"
  0

• Scanning multiple unit test result log files:

  $ auxchecktap example*.taplog
  1..6
  ok 1 [TAPFILE: '/home/tester/test/example1.taplog' 89 tests, 0 errors]
  ok 2 [TAPFILE: '/home/tester/test/example2.taplog' 88 tests, 0 errors]
  ok 3 [TAPFILE: '/home/tester/test/example3.taplog' 40 tests, 0 errors]
  ok 4 [TAPFILE: '/home/tester/test/example4.taplog' 20 tests, 0 errors]
  ok 5 [TAPTOTAL: 4 files, 237 tests, 0 errors]
  ok 6 [TAPGRAND: 4 files, 237 tests, 0 errors]
  $ echo "$?"
  0

• Scanning a unit test log file with a failed unit test report in it:

  $ auxchecktap another.taplog
  1..3
  not ok 1 [TAPFILE: '/home/tester/test/another.taplog' 3 tests, 1 error]
  # Found 1 failed test.
  not ok 2 [TAPTOTAL: 1 file, 3 tests, 1 error]
  not ok 3 [TAPGRAND: 1 file, 3 tests, 1 error]
  $ echo "$?"
  1

auxguid examples

Here are some examples of using auxguid.

• Generate a GUID/UUID:

  $ auxguid
  2c7459630bbf26bc01ee5a33259a215a

• Generate a lowercase GUID/UUID:

  $ auxguid --lower
  5bb659630c1f28006a2d5a57259a215a

• Generate an uppercase GUID/UUID:

  $ auxguid --upper
  39EB59630C67184D7E0E5B1E259A215A

Platforms

Auxilium programs are all written in Bash, the standard Linux shell language. Bash is an interpretive language, so as long as your platform has a relatively new version of Bash installed, it should be able to run the runtime Auxilium Bash scripts. There is no need of different runtime versions of Auxilium for different hardware platforms because there are no hard-compiled programs.

That being said, to date Auxilium has only been tested on Linux platforms. The author, however, would be very interested in user experience reports.

Authors

Eric Alan Christiansen
eric@motleybytes.com
https://www.linkedin.com/in/ericchristiansen/

Legal

Copyright © 2017 Eric Alan Christiansen.

This program comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to use and/or redistribute it under the conditions of the GNU General Public License v3.0.

See https://www.gnu.org/licenses/gpl-3.0.en.html

See Also

• https://github.com/ericmotleybytes/auxilium : The master auxilium GitHub repository. You can also report bugs, describe issues, and request enhancements here.

• https://testanything.org/ : A description of TAP, the unit testing Test Anything Protocol.

Updated 2017-07-15