libbash: How to create and install your own libraries

# How to create and install your own libraries

## General

libbash library is basicly just script. Script that define functions that become available when you source it.

## Writing libraries

A bash shared library that can be loaded using `ldbash` must answer 3 requirments:

1. It must contain a line that begins with `EXPORT=`. That line will contain (after the `'='` ) a list of fuctions that the library exports. I.e. all the function that will be usable after loading that library will be listed in that line.
2. It must contain a line that begins with `REQUIRE=`. That line will contain (after the `'='` ) a list of bash functions that are required for our library. I.e. every bash function that is in use in our bash library, and should be defined by another library, must be listed there.
3. The library must be listed (For more information, see `ldbashconfig` man page ).

### Basic guidelines for writing library of your own:

Be aware, that your library will be actually sourced. So, basicly, It should contain (i.e define) only functions.

1. Try to declare all variables intended for internal use as local.
2. Global variables and functions that are intended for internal use (i.e are not defined in `EXPORT=` ) shoud begin with: __<library_name>_ For example, internal function myfoosort of hashstash library should be named as

       __hashstash_myfoosort

   This helps to avoid conflicts in global namespace when using libraries that come from different vendors.
3. Do not overload defined functions. I.e. do not name one of your functions the same as a bash built-in command, or the same as a function that is defined by some other library or package.
4. Make sure you do not create mutual dependancy between bash libraries.

## Installing libraries

libbash is splitted in two utilites:

- `ldbash:` library loader
- `ldbashconfig:` checks out available libraries, resolves cross-library dependencies and builds cache file.

As number of libraries grows, it may take considerable amount of time to scan them all and resolve dependencies. That is why this process is done by separate utility - `ldbashconfig`. Afterwards, at runtime, `ldbash` reads cache file and determinies which libraries it needs to load in order to satisfy dependencies for requested library.

Install steps:

- name your library `<something>``.sh`
- put it in `$LIBBASH_PREFIX/lib/bash` (default is `/usr/lib/bash`).
- run `ldbashconfig`