You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
Matthew Raymer 6519bf6773 Add automated iOS build script with version management 4 days ago
..
README.md WIP: add Electron platform configuration to Capacitor 1 week ago
build-android.sh feat: Add comprehensive Electron build script and automation 1 week ago
build-electron.sh feat: Add comprehensive Electron build script and automation 1 week ago
build-ios.sh Add automated iOS build script with version management 4 days ago
check-prerequisites.js fix some test scripts 3 months ago
common.sh feat: Add comprehensive Electron build script and automation 1 week ago
copy-wasm.js fix error loading WASM file 1 month ago
copy-web-assets.sh feat(android): update Capacitor assets and fix Xcode project version 3 months ago
electron-dev.sh WIP: Fix Electron TypeScript compilation and SQLite configuration 1 week ago
generate-icons.sh feat(android): update Capacitor assets and fix Xcode project version 3 months ago
openssl_signing_console.sh chore: update capacitor config and script paths 2 months ago
run-available-mobile-tests.js feat: Add comprehensive mobile testing infrastructure 4 months ago
setup-electron.sh WIP: Fix Electron TypeScript compilation and SQLite configuration 1 week ago
test-all.sh migration: move to bash based build scripts 2 weeks ago
test-android.js fix some test scripts 3 months ago
test-common.sh migration: move to bash based build scripts 2 weeks ago
test-env.sh WIP: add Electron platform configuration to Capacitor 1 week ago
test-ios.js docs: add macOS build and packaging instructions 2 months ago
test-mobile.sh migration: move to bash based build scripts 2 weeks ago

README.md

TimeSafari Build Scripts

This directory contains unified build and test scripts for the TimeSafari application. All scripts use a common utilities library to eliminate redundancy and provide consistent logging, error handling, timing, and environment variable management.

Architecture

Common Utilities (common.sh)

The common.sh script provides shared functionality used by all build scripts:

  • Logging Functions: log_info, log_success, log_warn, log_error, log_debug, log_step
  • Timing: measure_time for execution time tracking
  • Headers/Footers: print_header, print_footer for consistent output formatting
  • Validation: check_command, check_directory, check_file, check_venv
  • Execution: safe_execute for error-handled command execution
  • Utilities: get_git_hash, clean_build_artifacts, validate_env_vars
  • Environment Management: setup_build_env, setup_app_directories, load_env_file, print_env_vars
  • CLI: parse_args, print_usage for command-line argument handling

Environment Variable Management

All scripts automatically handle environment variables for different build types:

Build Types and Environment Variables

Platform Mode PWA Enabled Native Features Build Script
web web true false build-web.sh
capacitor capacitor false true build-capacitor.sh

Automatic Environment Setup

Each script automatically:

  1. Sets platform-specific variables based on build type
  2. Gets git hash for versioning (VITE_GIT_HASH)
  3. Creates application directories (~/.local/share/TimeSafari/timesafari)
  4. Loads .env file if it exists
  5. Validates required variables when needed

Environment Functions

  • setup_build_env(build_type, production) - Sets environment for specific build type
  • setup_app_directories() - Creates necessary application directories
  • load_env_file(filename) - Loads variables from .env file
  • print_env_vars(prefix) - Displays current environment variables
  • validate_env_vars(var1, var2, ...) - Validates required variables exist

Script Structure

All scripts follow this unified pattern:

#!/bin/bash
# script-name.sh
# Author: Matthew Raymer
# Description: Brief description of what the script does
#
# Exit Codes: List of exit codes and their meanings
# Usage: ./scripts/script-name.sh [options]

# Exit on any error
set -e

# Source common utilities
source "$(dirname "$0")/common.sh"

# Parse command line arguments
parse_args "$@"

# Print header
print_header "Script Title"
log_info "Starting process at $(date)"

# Setup environment (automatic)
setup_build_env "build_type"
setup_app_directories
load_env_file ".env"

# Execute steps with safe_execute
safe_execute "Step description" "command to execute" || exit 1

# Print footer
print_footer "Script Title"
exit 0

Available Scripts

