|
3 days ago | |
---|---|---|
.. | ||
README.md | 1 week ago | |
build-android.sh | 4 days ago | |
build-electron.sh | 3 days ago | |
build-ios.sh | 5 days ago | |
check-android-resources.sh | 4 days ago | |
check-prerequisites.js | 3 months ago | |
common.sh | 3 days ago | |
copy-wasm.js | 1 month ago | |
copy-web-assets.sh | 3 months ago | |
electron-dev.sh | 3 days ago | |
generate-android-icons.sh | 4 days ago | |
generate-icons.sh | 3 months ago | |
openssl_signing_console.sh | 2 months ago | |
run-available-mobile-tests.js | 4 months ago | |
setup-electron.sh | 1 week ago | |
test-all.sh | 2 weeks ago | |
test-android.js | 3 months ago | |
test-common.sh | 2 weeks ago | |
test-env.sh | 1 week ago | |
test-ios.js | 2 months ago | |
test-mobile.sh | 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:
- Sets platform-specific variables based on build type
- Gets git hash for versioning (
VITE_GIT_HASH
) - Creates application directories (
~/.local/share/TimeSafari/timesafari
) - Loads .env file if it exists
- Validates required variables when needed
Environment Functions
setup_build_env(build_type, production)
- Sets environment for specific build typesetup_app_directories()
- Creates necessary application directoriesload_env_file(filename)
- Loads variables from .env fileprint_env_vars(prefix)
- Displays current environment variablesvalidate_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 correctlytest-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
- Create new script following the unified pattern
- Source
common.sh
at the top - Use
setup_build_env()
for environment setup - Use
safe_execute
for command execution - Document exit codes and usage
- Make executable:
chmod +x scripts/new-script.sh
Modifying Common Utilities
- Update
common.sh
with new functions - Export new functions with
export -f function_name
- Update this README if adding new categories
- Test with
test-common.sh
andtest-env.sh
Adding New Build Types
- Add new case to
setup_build_env()
function - Define appropriate environment variables
- Update this README with new build type
- 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