Integration Guide

Getting Started

STDLIB itself is distributed as a versioned tar archive that can be unpacked to the desired target location.

A consuming project need only source the distributed stdlib.sh script to begin using the project.

Safely Integrating Trap Signals

Each time Bash registers a trap signal handler, any existing handler is overwritten.

Given this constraint, when integrating STDLIB, take care not to overwrite its trap signal handling by directly registering your own handlers with the trap builtin.

Instead, it’s recommended to extend STDLIB’s trap handling for ERROR and EXIT by using the provided registration functions:

stdlib.trap.handler.err.fn.register
stdlib.trap.handler.exit.fn.register

This allows STDLIB to preserve its own trap handling, while giving consuming projects the ability to safely run one or more custom signal trap handlers.

Embedding STDLIB in a Project

Embedding stdlib in an existing project may be the easiest method to integrate it quickly. This is best done in a folder separate and parallel from the source code.

repository_root/
    src/
        source_code_file_1.bash
        source_code_file_2.bash
    stdlib/
        collect_coverage
        stdlib.sh
        stdlib_testing.sh
        t
    testing/
        t

Installing STDLIB Centrally on a System

You could also opt to globally install STDLIB so it can be consumed by multiple scripts running on a host machine from a central location.

Typically, this would be done in a /usr/local/lib/stdlib or similarly named folder.

Enabling Testing

External Dependencies

Depending on how you leverage STDLIB for testing, you’ll need to install one or more external tools.

bash_unit

This project leverages bash_unit under the hood as the test framework.

Given this constraint, the first step is to install bash_unit on your system, and ensure it’s available in PATH.

It is definitely possible to use other test frameworks instead, but for simplicity right now only bash_unit is officially supported.

kcov

If you wish to measure code coverage, you’ll need to also install kcov, and ensure this too is available in PATH.

Custom ‘t’ Script

The ‘t’ script is a callable that is used to invoke test suites.

To adapt STDLIB to your codebase, you’ll need to create a small wrapper script that loads dependencies or sets environment variables in order to establish a “testing context” within which the test suites will run.

This project has an example customized t script that:

exports a custom _t_runner_custom_execution_context function to load all the required libraries
calls the stdlib t script to actually run the test suites

Presumably your own custom ‘t’ script would perform these same tasks.

Mocking System

The mocking system records calls in files created by mktemp to simplify the task of mocking dependencies across different processes.

If you wish to compartmentalize your system’s /tmp folder, containerization is the recommended approach. This project’s own development leverages this approach in an attempt to ‘eat our own dog food’.