Test Scripts

  • test-all.sh: Comprehensive test suite (prerequisites, build, web tests, mobile tests)
  • test-mobile.sh: Mobile test suite (Capacitor build, Android tests, iOS tests)
  • test-common.sh: Test script to verify common utilities work correctly
  • test-env.sh: Test script to verify environment variable handling

Build Scripts

  • build-android.sh: Complete Android build process

Development Scripts

  • electron-dev.sh: Electron development workflow

Benefits of Unification

Before (Redundant)

# Each script had 50+ lines of duplicate code:
readonly RED='\033[0;31m'
readonly GREEN='\033[0;32m'
# ... 40+ more lines of duplicate logging functions
log_info "Step 1/4: Doing something..."
if ! measure_time some_command; then
    log_error "Step failed!"
    exit 1
fi
# Manual environment variable setup
export VITE_PLATFORM=electron
export VITE_PWA_ENABLED=false
# ... more manual exports

After (Unified)

# Each script is now ~20 lines of focused logic:
source "$(dirname "$0")/common.sh"
print_header "Script Title"
setup_build_env "electron"  # Automatic environment setup
safe_execute "Step description" "some_command" || exit 1
print_footer "Script Title"

Usage Examples

Running Tests

# Run all tests
./scripts/test-all.sh

# Run mobile tests only
./scripts/test-mobile.sh

# Run with verbose logging
./scripts/test-all.sh --verbose

# Show environment variables
./scripts/test-env.sh --env

Building Applications

# Build Android
./scripts/build-android.sh

# Build Linux package
./scripts/build-electron-linux.sh deb

# Build universal Mac package
./scripts/build-electron-mac.sh universal

# Show environment variables for build
./scripts/build-electron.sh --env

Development Workflows

# Start development
npm run dev

Environment Variable Features

Automatic Setup

All scripts automatically configure the correct environment variables for their build type:

# Capacitor builds automatically get:
export VITE_PLATFORM=capacitor
export VITE_PWA_ENABLED=false
export VITE_DISABLE_PWA=true
export DEBUG_MIGRATIONS=0
export VITE_GIT_HASH=<git-hash>

# Production builds also get:
export NODE_ENV=production

.env File Support

Scripts automatically load variables from .env files if they exist:

# .env file example:
VITE_API_URL=https://api.example.com
VITE_DEBUG=true
CUSTOM_VAR=value

Environment Validation

Required environment variables can be validated:

# In your script
validate_env_vars "VITE_API_URL" "VITE_DEBUG" || exit 1

Environment Inspection

View current environment variables with the --env flag:

./scripts/test-env.sh --env

Error Handling

All scripts use consistent error handling:

  • Exit Codes: Each script documents specific exit codes
  • Safe Execution: safe_execute provides timing and error handling
  • Graceful Failure: Scripts stop on first error with clear messages
  • Logging: All operations are logged with timestamps and colors
  • Environment Validation: Required variables are checked before execution

Testing

To verify the common utilities work correctly:

# Test all common functions
./scripts/test-common.sh

# Test environment variable handling
./scripts/test-env.sh

# Test with verbose logging
./scripts/test-env.sh --verbose

Maintenance

Adding New Scripts

  1. Create new script following the unified pattern
  2. Source common.sh at the top
  3. Use setup_build_env() for environment setup
  4. Use safe_execute for command execution
  5. Document exit codes and usage
  6. Make executable: chmod +x scripts/new-script.sh

Modifying Common Utilities

  1. Update common.sh with new functions
  2. Export new functions with export -f function_name
  3. Update this README if adding new categories
  4. Test with test-common.sh and test-env.sh

Adding New Build Types

  1. Add new case to setup_build_env() function
  2. Define appropriate environment variables
  3. Update this README with new build type
  4. Test with test-env.sh

Security Considerations

  • All scripts use set -e for immediate failure on errors
  • Commands are executed through safe_execute for consistent error handling
  • No direct execution of user input without validation
  • Environment variables are validated when required
  • .env files are loaded safely with proper parsing

Performance

  • Common utilities are sourced once per script execution
  • Timing information is automatically collected for all operations
  • Build artifacts are cleaned up automatically
  • No redundant command execution or file operations
  • Environment variables are set efficiently with minimal overhead