shell

Shell Scripting Standards for Scenescape

Shebang

Use #!/usr/bin/env bash for portability:

#!/usr/bin/env bash

Not #!/bin/bash (less portable) or #!/bin/sh (POSIX only, limiting).

Code Style

Linting

• Linter: shellcheck with style warnings
• Command:

  make lint-shell         # Lint all .sh files
  

Indentation

• Use 2 spaces (never tabs)
• Consistent with project standards

Line Length

• Target: 80-100 characters for readability
• Break long commands with \ line continuation

if [[ condition ]]; then
  echo "Indented with 2 spaces"
  if [[ nested ]]; then
    echo "Nested indentation"
  fi
fi

Best Practices

Exit on Error

Use set -e to exit on any error:

#!/usr/bin/env bash
set -e  # Exit immediately if a command fails
set -o pipefail  # Fail if any command in pipeline fails

# Now any failing command will exit the script
command1
command2
command3

Strict Mode

For critical scripts, use strict mode:

set -euo pipefail
# -e: exit on error
# -u: exit on undefined variable
# -o pipefail: fail on pipe errors

Trap Errors

Clean up on exit or error:

cleanup() {
  echo "Cleaning up..."
  rm -f /tmp/tempfile
}

trap cleanup EXIT
trap 'echo "Error on line $LINENO"' ERR

Variables

Naming

• Local variables: lowercase_with_underscores
• Environment/Global: UPPERCASE_WITH_UNDERSCORES
• Read-only: readonly CONSTANT_VALUE

# Local
local temp_file="/tmp/data"
local count=0

# Global/Environment
WORKSPACE_DIR="/workspace"
export DATABASE_PASSWORD

# Constants
readonly MAX_RETRIES=3

Quoting

Always quote variables to prevent word splitting:

# Good
file_path="/path/with spaces/file.txt"
cat "$file_path"

# Bad - breaks with spaces
cat $file_path

Default Values

# Use default if variable is unset
config_file="${CONFIG_FILE:-/etc/default.conf}"

# Use default if variable is unset or empty
database="${DATABASE_NAME:=scenescape}"

# Error if variable is unset
required="${REQUIRED_VAR:?Error: REQUIRED_VAR must be set}"

Conditionals

Use [[ ]] for Tests

Prefer [[ ]] over [ ] or test:

# Good - modern test
if [[ -f "$file" ]]; then
  echo "File exists"
fi

if [[ "$value" == "expected" ]]; then
  echo "Match"
fi

# Pattern matching
if [[ "$filename" == *.txt ]]; then
  echo "Text file"
fi

Common Test Operators

# File tests
[[ -f "$file" ]]      # File exists
[[ -d "$dir" ]]       # Directory exists
[[ -r "$file" ]]      # Readable
[[ -w "$file" ]]      # Writable
[[ -x "$file" ]]      # Executable

# String tests
[[ -z "$string" ]]    # Empty string
[[ -n "$string" ]]    # Non-empty string
[[ "$a" == "$b" ]]    # Equal
[[ "$a" != "$b" ]]    # Not equal

# Numeric tests
[[ "$a" -eq "$b" ]]   # Equal
[[ "$a" -ne "$b" ]]   # Not equal
[[ "$a" -lt "$b" ]]   # Less than
[[ "$a" -gt "$b" ]]   # Greater than

Short-Circuit Logic

# Execute command2 only if command1 succeeds
command1 && command2

# Execute command2 only if command1 fails
command1 || command2

# Multiple conditions
[[ -f "$file" ]] && [[ -r "$file" ]] && cat "$file"

Functions

Declaration

function_name() {
  local arg1="$1"
  local arg2="$2"

  # Function body
  echo "Processing: $arg1, $arg2"
  return 0
}

# Call function
function_name "value1" "value2"

Return Values

check_status() {
  if [[ condition ]]; then
    return 0  # Success
  else
    return 1  # Failure
  fi
}

# Use return value
if check_status; then
  echo "Check passed"
else
  echo "Check failed"
fi

Local Variables

Always use local for function variables:

process_data() {
  local input="$1"
  local temp_file="/tmp/temp_$$"

  # Process data
  # ...
}

Command Substitution

Use $() instead of backticks:

# Good
current_date=$(date +%Y-%m-%d)
file_count=$(ls | wc -l)

# Avoid (backticks)
current_date=`date +%Y-%m-%d`

Loops

For Loops

# Iterate over list
for item in item1 item2 item3; do
  echo "$item"
done

