SBO::Lib::Util(3)

NAME
SBO::Lib::Util - Utility functions for SBO::Lib and the sbotools

SYNOPSIS
  use SBO::Lib::Util qw/uniq/;

  # ('duplicate');
  my @uniq = uniq('duplicate', 'duplicate');

VARIABLES

  $anticipated_next
The anticipated Slackware version number to be supported by SBO, currently 15.1.

  $arch
The kernel architecture, accounting for "i?86" userlands reporting a "x86_64" kernel.

  ($color_default, $color_lesser, $color_notice, $color_warn)
These variables are ANSI colors. $color_notice is "cyan" for selected "sbotools" informative messages. $color_lesser is "bold" for warnings of lesser concern. $color_warn, "red bold", is for errors and warnings of greater concern. "sbotools" color display can be enabled by setting "COLOR" to "TRUE". $color_default is currently "reset" and is not configurable.

get_colors() reads "/etc/sbotools/sbotools.colors" for custom values.

  $conf_dir
$conf_dir is "/etc/sbotools" by default, or else the contents of an environment variable "SBOTOOLS_CONF_DIR".

  $conf_file
$conf_file is "/etc/sbotools/sbotools.conf" by default.

  %config
All values default to "FALSE", but when read_config() is run, they change according to the configuration. "SBO_HOME" is changed to "/usr/sbo" if still "FALSE".

The supported keys are: "NOCLEAN", "DISTCLEAN", "JOBS", "PKG_DIR", "SBO_HOME", "LOCAL_OVERRIDES", "SLACKWARE_VERSION", "REPO", "BUILD_IGNORE", "GPG_VERIFY", "RSYNC_DEFAULT", "STRICT_UPGRADES", "GIT_BRANCH", "CLASSIC", "CPAN_IGNORE", "ETC_PROFILE", "LOG_DIR", "NOWRAP", "COLOR", "SO_CHECK", "DIALOGRC" and "NONET".

  $download_time
The time spent downloading source files. Unless "CLASSIC" is "TRUE", it is displayed when all builds are complete.

  $hint_file
A file, "/etc/sbotools/sbotools.hints" by default, containing blacklisted scripts, optional script dependencies and automatic revese dependency rebuild requests.

  ($is_sbotest, $is_sbotool)
This shared variable indicate runs from "sbotest" and "sbotool", respectively.

  $sbotest_compatible
This shared variable indicates compatibility with the "sbotest" companion package.

  $total_build_time
A running total of the time it took to build and package each script in the queue. Unless "CLASSIC" is "TRUE", it is displayed when all builds are complete.

  $total_install_time
A running total of the time it took to install each script in the queue. Unless "CLASSIC" is "TRUE", it is displayed when all builds are complete.

  ($paused_time, $resume_time, $stop_time)
These variables are used to track any time spent stopped by keyboard interrupt. Times are adjusted in the reconcile_time() subroutine before reporting.

  @listings
An array with blacklisted scripts and requests for optional dependencies, ignoring test failures and automatic reverse dependency rebuilds read in from "/etc/sbotools/sbotools.hints".

  (@on_blacklist, @auto_reverse, %optional, @ignore_tests)
These exported variables are populated by read_hints() and used to determine hint status.

  $obs_file
This file contains a list of scripts that have been renamed and added to Slackware -current, or are known to be obsolete build dependencies. It is located at "/etc/sbotools/obsolete" by default.

  @obsolete
This array is based on the contents of $obs_file. Only obsolete_array() should interact with @obsolete directly; in other situations, make a copy.

  $perl_file
This file contains build timestamps for the introduction of major perl versions into Slackware. It is used by "Solibs.pm" during the "perl" package test. It is located at "/etc/sbotools/perl_vers" by default.

  $userland_32
get_arch() defines this variable when running in a 32-bit userland on a 64-bit kernel.

SUBROUTINES

  auto_reverse
  my $result = auto_reverse($sbo)

auto_reverse() checks whether automatic reverse dependency rebuilding for $sbo has been requested. Results will be the same for the "compat32" version of the script.

  build_cmp
  my $cmp = build_cmp($build1, $build2, $ver1, $ver2);

