blib - a bash library

blib is a lightweight general purpose library for bash.

It aims to provide robust implementations for commonly encountered issues whilst leaving the bash syntax as it is.

Functionality

blib currently provides functionality in the following areas:

• logging
• mutexes
• code documentation
• config files
• OS identification
• data typing
• terminal colors
• traps
• module management
• error reporting & handling
• privilege elevation
• inter-process communication
• Qubes OS: RPC, file attaching, ...

The various topics are grouped into dedicated modules which can be imported into the global bash namespace at will.

A complete overview of the available list of modules and functions can be obtained from the Documentation.

Portability

blib is currently only tested on Linux systems. Your mileage on other OSes (e.g. Unixes, BSD, Windows, ...) may vary. You can use the functionality tests to see what works as expected.

Table of contents

• Installation
  • Functionality Tests
• Usage
  • Command-line
  • Library
• Documentation
• Uninstall
• Copyright

Installation

Check out a copy of the blib repository and then run the provided installer script, e.g.

git clone https://github.com/3hhh/blib.git
cd blib
sudo ./installer install

The default installation goes to /usr/lib, but you can choose a different prefix as installation parameter.

If you would like to generate the offline html, pdf and manpage documentation as part of the installation, please install pandoc first. pandoc is available from the repositories of many operating systems. You may however also omit this step and re-run the documentation generation with blib gendoc at any later time.

blib requires bash version 4.2 or higher.

Functionality Tests

After the installation it is recommended to make sure that all blib modules behave as expected on your system by running the unit tests shipped with blib:

blib test

This requires bats to be installed beforehand.

Usage

blib is meant to be used as a bash library, but provides a few features on the command-line as well.

Command-line

Run blib without any parameters to display its command-line help.

Library

In order to import e.g. the functions of the str module to your bash namespace, simply execute the following at the top of your script:

source blib
b_checkVersion 1 2 || { >&2 echo "This script depends on blib (https://github.com/3hhh/blib) version 1.2 or higher. Please install a supported version." ; exit 1 ; }

b_import str

Check out the module implementations or the qcrypt code for real-life examples on how to use the library.

Documentation

The blib code reference is available in many formats:

1. Command-line: blib list and blib info [module]
2. Online: (possibly outdated)

• Code Reference (html)
• Code Reference (pdf)

3. Manpage: man blib (requires pandoc during installation)
4. Offline: as html and pdf in /usr/lib/blib/doc (requires pandoc during installation)

Uninstall

Use the installer script as follows:

cp /usr/lib/blib/installer /tmp/
cd /tmp/
sudo ./installer uninstall
rm /tmp/installer

If you didn't install to /usr/lib, you'll have to provide the installer script the location from which to uninstall.

Copyright

© 2021 David Hobach

blib is released under the LGPLv3 license; see LICENSE for details.