# Iterate over files
for file in /path/*.txt; do
  [[ -f "$file" ]] && process "$file"
done

# C-style loop
for ((i = 0; i < 10; i++)); do
  echo "Iteration $i"
done

While Loops

# Read file line by line
while IFS= read -r line; do
  echo "Line: $line"
done < input.txt

# Condition-based
count=0
while [[ $count -lt 10 ]]; do
  echo "$count"
  ((count++))
done

Arrays

Declaration and Access

# Declare array
declare -a services=("controller" "manager" "autocalibration")

# Access elements
echo "${services[0]}"      # First element
echo "${services[@]}"      # All elements
echo "${#services[@]}"     # Array length

# Iterate
for service in "${services[@]}"; do
  echo "Service: $service"
done

Adding Elements

services+=("mapping")

Error Handling

Check Command Success

if command_that_might_fail; then
  echo "Success"
else
  echo "Failed with exit code: $?"
  exit 1
fi

Error Messages to stderr

error_exit() {
  echo "Error: $1" >&2
  exit 1
}

# Usage
[[ -f "$config_file" ]] || error_exit "Config file not found: $config_file"

Verbose Error Output

set -x  # Enable debug output (prints each command)
# Commands here will be echoed
set +x  # Disable debug output

File Operations

Reading Files

# Read entire file
content=$(cat file.txt)

# Read line by line
while IFS= read -r line; do
  echo "$line"
done < file.txt

Writing Files

# Overwrite
echo "content" > file.txt

# Append
echo "more content" >> file.txt

# Here document
cat > config.txt << EOF
setting1=value1
setting2=value2
EOF

Temporary Files

temp_file=$(mktemp)
trap "rm -f '$temp_file'" EXIT

# Use temp file
echo "data" > "$temp_file"

Path Handling

Absolute Paths

# Get script directory
script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)

# Construct absolute paths
config_file="$script_dir/config.txt"

Path Components

filepath="/path/to/file.txt"

dirname=$(dirname "$filepath")    # /path/to
basename=$(basename "$filepath")  # file.txt
filename="${basename%.*}"         # file
extension="${basename##*.}"       # txt

Process Management

Background Jobs

# Start background job
long_running_command &
pid=$!

# Wait for specific job
wait $pid

# Wait for all background jobs
wait

Process Substitution

# Compare outputs of two commands
diff <(command1) <(command2)

# Read from command output
while read -r line; do
  echo "$line"
done < <(command)

Scenescape-Specific Patterns

Docker Commands

# Build with progress
env BUILDKIT_PROGRESS=plain docker build \
  --build-arg VERSION="$VERSION" \
  -t "scenescape-service:$VERSION" \
  .

Environment Variables

# Check required variables
: "${SUPASS:?SUPASS environment variable must be set}"
: "${DATABASE_PASSWORD:?DATABASE_PASSWORD must be set}"

Makefile Integration

# Get variables from Makefile
VERSION=$(cat version.txt)
BUILD_DIR="${BUILD_DIR:-build}"

Common Patterns

Retry Logic

retry_command() {
  local max_attempts=3
  local attempt=1

  while [[ $attempt -le $max_attempts ]]; do
    if command_to_retry; then
      return 0
    fi
    echo "Attempt $attempt failed, retrying..." >&2
    ((attempt++))
    sleep 2
  done

  return 1
}

Input Validation

validate_input() {
  local input="$1"

  if [[ -z "$input" ]]; then
    echo "Error: Input cannot be empty" >&2
    return 1
  fi

  if [[ ! "$input" =~ ^[0-9]+$ ]]; then
    echo "Error: Input must be numeric" >&2
    return 1
  fi

  return 0
}

Logging

log() {
  echo "[$(date +'%Y-%m-%d %H:%M:%S')] $*"
}

log_error() {
  echo "[$(date +'%Y-%m-%d %H:%M:%S')] ERROR: $*" >&2
}

log "Starting process"
log_error "Something went wrong"

Anti-Patterns to Avoid

❌ Don't use eval (security risk):

# Bad
eval "$user_input"

# Good - use arrays or proper quoting
args=("$arg1" "$arg2")
command "${args[@]}"

❌ Don't parse ls output:

# Bad
files=$(ls *.txt)
for file in $files; do
  process "$file"
done

# Good
for file in *.txt; do
  [[ -f "$file" ]] && process "$file"
done

❌ Don't use cat unnecessarily:

# Bad (useless use of cat)
cat file.txt | grep pattern

# Good
grep pattern file.txt

❌ Don't ignore errors:

# Bad
command_that_might_fail

# Good
if ! command_that_might_fail; then
  echo "Command failed" >&2
  exit 1
fi

Testing

Manual Testing

Test scripts with:

bash -n script.sh   # Syntax check
shellcheck script.sh   # Linting
bash -x script.sh   # Debug mode

Test Different Inputs

# Test edge cases
test_script() {
  ./script.sh ""           # Empty input
  ./script.sh "normal"     # Normal input
  ./script.sh "with spaces"  # Spaces
  ./script.sh "$long_string"  # Long input
}

Documentation

Script Header

#!/usr/bin/env bash

# SPDX-FileCopyrightText: (C) 2025 Intel Corporation
# SPDX-License-Identifier: Apache-2.0

#
# Script Name: deploy.sh
# Description: Deploy Scenescape services to production
# Usage: ./deploy.sh [environment]
#

set -euo pipefail

Function Documentation

#
# Function: process_data
# Description: Process input data and generate output
# Arguments:
#   $1 - Input file path
#   $2 - Output directory
# Returns:
#   0 on success, 1 on error
#
process_data() {
  local input_file="$1"
  local output_dir="$2"
  # ...
}

Performance

Avoid Subshells

# Slower - creates subshell
count=$(expr $count + 1)

# Faster - built-in arithmetic
((count++))

Use Built-ins

# Prefer bash built-ins over external commands
[[ "$string" == *pattern* ]]  # Built-in pattern matching
# vs
echo "$string" | grep pattern  # External process

Portability

Bash-specific Features

Scenescape uses bash, not POSIX sh. These are OK:

• [[ ]] tests
• Arrays
• $() command substitution
• (( )) arithmetic
• [[ =~ ]] regex matching

Avoid Bashisms When Possible

But prefer portable constructs when they work equally well.