build_cmp() compares $build1 with $build2 while checking that $ver1 and $ver2 are different. If the build numbers are not the same and the version numbers are, upgrading for a script bump may be in order.

  check_multilib
  my $ml = check_multilib();

check_multilib() verifies "/etc/profile.d/32dev.sh" existence. The sbotools use this file to build 32-bit packages on x64 architecture.

Returns 1 if the file exists, and 0 otherwise.

  dangerous_directory
  my $dangerous = dangerous_directory($dirname);

dangerous_directory() takes a string and returns true if it is equal to "/", "/root", "/home" or a possible top-level directory under "/home".

  display_times
  display_times();

display_times() shows the time spent downloading, packaging and installing the scripts in the build queue. It takes no arguments and has no useful return value.

  error_code
  error_code($message, $code);

error_code() takes a message and an error code. The message is displayed wrapped at 72 characters and the script exits with the specified error code. There is no useful return value.

dialog(1) displays the message when running "sbotool".

For _ERR_USAGE and _ERR_SCRIPT, use usage_error() and script_error(), respectively.

  get_arch
  my $arch = get_arch();

get_arch() returns the machine architechture as reported by "uname -m". For the "x86_64" architecture, additionally check whether "/bin/bash" is 64- or 32-bit to account for 32-bit userlands running on a 64-bit kernel.

"get_arch" is not exported; use the exported variable $arch if it is necessary to check for architecture.

  get_colors
  my ($color_notice, $color_lesser, $color_warn) = get_colors();

get_colors() reads the contents of "/etc/sbotools/sbotools.colors" to set custom values for $color_notice, $color_lesser and $color_warn. No color can be set to an invalid ANSI specification; in such cases, the default value is used instead. See Term::ANSIColor(3) for details.

  get_kernel_version
  my $kv = get_kernel_version();

get_kernel_version() checks the version of the running kernel and returns it in a format suitable for appending to a Slackware package version.

  get_optional
  my $optional = get_optional($sbo)

get_optional() checks for user-requested optional dependencies for $sbo. In all cases, results for "compat32" scripts have the corresponding "compat32" scripts to the results for the base script.

  get_sbo_from_loc
  my $sbo = get_sbo_from_loc($location);

get_sbo_from_loc() returns the package name from the $location passed in.

  get_slack_branch
  my $url = get_slack_branch();

get_slack_branch() returns the default git branch for the given Slackware version, if any. If the upstream repository does not have this branch, an onscreen message appears.

  get_slack_version
  my $version = get_slack_version();

get_slack_version() returns the appropriate version of the SBo reposiotry.

The program exits if the version is unsupported or if an error occurs.

  get_slack_version_url
  my $url = get_slack_version_url();

get_slack_version_url() returns the default URL for the given Slackware version.

The program exits if the version is unsupported or if an error occurs.

  idx
  my $idx = idx($needle, @haystack);

idx() looks for $needle in @haystack, and returns the index of where it was found, or "undef" if it was not found.

  ignore_tests
  my $result = ignore_tests($sbo)

ignore_tests() checks whether test failures for $sbo are to be ignored by sboupgrade(1). Results will be the same for the "compat32" version of the script.

  in
  my $found = in($needle, @haystack);

in() looks for $needle in @haystack, and returns a true value if it was found, and a false value otherwise.

in() formerly matched "Regexp", but this was changed for performance reasons. Use in_regexp() for the old functionality.

  indent
  my $str = indent($indent, $text);

indent() indents every non-empty line in $text by $indent spaces and returns the resulting string.

  is_obsolete
  my $is_obsolete = check_obsolete($sbo);

is_obsolete() takes the name of a SlackBuild and searches for it in the @obsolete array. It returns 1 if the SlackBuild is found and the Slackware version is -current equivalent.

  lint_sbo_config
  lint_sbo_config($running_script, %configs);

lint_sbo_config() takes the name of an sbotools script and a hash with configuration parameters. It checks the validity of all parameters except for REPO, exiting with an error message in case of invalid options.

