List Commands with Descriptions (#161)

* Updated `utils.sh` with `bpkg_exec_exist` and `bpkg_exec_or_exit`.
* Updated scripts with `bpkg_exec_or_exit`.
* Updated `install.sh` to utilize utility functions.
* Updated `runner` in `run.sh`.
* Added `--list` option to `run.sh`.
* Added `commands-description` to `bpkg.json`.
* Updated README TOC and missing `dependencies-dev` section.
* Added `commands-description` section to README.
* Corrected failing shellcheck.
pull/162/head
Sam Likins 1 year ago committed by GitHub
parent e2e373acf6
commit 79481450fe
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -27,14 +27,15 @@ You can install shell scripts globally (on `${PREFIX:-/usr/local/bin}`) or use t
* [scripts](#scripts)
* [files (optional)](#files-optional)
* [dependencies (optional)](#dependencies-optional)
* [dependencies-dev (optional)](#dependencies-dev-optional)
* [commands (optional)](#commands-optional)
* [commands-description (optional)](#commands-description-optional)
* [Packaging best practices](#packaging-best-practices)
* [Package exports](#package-exports)
* [Sponsors](#sponsors)
* [Contributors](#contributors)
* [Backers](#backers)
* [License](#license)
<!-- END-MARKDOWN-TOC -->
## Install
@ -262,6 +263,16 @@ This is a hash of dependencies. The keys are the package names, and the values a
}
```
### dependencies-dev (optional)
This is a hash of dependencies only needed during development. Like the `dependencies` array, the keys are the package names, and the values are the version specifiers; `'master'` or a tagged release can be used as the identifier. These development dependencies are installed by adding the `-d` or `--dev` flags to the `bpkg install` command.
```json
"dependencies-dev": {
"term": "0.0.1"
}
```
### commands (optional)
This is a hash of commands. The keys are the names of the commands and the values are the commands to execute in a shell. The commands can be called from the command line with `bpkg run` followed by the command name.
@ -279,6 +290,16 @@ $ bpkg run say-hello "Bash Package Manager"
Hello Bash Package Manager
```
### commands-description (optional)
This is a hash of descriptions for configured commands. The keys are the names of the commands and the values are the descriptions for the specified commands. The command descriptions can be listed on the command line by providing the `-l` or `--list` flags after the `bpkg run` command.
```json
"commands-description": {
"say-hello": "Output hello to provided name (ex: bpkg run say-hello John)"
}
```
## Packaging best practices
These are guidelines that we strongly encourage developers to follow.

@ -8,5 +8,9 @@
"commands": {
"lint": "command shellcheck **/*.sh",
"list-sources": "echo ${BPKG_PACKAGE_SOURCES[@]} | sed 's/ /\n/g'"
},
"commands-description": {
"lint": "Execute shellcheck against all .sh files in project",
"list-sources": "Output package source files"
}
}

@ -1,31 +1,20 @@
#!/usr/bin/env bash
if ! type -f bpkg-realpath &>/dev/null; then
echo "error: bpkg-realpath not found, aborting"
exit 1
else
# shellcheck disable=SC2230
# shellcheck source=lib/realpath/realpath.sh
source "$(which bpkg-realpath)"
fi
if ! type -f bpkg-utils &>/dev/null; then
echo "error: bpkg-utils not found, aborting"
exit 1
else
# shellcheck disable=SC2230
fi
# shellcheck source=lib/utils/utils.sh
source "$(which bpkg-utils)"
fi
if ! type -f bpkg-getdeps &>/dev/null; then
echo "error: bpkg-getdeps not found, aborting"
exit 1
else
# shellcheck disable=SC2230
# shellcheck source=lib/realpath/realpath.sh
bpkg_exec_or_exit bpkg-realpath &&
source "$(which bpkg-realpath)"
# shellcheck source=lib/getdeps/getdeps.sh
bpkg_exec_or_exit bpkg-getdeps &&
source "$(which bpkg-getdeps)"
fi
bpkg_initrc
@ -34,15 +23,6 @@ let install_dev=0
let force_actions=${BPKG_FORCE_ACTIONS:-0}
let needs_global=0
## check parameter consistency
validate_parameters () {
if [[ ${#BPKG_GIT_REMOTES[@]} -ne ${#BPKG_REMOTES[@]} ]]; then
error "$(printf 'BPKG_GIT_REMOTES[%d] differs in size from BPKG_REMOTES[%d] array' "${#BPKG_GIT_REMOTES[@]}" "${#BPKG_REMOTES[@]}")"
return 1
fi
return 0
}
## output usage
usage () {
echo 'usage: bpkg-install [directory]'
@ -52,62 +32,6 @@ usage () {
echo ' or: bpkg-install [-g|--global] [-f|--force] ...<user>/<package>'
}
## format and output message
message () {
if type -f bpkg-term > /dev/null 2>&1; then
bpkg-term color "$1"
fi
shift
echo -n " $1"
shift
if type -f bpkg-term > /dev/null 2>&1; then
bpkg-term reset
fi
printf ': '
if type -f bpkg-term > /dev/null 2>&1; then
bpkg-term reset
bpkg-term bright
fi
printf "%s\n" "$@"
if type -f bpkg-term > /dev/null 2>&1; then
bpkg-term reset
fi
}
## output error
error () {
message 'red' 'error' "$@" >&2
return 0
}
## output warning
warn () {
message 'yellow' 'warn' "$@" >&2
return 0
}
## output info
info () {
local title='info'
if (( "$#" > 1 )); then
title="$1"
shift
fi
message 'cyan' "$title" "$@"
return 0
}
save_remote_file () {
local auth_param dirname path url
@ -209,7 +133,7 @@ bpkg_install () {
pkgs+=("$opt")
shift
else
error "Unknown option \`$opt'"
bpkg_error "Unknown option \`$opt'"
return 1
fi
;;
@ -249,7 +173,7 @@ bpkg_install () {
did_fail=0
break
elif [[ "$?" == '2' ]]; then
error 'fatal error occurred during install'
bpkg_error 'fatal error occurred during install'
return 1
fi
i=$((i+1))
@ -257,7 +181,7 @@ bpkg_install () {
done
if (( did_fail == 1 )); then
error 'package not found on any remote'
bpkg_error 'package not found on any remote'
return 1
fi
@ -309,7 +233,7 @@ bpkg_install_from_remote () {
name="${pkg_parts[0]}"
version="${pkg_parts[1]}"
else
error 'Error parsing package version'
bpkg_error 'Error parsing package version'
return 1
fi
@ -329,7 +253,7 @@ bpkg_install_from_remote () {
user="${pkg_parts[0]}"
name="${pkg_parts[1]}"
else
error 'Unable to determine package name'
bpkg_error 'Unable to determine package name'
return 1
fi
@ -340,7 +264,7 @@ bpkg_install_from_remote () {
## check to see if remote is raw with oauth (GHE)
if [[ "${remote:0:10}" == "raw-oauth|" ]]; then
info 'Using OAUTH basic with content requests'
bpkg_info 'Using OAUTH basic with content requests'
OLDIFS="$IFS"
IFS="'|'"
local remote_parts=("$remote")
@ -360,7 +284,7 @@ bpkg_install_from_remote () {
## clean up extra slashes in uri
uri=${uri/\/\///}
info "Install $uri from remote $remote [$git_remote]"
bpkg_info "Install $uri from remote $remote [$git_remote]"
## Ensure remote is reachable
## If a remote is totally down, this will be considered a fatal
@ -368,7 +292,7 @@ bpkg_install_from_remote () {
## from the broken remote.
{
if ! url_exists "$remote" "$auth_param"; then
error "Remote unreachable: $remote"
bpkg_error "Remote unreachable: $remote"
return 2
fi
}
@ -392,7 +316,7 @@ bpkg_install_from_remote () {
if (( 0 == has_pkg_json )); then
## check to see if there's a Makefile. If not, this is not a valid package
if ! url_exists "$url/Makefile?$nonce" "$auth_param"; then
warn "Makefile not found, skipping remote: $url"
bpkg_warn "Makefile not found, skipping remote: $url"
return 1
fi
fi
@ -462,8 +386,8 @@ bpkg_install_from_remote () {
fi
if [[ -z "$build" ]]; then
warn 'Missing build script'
warn 'Trying "make install"...'
bpkg_warn 'Missing build script'
bpkg_warn 'Trying "make install"...'
build='make install'
fi
@ -483,7 +407,7 @@ bpkg_install_from_remote () {
( (( 0 == prevent_prune )) && rm -rf "$name-$version")
## shallow clone
info "Cloning $repo_url to $(pwd)/$name-$version"
bpkg_info "Cloning $repo_url to $(pwd)/$name-$version"
(test -d "$name-$version" || git clone "$repo_url" "$name-$version" 2>/dev/null) && (
## move into directory
cd "$name-$version" && (
@ -495,7 +419,7 @@ bpkg_install_from_remote () {
)
## build
info "Performing install: \`$build'"
bpkg_info "Performing install: \`$build'"
mkdir -p "$PREFIX"/{bin,lib}
build_output=$(eval "$build")
echo "$build_output"
@ -518,7 +442,7 @@ bpkg_install_from_remote () {
mkdir -p "$BPKG_PACKAGE_DEPS/bin"
# install package dependencies
info "Install dependencies for $name"
bpkg_info "Install dependencies for $name"
BPKG_DEPS_EXEC="bpkg_getdeps"
if (( 1 == install_dev )); then
@ -533,19 +457,19 @@ bpkg_install_from_remote () {
if [[ "$script" ]];then
local scriptname="$(echo "$script" | xargs basename )"
info "fetch" "$url/$script"
warn "BPKG_PACKAGE_DEPS is '$BPKG_PACKAGE_DEPS'"
info "write" "$BPKG_PACKAGE_DEPS/$name/$script"
bpkg_info "fetch" "$url/$script"
bpkg_warn "BPKG_PACKAGE_DEPS is '$BPKG_PACKAGE_DEPS'"
bpkg_info "write" "$BPKG_PACKAGE_DEPS/$name/$script"
save_remote_file "$url/$script" "$BPKG_PACKAGE_DEPS/$name/$script" "$auth_param"
scriptname="${scriptname%.*}"
info "$scriptname to PATH" "$BPKG_PACKAGE_DEPS/bin/$scriptname"
bpkg_info "$scriptname to PATH" "$BPKG_PACKAGE_DEPS/bin/$scriptname"
if (( force_actions == 1 )); then
ln -sf "../$name/$script" "$BPKG_PACKAGE_DEPS/bin/$scriptname"
else
if test -f "$BPKG_PACKAGE_DEPS/bin/$scriptname"; then
warn "'$BPKG_PACKAGE_DEPS/bin/$scriptname' already exists. Overwrite? (yN)"
bpkg_warn "'$BPKG_PACKAGE_DEPS/bin/$scriptname' already exists. Overwrite? (yN)"
read -r yn
case $yn in
Yy) rm -f "$BPKG_PACKAGE_DEPS/bin/$scriptname" ;;
@ -565,9 +489,9 @@ bpkg_install_from_remote () {
for file in "${files[@]}"; do
(
if [[ "$file" ]];then
info "fetch" "$url/$file"
warn "BPKG_PACKAGE_DEPS is '$BPKG_PACKAGE_DEPS'"
info "write" "$BPKG_PACKAGE_DEPS/$name/$file"
bpkg_info "fetch" "$url/$file"
bpkg_warn "BPKG_PACKAGE_DEPS is '$BPKG_PACKAGE_DEPS'"
bpkg_info "write" "$BPKG_PACKAGE_DEPS/$name/$file"
save_remote_file "$url/$file" "$BPKG_PACKAGE_DEPS/$name/$file" "$auth_param"
fi
)
@ -580,7 +504,7 @@ bpkg_install_from_remote () {
## Use as lib or perform install
if [[ ${BASH_SOURCE[0]} != "$0" ]]; then
export -f bpkg_install
elif validate_parameters; then
elif bpkg_validate; then
bpkg_install "$@"
exit $?
else

@ -3,10 +3,10 @@
if ! type -f bpkg-utils &>/dev/null; then
echo "error: bpkg-utils not found, aborting"
exit 1
else
fi
# shellcheck source=lib/utils/utils.sh
source "$(which bpkg-utils)"
fi
bpkg_initrc

@ -1,13 +1,16 @@
#!/usr/bin/env bash
if ! type -f bpkg-realpath &>/dev/null; then
echo "error: bpkg-realpath not found, aborting"
if ! type -f bpkg-utils &>/dev/null; then
echo "error: bpkg-utils not found, aborting"
exit 1
else
# shellcheck disable=SC2230
fi
# shellcheck source=lib/utils/utils.sh
source "$(which bpkg-utils)"
# shellcheck source=lib/realpath/realpath.sh
bpkg_exec_or_exit bpkg-realpath &&
source "$(which bpkg-realpath)"
fi
BPKG_JSON="$(which bpkg-json)"

@ -1,62 +1,81 @@
#!/usr/bin/env bash
if ! type -f bpkg-realpath &>/dev/null; then
echo "error: bpkg-realpath not found, aborting"
exit 1
else
# shellcheck disable=SC2230
# shellcheck source=lib/realpath/realpath.sh
source "$(which bpkg-realpath)"
fi
if ! type -f bpkg-utils &>/dev/null; then
echo "error: bpkg-utils not found, aborting"
exit 1
else
fi
# shellcheck source=lib/utils/utils.sh
source "$(which bpkg-utils)"
fi
if ! type -f bpkg-env &>/dev/null; then
echo "error: bpkg-env not found, aborting"
exit 1
else
# shellcheck disable=SC2230
# shellcheck source=lib/env/env.sh
source "$(which bpkg-env)"
fi
# shellcheck source=lib/realpath/realpath.sh
bpkg_exec_or_exit bpkg-realpath &&
source "$(which bpkg-realpath)"
if ! type -f bpkg-install &>/dev/null; then
echo "error: bpkg-install not found, aborting"
exit 1
else
# shellcheck source=lib/install/install.sh
bpkg_exec_or_exit bpkg-install &&
source "$(which bpkg-install)"
fi
if ! type -f bpkg-package &>/dev/null; then
echo "error: bpkg-package not found, aborting"
exit 1
else
# shellcheck source=lib/package/package.sh
bpkg_exec_or_exit bpkg-package &&
source "$(which bpkg-package)"
fi
bpkg_initrc
## output usage
usage () {
echo 'usage: bpkg-run [-h|--help]'
echo ' or: bpkg-run [-h|--help] [command]'
echo ' or: bpkg-run [-l|--list]'
echo ' or: bpkg-run [-s|--source] <package> [command]'
echo ' or: bpkg-run [-s|--source] <user>/<package> [command]'
}
runner () {
bpkg_list_commands () {
local commands
local col_len
local description
commands="$(bpkg_package 2>/dev/null | grep '\["commands"' | sed 's/\["commands","\([^"]*\).*/\1/')"
col_len="$(wc -L <<< "${commands}")"
if [ "${col_len}" -eq 0 ]; then
bpkg_error "No commands provided in BPKG package file."
return 1
fi
for command in ${commands}; do
description="$(bpkg_package commands-description "${command}")"
if [ -z "${description}" ]; then
description="Runs the ${command} command as defined in BPKG configuration"
fi
printf " "
bpkg_exec_exist bpkg-term &&
bpkg-term color cyan
printf "%-${col_len}s " "${command}"
bpkg_exec_exist bpkg-term && {
bpkg-term reset
bpkg-term bright
}
printf "%s\n" "${description}"
bpkg_exec_exist bpkg-term &&
bpkg-term reset
done
return 0
}
bpkg_runner () {
local cmd="$1"
shift
# shellcheck disable=SC2068
eval "$cmd"
return $?
}
@ -75,6 +94,11 @@ bpkg_run () {
return 0
;;
-l|--list)
bpkg_list_commands
return $?
;;
-s|--source)
should_source=1
shift
@ -137,8 +161,7 @@ bpkg_run () {
done
shift
# shellcheck disable=SC2068
runner "$prefix ${args[*]}" $@
bpkg_runner "$prefix ${args[*]}"
return $?
fi
fi
@ -172,9 +195,9 @@ bpkg_run () {
return 1
fi
local pkgname="$(bpkg_package name 2>/dev/null)"
if [ -n "$pkgname" ]; then
name="$pkgname"
local pkg_name="$(bpkg_package name 2>/dev/null)"
if [ -n "$pkg_name" ]; then
name="$pkg_name"
fi
if (( 1 == should_emit_source )); then
@ -218,8 +241,7 @@ bpkg_run () {
done
shift
# shellcheck disable=SC2068
runner "$prefix ${args[*]}" $@
bpkg_runner "$prefix ${args[*]}"
fi
# shellcheck disable=SC2068

@ -3,19 +3,10 @@
if ! type -f bpkg-utils &>/dev/null; then
echo "error: bpkg-utils not found, aborting"
exit 1
else
# shellcheck source=lib/utils/utils.sh
source "$(which bpkg-utils)"
fi
if ! type -f bpkg-env &>/dev/null; then
echo "error: bpkg-env not found, aborting"
exit 1
else
# shellcheck disable=SC2230
# shellcheck source=lib/env/env.sh
source "$(which bpkg-env)"
fi
# shellcheck source=lib/utils/utils.sh
source "$(which bpkg-utils)"
bpkg_initrc

@ -1,12 +1,17 @@
#!/usr/bin/env bash
if ! type -f bpkg-run &>/dev/null; then
echo "error: bpkg-run not found, aborting"
if ! type -f bpkg-utils &>/dev/null; then
echo "error: bpkg-utils not found, aborting"
exit 1
else
fi
# shellcheck source=lib/utils/utils.sh
source "$(which bpkg-utils)"
# shellcheck source=lib/run/run.sh
bpkg_exec_or_exit bpkg-run &&
source "$(which bpkg-run)"
fi
bpkg_source () {
# shellcheck disable=SC2068

@ -3,11 +3,10 @@
if ! type -f bpkg-utils &>/dev/null; then
echo "error: bpkg-utils not found, aborting"
exit 1
else
# shellcheck disable=SC2230
fi
# shellcheck source=lib/utils/utils.sh
source "$(which bpkg-utils)"
fi
## output usage
usage () {

@ -3,10 +3,10 @@
if ! type -f bpkg-utils &>/dev/null; then
echo "error: bpkg-utils not found, aborting"
exit 1
else
fi
# shellcheck source=lib/utils/utils.sh
source "$(which bpkg-utils)"
fi
bpkg_initrc

@ -1,13 +1,7 @@
#!/usr/bin/env bash
if ! type -f bpkg-env &>/dev/null; then
echo "error: bpkg-env not found, aborting"
exit 1
else
# shellcheck disable=SC2230
# shellcheck source=lib/env/env.sh
source "$(which bpkg-env)"
fi
if [ -z "${BPKG_UTILS}" ]; then
BPKG_UTILS=1
## Collection of shared bpkg functions
@ -46,32 +40,30 @@ bpkg_validate () {
return 0
}
## format and output message
bpkg_message () {
if type -f bpkg-term > /dev/null 2>&1; then
bpkg_exec_exist bpkg-term &&
bpkg-term color "${1}"
fi
shift
echo -n " ${1}"
shift
if type -f bpkg-term > /dev/null 2>&1; then
bpkg_exec_exist bpkg-term &&
bpkg-term reset
fi
printf ": "
if type -f bpkg-term > /dev/null 2>&1; then
bpkg_exec_exist bpkg-term && {
bpkg-term reset
bpkg-term bright
fi
}
printf "%s\n" "${@}"
if type -f bpkg-term > /dev/null 2>&1; then
bpkg_exec_exist bpkg-term &&
bpkg-term reset
fi
}
## output error
@ -98,6 +90,26 @@ bpkg_info () {
bpkg_message "cyan" "${title}" "${@}"
}
## check if executable exists in path
bpkg_exec_exist () {
local exec_name="${1}"
type -f "${exec_name}" > /dev/null 2>&1
}
## executable exists in path or exit with message
bpkg_exec_or_exit () {
local exec_name="${1}"
local exit_error="${2:-1}"
if ! bpkg_exec_exist "${exec_name}"; then
bpkg_error "${exec_name} not found, aborting"
exit "${exit_error}"
fi
}
## takes a remote and git-remote and sets the globals:
## BPKG_REMOTE: raw remote URI
## BPKG_GIT_REMOTE: git remote for cloning
@ -149,6 +161,14 @@ bpkg_select_raw_path() {
return 0
}
bpkg_exec_or_exit bpkg-env
# shellcheck disable=SC2230
# shellcheck source=lib/env/env.sh
source "$(which bpkg-env)"
export -f bpkg_initrc
export -f bpkg_validate
@ -157,5 +177,9 @@ export -f bpkg_warn
export -f bpkg_error
export -f bpkg_info
export -f bpkg_exec_exist
export -f bpkg_exec_or_exit
export -f bpkg_select_remote
export -f bpkg_select_raw_path
fi

Loading…
Cancel
Save