installer_tools.md

Documentation for the functions in installer_tools.sh. A general overview is given in the project documentation.

Function documentation

If the pipes are not documented, the default is:

• stdin: piped input ignored
• stdout: empty

get_package_manager()

Tries to detect the installed package manager.

Pipes	stdout	in case of success, the package manager. Can be apt or yum
Status	0	package manager written on stdout
	1	no package manager found

get_executable_status()

Get a detailed executable status about a path.

Param.	$1	executable name
	[$2]	if it's set to 1, the executable path is written on stdout if status is 0
Pipes	stdout
Status	0	$1 is executable
	1	$1 is not executable
	2	$1 not found in $PATH
	3	found $1 in a $PATH folder but was unable to determine the actual path (usually broken symlinks)
	4	incoherence: everything seems fine (found $1 in a path folder, it's executable) but which didn't find it
	5	$1 is empty

handle_dependency()

If the command $1 is not found or not executable, this function tries to install it, respectively make it executable. Both operations may be customized through callback functions.

To start, get_executable_status() is called on $1. It returns:

• 1: $1 is not executable
• 2: $1 is not installed
• above 2: non-recoverable error, abort
• 0: $1 is installed & executable, there's nothing to do

To customize the handling callback functions may be defined:

• handle_dependency_installation(): receives the command and the package manager (stdout of get_package_manager()) as parameters
• handle_non_executable_dependency(): called with the path as parameter

The default handling is simply a chmod +x if it's not executable; if it's not installed, the function looks for a package list depending on to the detected package manager: $apt_packages for apt, $yum_packages for yum, etc. Inside this list, it looks for a element with the name of the command. If no package list or no corresponding entry is found, the function tries to use the command name ($1) itself.

Examples:

# on a apt based system
declare -A apt_packages
apt_packages[my_command]="my_command_package"
# other command package relationship definitions, also for other package managers ...
handle_dependency "my_command"

Calls apt-get install "my_command_package" if my_command is not found.

Verbose mode / message customization

The variable placeholders %command, %path and %package are replaced with the corresponding values. %path and %package are obtained via a $temp_var, depending on the status:

Status	$temp_var	Template
1	%path	%command (%path) already installed
2	%path	%command (%path) was not executable, applied chmod +x successfully
3	%package	%command installed successfully (package %package)
4	%path	Error: %command (%path) is not executable and chmod +x failed
5	%package	Error: %command installation failed (package %package)
6		Error: %command not installed and no package manager found
7		Error: %command is not installed and no package found to install it
8	%path	Error: %command exists in $PATH at %path but it doesn't resolve to an existing filesystem location(broken symlink?)
9		Error: %command exists but there's a incoherence with which (it can't find it)
10		Error: command empty

The messages can be customized by setting up an array variable where the indizes are the states and the values the corresponding templates (i.e. "already installed" message template is at index 0, etc.). The name of the array variable - and not the variable itself - has to be provided as 2nd call parameter. It's perfectly valid to customize a subset of states/templates, the function falls back to the default templates where it can't find a customization. In the next example, the "installed successfully" message template is overwritten:

# on a apt based system
declare -A apt_packages && apt_packages[sshd]="openssh-server"
msg_defs[3]="%package installed for %cmd"
handle_dependency "sshd" "msg_defs"

prints openssh-server installed for sshd if sshd misses. The message templates don't support text flow control sequences like \t or \n. In fact, the message is a string input to a printf; these sequences are hence escaped and appear in the final message. The default output pattern is "just the message" (no newline): %s. To add f.ex. a newline at the end of each printed message, set $3 to %s\n.

Param.	$1	command
	[$2]	if $2 is omitted or empty, nothing is written on stdout if $2 is set to a non-empty value, the system tries to find a array variable with that name. If such a variable is defined it tries to load the element which is at the index corresponding to the return status. If either the array or the array element is not defined, it uses the default messages given above
		[$3]	printf pattern for messages, default to %s ("just the message") if omitted. Look at the explanation above.
Pipes	stdout	the message if $2 is not omitted or empty
Status	1	$1 already installed
	2	successfully applied chmod +x to $1
	3	$1 installed successfully
	4	$1 not executable and chmod +x attempt failed
	5	$1 installation failed
	6	$1 not installed and no package manager found
	7	found $1 in a $PATH folder but was unable to determine the actual path (usually broken symlinks)
	8	incoherence: everything seems fine (found $1 in a path folder, it's executable) but which didn't find it
	9	$1 is empty
	Globals		$apt_packages: associative array which defines the package(s) to install if the package manager is apt $yum_packages: associative array which defines the package(s) to install if the package manager is yum

handle_dependencies()

handle_dependency() wrapper to handle dependency list. Its return status is the amount of failed dependencies.

Param.	$1	list of dependencies separated with spaces, f.ex. *docker sshd mysql*
	[$2]	Stdout output control directly passed through to [handle_dependency()](#handle_dependency)
			[$3]
Status	*0* if all dependencies in $1 are installed and executable, the amount of failed dependencies otherwise. A dependency is considered failed if [handle_dependency()](#handle_dependency) returns a status above *3*

reset_package_lists()

Reset package manager cache.

Status

2 if the no package manager is found, the return status of the package manager operation otherwise