sboconfig(1) runs this subroutine to lint any requested parameter changes; all other scripts lint the full configuration at startup.

  obsolete_array
  our @obsolete = obsolete_array();

obsolete_array() populates the shared @obsolete array based on the "/etc/sbotools/obsolete" file.

  on_blacklist
  my $result = on_blacklist($sbo);

on_blacklist() checks whether $sbo has been blacklisted. Results will be the same for the "compat32" version of the script.

  open_fh
  my ($ret, $exit) = open_fh($fn, $op);

open_fh() opens $fn for reading and/or writing depending on $op (e.g., ">" or "<").

It returns two values: the file handle and the exit status. If the exit status is non-zero, it returns an error message rather than a file handle.

  open_read
  my ($ret, $exit) = open_read($fn);

open_read() opens $fn for reading.

It returns two values: the file handle and the exit status. If the exit status is non-zero, it returns an error message rather than a file handle.

  print_color
  print_color "red bold";

print_color() takes one or more ANSI colors and prints, provided that the "COLOR" setting is "TRUE". See the "Function Interface" section in Term::ANSIColor(3) for a list of available colors.

Using colors "black" through "bright_white", "bold" and "reset" only is advisable to ensure terminal compatibility. When calling print_color() before exiting, ensure that a new line follows to avoid an improper cursor on some terminals.

There is no useful return value.

  print_failures
  print_failures($failures);

print_failures() prints all failures in the $failures array reference to STDERR, if any.

There is no useful return value.

  prompt
  exit unless prompt $color_notice, "Should we continue?", default => "yes";

prompt() prompts the user for an answer, optionally specifying a default of "yes" or "no".

If the default has been specified, it returns a true value for 'yes' and a false one for 'no'. Otherwise, it returns the content of the user's answer.

Output is wrapped at 72 characters.

  read_config
  read_config();

read_config() reads in the configuration settings from "/etc/sbotools/sbotools.conf", updating the %config hash. If "SBO_HOME" is "FALSE", it changes to "/usr/sbo". Additionally, "BUILD_IGNORE" and "RSYNC_DEFAULT" are turned on if "CLASSIC" is "TRUE"; "COLOR" is turned off.

When "sbotest" is running, the default value of "SBO_HOME" is "/usr/sbotest", and "ETC_PROFILE" and "CPAN_IGNORE" default to "TRUE". Supplementary setting "SBO_ARCHIVE" defaults to "/usr/sbotest/archive". "PKG_DIR" and "LOG_DIR" default to "/usr/sbotest/tests" and "/usr/sbotest/logs", respectively, but "sbotest" uses timestamped directories under the configured paths.

There is no useful return value.

  read_hints
  our @listings = read_hints();

read_hints() reads the contents of /etc/sbotools/sbotools.hints, returning an array of potentially valid lines in "/etc/sbotools/sbotools.hints". read_hints() is used to populate global array @listings, and should only be called at the start and again when editing the hints file.

@on_blacklist, @auto_reverse, %optional and @ignore_tests are populated here and used by on_blacklist(), auto_reverse(), get_optional() and "ignore_tests" later.

  reconcile_time
  my $corrected_seconds = reconcile_time($seconds);

reconcile_time() takes a duration in seconds (integer or otherwise) and subtracts any time spent stopped from keyboard signal. It returns the corrected number of seconds.

  save_options
  save_options($sbo, $opts)

save_options() saves build options to "/var/log/sbotools/sbo". For "compat32" packages, the file for the base script is used. If the file already exists and the user supplies no build options, the existing file is retained.

  script_error
  script_error();
  script_error($msg);

script_error() warns and exits with code _ERR_SCRIPT, printing the following to STDERR:

  A fatal script error has occurred. Exiting.

If a $msg was supplied, it instead prints:

  A fatal script error has occurred:
  $msg.
  Exiting.

dialog(1) displays $msg when running "sbotools".

There is no useful return value. For _ERR_USAGE, use usage_error(). For other error codes, use error_code().

  show_version
  show_version();

