abox-util.sh

#!/bin/bash
#---------------------------------------------------------------------
# vim:set noexpandtab:
#---------------------------------------------------------------------
# Copyright (c) 2023 James O. D. Hunt <jamesodhunt@gmail.com>
#
# SPDX-License-Identifier: Apache-2.0
#---------------------------------------------------------------------

readonly initial_year='2023'
readonly author_name='James O. D. Hunt'
readonly author_email='jamesodhunt@gmail.com'

# FIXME:
readonly description="\
Generate the assembly code to select the appropriate command to run.

This could be hand-crafted, but it's safer and easier to maintain if
we auto-generate it."

readonly script_name=${0##*/}

set -o errexit
set -o nounset
set -o pipefail

# XXX: Bash-specific code. zsh doesn't support this option and that *does*
# matter if this script is run sourced... since it'll be using zsh! ;)
[ -n "$BASH_VERSION" ] && set -o errtrace

[ -n "${DEBUG:-}" ] && set -o xtrace

# FIXME: Handle i18n issues if parsing command output.
export LC_ALL="C"
export LANG="C"

asm_ext='.asm'

copyright_year=''
copyright_name_tag=''

die()
{
	echo >&2 "ERROR: $*"
	exit 1
}

warn()
{
	echo >&2 "WARNING: $*"
}

info()
{
	echo "INFO: $*"
}

usage()
{
    cat <<EOT
Usage: $script_name [options]

Description: $description

Options:

 -h       : Show this help statement.

Notes:

FIXME

Examples:

FIXME

EOT
}

setup()
{
	local current_year=$(date '+%Y')

	if [ "$current_year" = "$initial_year" ]
	then
		copyright_year="$initial_year"
	else
		copyright_year=$(printf "%s-%s\n" \
			"$initial_year" \
			"$current_year")
	fi

	copyright_name_tag=$(printf "%s <%s>\n" \
		"$author_name" \
		"$author_email")

	true
}

# Return a sorted list of commands
get_commands()
{
	local cmd_dir="${1:-}"
	[ -z "$cmd_dir" ] && die "need command directory"
	[ -d "$cmd_dir" ] || die "invalid command directory: '$cmd_dir' (pwd: '$PWD')"

	local cmd

	find "$cmd_dir" -type f -name "*${asm_ext}" |\
		while read -r cmd
		do
			basename "$cmd"|sed "s/${asm_ext}//g"
		done | sort
}

generate_header()
{
	local out_file="${1:-}"
	[ -z "$out_file" ] && die "need output file"

	rm -f "$out_file"

	cat <<-EOT>>"${out_file}"
	;---------------------------------------------------------------------
	; XXX Generated file - do not modify! XXX
	;---------------------------------------------------------------------
	; Generated by: '$script_name'
	; Generated at: $(date -Isec)
	;---------------------------------------------------------------------
	; Copyright (c) ${copyright_year} ${copyright_name_tag}
	;
	; SPDX-License-Identifier: Apache-2.0
	;---------------------------------------------------------------------

	EOT
}

generate_details()
{
	local name="${1:-}"
	[ -z "$name" ] && die "need name"

	local version="${2:-}"
	[ -z "$version" ] && die "need version"

	local out_file="${3:-}"
	[ -z "$out_file" ] && die "need output file"

	generate_header "$out_file"

	local len
	len=$(echo -n "$name"|wc -c)

	cat <<-EOT>>"${out_file}"
	;---------------------------------------------------------------------
	; XXX Generated file - do not modify! XXX
	;---------------------------------------------------------------------
	; Generated by: '$script_name'
	; Generated at: $(date -Isec)
	;---------------------------------------------------------------------
	; Copyright (c) ${copyright_year} ${copyright_name_tag}
	;
	; SPDX-License-Identifier: Apache-2.0
	;---------------------------------------------------------------------

	global multicall_name
	global multicall_name_len
	global version

	section .rodata

	; Name of program when run as a multi-call binary
	; (as opposed to running it via a symlink to the
	; multi-call binary).
	multicall_name:  db  "${name}",0

	; Length of multicall_name
	; (not including the terminating nul byte).
	multicall_name_len: db ${len}

	version:         db  "${version}",0
	EOT
}

generate_defines()
{
	local out_file="${1:-}"
	[ -z "$out_file" ] && die "need output file"

	local cmd='errno'
	command -v "$cmd" &>/dev/null || die "need command: '$cmd'"

	local line

	generate_header "$out_file"

	errno -l | while read -r line
	do
		local name
		local num
		local desc

		eval set -- "$line"

		name="${1:-}" && shift
		num="${1:-}" && shift
		desc="${*:-}"

		printf "%%assign %-16s\t\t%d\t\t; %s\n" \
			"${name}" \
			"${num}" \
			"${desc}" \
			>> "${out_file}"
	done
}

generate_commands()
{
	local cmd_dir="${1:-}"
	[ -z "$cmd_dir" ] && die "need command directory"

	local out_file="${2:-}"
	[ -z "$out_file" ] && die "need output file"

	local -r commands_label='commands'
	local -r commands_count_label='commands_count'

	local cmds
	local cmd

	cmds=$(get_commands "$cmd_dir" || true)
	[ -z "$cmds" ] && die "no commands found"

	generate_header "$out_file"

	for cmd in $cmds
	do
		cat <<-EOT>>"${out_file}"
		extern command_${cmd}
		extern command_help_${cmd}

		EOT
	done

	cat <<-EOT>>"${out_file}"
	%include "header.inc"

	section .rodata

	;---------------------------------------------------------------------
	; List of available command names.

	command_names:

	EOT

	local count=0

	for cmd in $cmds
	do
		cat <<-EOT>>"${out_file}"
		command_name_${cmd}: db "${cmd}",0
		EOT
		count=$((count+1))
	done

	cat <<-EOT>>"${out_file}"

	;---------------------------------------------------------------------
	; Globals

	EOT

	for cmd in $cmds
	do
		cat <<-EOT>>"${out_file}"
		global command_entry_${cmd}
		EOT
	done

	cat <<-EOT>>"${out_file}"

	global ${commands_label}
	global ${commands_count_label}

	;---------------------------------------------------------------------
	; Number of available commands.

	${commands_count_label}: dq $count

	;---------------------------------------------------------------------
	; Array of available commands.

	${commands_label}:

	EOT

	for cmd in $cmds
	do
		cat <<-EOT>>"${out_file}"
		command_entry_${cmd}:
		  istruc Command
		    at Command.name,  dq  command_name_${cmd}
		    at Command.func,  dq  command_${cmd}
		    at Command.help,  dq  command_help_${cmd}
		  iend

		EOT
	done
}

generate_test_settings()
{
	local binary_name="${1:-}"
	[ -z "$binary_name" ] && die "need binary name"

	local binary_path="${2:-}"
	[ -z "$binary_path" ] && die "need binary path"
	[ -e "$binary_path" ] || die "invalid binary path: '$binary_path'"

	local cmds_dir="${3:-}"
	[ -z "$cmds_dir" ] && die "need commands directory"
	[ -d "$cmds_dir" ] || die "invalid commands directory: '$cmds_dir'"

	local test_dir="${4:-}"
	[ -z "$test_dir" ] && die "need test directory"

	mkdir -p "$test_dir"

	local settings_file="${5:-}"
	[ -z "$settings_file" ] && die "need settings file"

	local canonical_cmds_dir
	canonical_cmds_dir=$(realpath -e "$cmds_dir")

	cat <<-EOT>"$settings_file"
	# XXX: WARNING: Generated file - do not modify WARNING: XXX:

	ABOX_BINARY='$binary_path'
	ABOX_NAME='$binary_name'
	CMDS_DIR='$canonical_cmds_dir'
	TEST_DIR='$test_dir'
	EOT
}

# TODO: add SPDX license header check.
handle_check()
{
	local dir="${1:-}"
	[ -z "$dir" ] && die "need source directory"
	[ -d "$dir" ] || die "invalid source directory"

	local file

	find "$dir" -type f -name "*${asm_ext}" | while read -r file
	do
        # Ignore commented out code
		grep -Ev '[[:space:]]*;' "$file" |\
		(grep -Eq '\<call\>[[:space:]][[:space:]]*[^[:space:]]+' \
			&& \
			warn "file '$file' uses 'call' instruction rather than 'dcall' macro") || true

		grep -qE '^\.*fixme.*:' "$file" \
			&& die "file '$file' contains temporary/fixme labels" || true

		grep -qE '	' "$file" && die "file '$file' contains tabs" || true

		grep -qE "SPDX-License-Identifier:" "$file" ||\
			die "file '$file' missing SPDX-License-Identifier"

		local commented_out
		commented_out=$(grep -nE ';[a-zA-Z0-9]' "$file" || true)

		[ -n "$commented_out" ] && \
			die "file '$file' contains commented out code: '$commented_out'" || true

		# Handle magic programmer comments:
		#
		# - 'FIXME:' and 'TODO:' are allowed.
		#
		#   Rationale: They are assumed to represent non-fatal/critical
		#   "nice to have" / "should handle at some point" scenarios.
		#
		# - 'BUG:' and 'TESTING:' are not permitted.
		#
		#   Rationale: They are assumed to represent fatal/critical
		#   scenarios, or chunks of testing bloat / commented out code
		#   that should not be allowed in official commits.

		grep -qE '(\<BUG\>|TESTING:)' "$file" && \
			die "file '$file' contains BUG/TESTING comments" || true

	done

	true
}

handle_generate()
{
	local cmd="${1:-}"
	[ -z "$cmd" ] && die "need generate command"

	shift || true

	case "$cmd" in
		commands) generate_commands "$@" ;;
		defines) generate_defines "$@" ;;
		details) generate_details "$@" ;;
		test-settings) generate_test_settings "$@" ;;
		*) die "invalid generate command: '$@'" ;;
	esac
}

usage()
{
	cat <<-EOT
	Usage: $script_name [options] [cmd]

	Description: $description

	Options:

	  -h       : Show this help statement.

	Commands:

	  check                  : Perform basic static analysis on asm files in specified directory.
	  help                   : Show usage.
	  generate commands      : Generate command structures asm header.
	  generate defines       : Generate defines for system attributes like errno.
	  generate details       : Generate program details asm header.
	  generate test-settings : Generate settings file for bats tests.

	EOT
}

handle_args()
{
	local cmd="${1:-}"
	[ -z "$cmd" ] && die "need command"

	shift || true

	case "$cmd" in
		help|-h|--help) usage ;;
		check) handle_check "$@" ;;
		generate) handle_generate "$@" ;;
		*) die "invalid command: '$cmd'" ;;
	esac
}

main()
{
	setup

	handle_args "$@"
}

main "$@"