Shellib

Simple Bash scripting library.

Easy-to-use yet powerful library set of functions for Bash. The goal is not to replace traditional idioms but to provide a toolbox to boost your scripting productivity.

The project is under active development.

Table of Contents

• Features
  • Functions
  • Constants
• Installation and Configuration
  • Deb Package
  • Git Submodule
• Usage
• Contributing
  • Testing
    • Test at Docker Container
  • Packaging
• To-Do list
• Roadmap
• Credits and Acknowledgments
• Copyright and Licensing
• Changelog and News
• Notes and References
  • Dependencies
  • Recommendations
  • Further Reading

Features

Functions

• get_version: Output Shellib version to stdout
• is_root: Return boolean status, if the current user is a root, or not (idiomatic [ "$EUID" -ne 0 ] is not easily testable as $EUID is read-only)
• event 'message' ['level' ['symbol' ['command']]]: Send "command symbol message" to stderr, default level = $level_info, default symbol depends on the level ($level_err ✗, $level_sec ☠, $level_warn ⚠, $level_notice 🛈, default $level_info ✓), and default command is $0
  • err, sec, warn, notice, and info functions - func 'message' ['symbol' ['command']]: Wrappers for each level, default symbol depends on the level, and default command is $0
• pkgs install 'man:pkg1' ['man:pkg2' [...]]: Install packages from the package list formatted as man:pkg, where man is a supported package manager, and pkg is a package to install, supported package managers:
  • apt for deb packages by apt
  • pip for Python packages by pip3
  • npm for npm packages by npm
  • snap for Snap packages
  • curl2bash for package specification command=URL - if a command exists, then the package is marked as installed. If doesn't, it is installed source by curl -s "$URL" | bash
• apt_add 'repository specification' 'repository_key_URL': Add apt repository by apt, equivalent to curl -fsSL 'repository_key_URL' | apt-key add - && apt-add-repository 'repository specification' && apt-get update

Constants

• Status codes: $status_ok 0, $status_err 1
• Symbols: $symbol_err ✗, $symbol_sec ☠, $symbol_warn ⚠, $symbol_notice 🛈, $symbol_ok ✓, $symbol_tip 💡, $symbol_todo ☐, $symbol_doing …, $symbol_done 🗹, $symbol_failed ☒
• Event levels: $level_err < $level_sec < $level_warn < $level_notice < $level_info

Installation and Configuration

Deb Package

shellib_latest_deb_url=$(curl https://gitlab.com/api/v4/projects/26143455/releases | jq --raw-output '.[0].assets.links | .[0].direct_asset_url') # Get the latest deb package URL
shellib_downloaded_deb_file=$(mktemp --suffix='deb') # Set the package download destination
curl "$shellib_latest_deb_url" -o "$shellib_downloaded_deb_file" # Download the latest deb package
sudo dpkg -i "$shellib_downloaded_deb_file" # Install the package
rm "$shellib_downloaded_deb_file" # Clean up after yourself

Git Submodule

Install:

cd your-project/path/to/submodule # Get to the directory
git submodule add https://github.com/xebis/shellib.git shellib # Add Shellib as a git submodule
# Previous command:
#   - updates (or creates, when doesn't exist) .gitmodules
#   - stages .gitmodules and the new submodule

# Commit, push, ...

Update:

git submodule update path/to/submodule --remote --merge # Update the submodule
# OR
git submodule update --remote --merge # Updates all repository submodules
# Commit, push, ...

Usage

Recommended, but not necessary:

#!/usr/bin/env bash

# Use Bash Strict Mode, see http://redsymbol.net/articles/unofficial-bash-strict-mode/
set -euo pipefail
IFS=$'\n\t'

# Set safe basic locale
LANG=C

Source the library:

. /usr/lib/shellib.sh # When installed as a deb package
# OR
. path/to/submodule/shellib/shellib.sh # When added as a git submodule

Use library functions:

out 'Hello world!' '😀'
# Result is similar to:
# your/script 😀 Hello world!

Contributing

Please read CONTRIBUTING for details on our code of conduct, and the process for submitting merge requests to us.

Testing

• Git hooks check a lot of things for you, including running automated tests scripts/test full

• Stuff inherited from repository-template should be tested there.

• Make sure all non-inherited scripts/* work as expected, testing checklist:

• shellib.sh and src/* - covered by unit tests tests/*.sh

  • shellib.sh
  • src/events.sh
  • src/packages.sh
  • src/process.sh
  • src/system.sh

• scripts/* scripts

  • scripts/build - covered by unit tests
  • scripts/pack
  • scripts/set-ver - covered by unit tests

• GitLab CI

  • Built DEB package, see Installation And Configuration

Test at Docker Container

To test your changes in a different environment, you might try to run a Docker container and test it from there.

Run a disposal Docker container:

• sudo docker run -it --rm -v "$(pwd)":/shellib alpine:latest
• sudo docker run -it --rm -v "$(pwd)":/shellib --entrypoint bash node:latest

In the container:

cd shellib
# Set variables GL_TOKEN and GH_TOKEN when needed
# Put here commands from .gitlab-ci.yml job:before_script and job:script
# For example job test-full:
apk -U upgrade
apk add bats
bats tests
# Result is similar to:
# 1..1
# ok 1 dummy test

Packaging

Build, and pack:

ver_next='1.5.25-alpha'
scripts/set-ver "$ver_next" # Set version at source codes
# ... Do not forget to commit the change
scripts/build # Create build at ./build
scripts/pack "$ver_next" # Create package at ./build

To-Do list

• Fix workaround for pre-commit jumanjihouse/pre-commit-hooks hook script-must-have-extension - *.bats shouldn't be excluded
• Fix workaround for pre-commit local hook shellcheck - shellcheck has duplicated parameters from .shellcheckrc, because these are not taken into account

Roadmap

• Find a satisfactory way how to manage (list, install, update) dependencies across various distributions and package managers
• Add pre-commit meta hooks
• Add jumanjihouse/pre-commit-hooks hook protect-first-parent
• Speed up CI/CD by preparing a set of Docker images with pre-installed dependencies for each CI/CD stage, or by cache for apk, pip, and npm

Credits and Acknowledgments

• Martin Bružina - Author

Copyright and Licensing

• MIT License
• Copyright © 2021 Martin Bružina

Changelog and News

• Changelog

Notes and References

Dependencies

• GitHub - xebis/repository-template: Well-manageable and well-maintainable repository template. - a lot of stuff is inherited from there, including git hooks, GitLab CI, scripts, or Visual Studio Code suggested extensions
• GitHub - mvdan/sh: A shell parser, formatter, and interpreter with bash support; includes shfmt
• GitHub - koalaman/shellcheck: ShellCheck, a static analysis tool for shell scripts
• GitHub - bats-core/bats-core: Bash Automated Testing System
  • GitHub - bats-core/bats-support: Supporting library for Bats test helpers
  • GitHub - bats-core/bats-assert: Common assertions for Bats
  • GitHub - bats-core/bats-file: Common filesystem assertions for Bats

Recommendations

• aaron maxwell: Use Bash Strict Mode (Unless You Love Debugging)

Further Reading

• GNU Bash: Bash Reference Manual
• The Debian GNU/Linux FAQ: Chapter 7. Basics of the Debian package management system