show_version() prints the sbotools version and licensing information to STDOUT.

There is no useful return value.

  slurp
  my $data = slurp($fn);

slurp() takes a filename in $fn, opens it, and reads in the entire file. The contents are then returned. On error, it returns "undef".

  time_format
  my $time_string = time_format($time);

time_format() takes a number of seconds (integer or otherwise) and returns a string H:MM:SS.

  uniq
  my @uniq = uniq(@duplicates);

uniq() removes any duplicates from @duplicates, otherwise returning the list in the same order.

  usage_error
  usage_error($msg);

usage_error() warns and exits with code _ERR_USAGE, printing $msg to STDERR. Error messages wrap at 72 characters.

dialog(1) displays $msg when running "sbotools".

There is no useful return value. For _ERR_SCRIPT, use script_error(); for other error codes, use error_code().

  version_cmp
  my $cmp = version_cmp($ver1, $ver2);

version_cmp() compares $ver1 with $ver2. It returns 1 if $ver1 is higher, -1 if $ver2 is higher and 0 if they are equal. It strips the running kernel version, as well as any locale information that may have been appended to the version strings.

  warn_color
  warn_color($color, $msg);

warn_color() emits a warning in the chosen color and resets the color afterwards. No colors are used unless "COLOR" is "TRUE". A newline is added automatically after the message. There is no useful return value.

  wrapsay
  wrapsay($msg, $trail);

wrapsay() outputs a message with the lines wrapped at 72 characters and a trailing newline. There is no useful return value. Optional $trail outputs an extra newline if present.

Use this subroutine whenever it is either obvious that the output exceeds 80 characters or the output includes a variable. "say" can be used in other cases. wrapsay() should not be used on output that can be piped for use in scripts (e.g., queue reports from sbofind(1)).

  wrapsay_color
  wrapsay_color($color, $msg, $trail);

wrapsay_color() takes a color, a message and any true value if a trailing line is required. It applies a color, runs the message through wrapsay() and resets the color afterwards. No colors are used unless "COLOR" is "TRUE". There is no useful return value.

EXIT CODES
The sbotools share the following exit codes:

  _ERR_USAGE         1   usage errors
  _ERR_SCRIPT        2   script or module bug
  _ERR_BUILD         3   errors when executing a SlackBuild
  _ERR_MD5SUM        4   download verification failure
  _ERR_DOWNLOAD      5   download failure
  _ERR_OPENFH        6   failure to open file handles
  _ERR_NOINFO        7   missing download information
  _ERR_F_SETD        8   fd-related temporary file failure
  _ERR_NOMULTILIB    9   lacking multilib capabilities when needed
  _ERR_CONVERTPKG    10  convertpkg-compat32 failure
  _ERR_NOCONVERTPKG  11  lacking convertpkg-compat32 when needed
  _ERR_INST_SIGNAL   12  the script was interrupted while building
  _ERR_CIRCULAR      13  attempted to calculate a circular dependency
  _ERR_USR_GRP       14  a required user or group is missing
  _ERR_GPG           15  GPG verification failed
  _ERR_STDIN         16  reading keyboard input failed

SEE ALSO
SBO::Lib(3), SBO::Lib::Build(3), SBO::Lib::Download(3), SBO::Lib::Info(3), SBO::Lib::Pkgs(3), SBO::Lib::Readme(3), SBO::Lib::Repo(3), SBO::Lib::Tree(3), dialog(1), Term::ANSIColor(3)

AUTHORS
SBO::Lib was originally written by Jacob Pipkin <j@dawnrazor.net> with contributions from Luke Williams <xocel@iquidus.org> and Andreas Guldstrand <andreas.guldstrand@gmail.com>.

MAINTAINER
SBO::Lib is maintained by K. Eugene Carlson <kvngncrlsn@gmail.com>.

LICENSE
The sbotools are licensed under the MIT License.

Copyright (C) 2012-2017, Jacob Pipkin, Luke Williams, Andreas Guldstrand.

Copyright (C) 2024-2026, K. Eugene Carlson.