Shell Design and Engineering Practices (DEPs) serve as the internal "technical law" for Shell projects and operations. They provide standardized requirements and recommendations for the design, construction, and operation of assets to ensure safety, reliability, and cost-efficiency. 🛠️ Core Purpose and Scope DEPs are a comprehensive repository of engineering wisdom gathered from decades of global operations. Safety First : Establishes minimum requirements to prevent accidents and protect the environment. Technical Uniformity : Ensures consistency across different global business units. Efficiency : Reduces rework and provides a clear framework for contractors and vendors. Project Lifecycle : Covers everything from initial process engineering to decommissioning. 📚 Key Categories and Structure The DEPs are categorized by engineering disciplines, often following a specific numbering system (e.g., 31.xx.xx.xx for Mechanical). Shell DEP and MESC Standards Overview | PDF | Valve - Scribd
This guide outlines a comprehensive set of standards and best practices for shell scripting (specifically Bash/Sh) regarding dependencies. The goal is to produce scripts that are portable, robust, and easy to maintain.
Shell Script Dependency Standards 1. Philosophy: Explicit over Implicit A script should never assume the execution environment is pre-configured. Dependencies must be declared, checked, and isolated to ensure the script behaves identically on a fresh machine as it does on a development machine. 2. Declaration and Documentation Dependencies should not be a mystery to the user or the maintainer. File Headers Every script must contain a header block that explicitly lists dependencies.
Language Version: Specify the minimum required shell version (e.g., bash >= 4.0 for associative arrays). External Binaries: List any non-standard command-line tools (e.g., jq , curl , aws-cli ). Environment Variables: Document variables that must be set (e.g., AWS_ACCESS_KEY_ID ). shell dep standards
Example: #!/usr/bin/env bash # # @description: Deploys the application stack. # @dependencies: # - bash >= 4.0 # - jq (commandline JSON processor) # - docker # - curl # @env_vars: # - DEPLOY_ENV (set to 'staging' or 'prod') #
3. Dependency Detection Scripts should fail fast if dependencies are missing. Do not wait until the middle of execution to crash. The command -v Standard Avoid using which for checking dependencies. which is an external binary and may not exist on all minimal systems (e.g., minimal Docker containers). Use the built-in command -v . Standard Pattern: declare -a required_commands=("jq" "curl" "docker") for cmd in "${required_commands[@]}"; do if ! command -v "$cmd" &> /dev/null; then echo "Error: Required dependency '$cmd' is not installed or not in PATH." exit 1 fi done
Version Checking If a script relies on a specific feature (like jq specific flags or git version), check the version number programmatically. # Example: Checking Bash version if [ "${BASH_VERSINFO[0]}" -lt 4 ]; then echo "Error: This script requires Bash version 4.0 or higher." exit 1 fi Shell Design and Engineering Practices (DEPs) serve as
4. Managing External Libraries For complex scripts, avoid writing everything from scratch. Use libraries, but manage them carefully. The "Vendor" Approach (Recommended) Do not rely on the user having a specific shell library (like shunit2 or 严格的bash ) installed globally.
Create a lib/ or vendor/ directory within your project. Copy necessary library scripts into this directory. Commit them to version control.
Sourcing Strategy: # Use absolute paths relative to the script location SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" source "$SCRIPT_DIR/lib/logging.sh" source "$SCRIPT_DIR/lib/validators.sh" Safety First : Establishes minimum requirements to prevent
curl -ing Libraries (Discouraged) Avoid sourcing scripts directly from the internet ( source <(curl url) ). This introduces a runtime network dependency and security risks. If you must download a dependency, do it during a setup phase, verify the checksum, then source it locally. 5. Language Portability Standards To minimize dependencies on specific shell implementations, adhere to these coding standards. Use #!/usr/bin/env bash Use env for the shebang rather than hardcoding /bin/bash .
Why: Systems like macOS, BSD, and various Linux distros place bash in different locations ( /bin/bash , /usr/local/bin/bash , /opt/homebrew/bin/bash ). env searches the $PATH to find the correct interpreter.