How to define a shell script to be sourced not run

Question

I am defining a shell script which a user should source rather than execute.

Is there a conventional or intelligent way to hint to the user that this is the case, for instance via a file extension?

Is there shell code I can write in the file itself, which will cause it to echo a message and quit if it is executed instead of sourced, so that I can help the user avoid this obvious mistake?

Answer 1

Assuming that you are running bash, put the following code near the start of the script that you want to be sourced but not executed:

if [ "${BASH_SOURCE[0]}" -ef "$0" ]
then
    echo "Hey, you should source this script, not execute it!"
    exit 1
fi

Under bash, ${BASH_SOURCE[0]} will contain the name of the current file that the shell is reading regardless of whether it is being sourced or executed.

By contrast, $0 is the name of the current file being executed.

-ef tests if these two files are the same file. If they are, we alert the user and exit.

Neither -ef nor BASH_SOURCE are POSIX. While -ef is supported by ksh, yash, zsh and Dash, BASH_SOURCE requires bash. In zsh, however, ${BASH_SOURCE[0]} could be replaced by ${(%):-%N}.

Answer 2

A non-executable file can be sourced but not executed, so, as a first line of defense, not setting the executable flag should be a good hint...

Edit: trick I just stumbled on: make the shebang be any executable that isn't a shell interpreter, /bin/false makes the script return an error (rc!=0)

#!/bin/false "This script should be sourced in a shell, not executed directly"

Answer 3

There are several methods suggested in this Stack Overflow post, of which, I liked the function-based one suggested by Wirawan Purwanto and mr.spuratic best:

The most robust way, as suggested by Wirawan Purwanto, is to check FUNCNAME[1] within a function:

function mycheck() { declare -p FUNCNAME; }
mycheck

Then:

$ bash sourcetest.sh
declare -a FUNCNAME='([0]="mycheck" [1]="main")'
$ . sourcetest.sh
declare -a FUNCNAME='([0]="mycheck" [1]="source")'

This is the equivalent to checking the output of caller, the values main and source distinguish the caller's context. Using FUNCNAME[] saves you capturing and parsing caller output. You need to know or calculate your local call depth to be correct though. Cases like a script being sourced from within another function or script will cause the array (stack) to be deeper. (FUNCNAME is a special bash array variable, it should have contiguous indexes corresponding to the call stack, as long as it is never unset.)

So you can add to the start of the script:

function check()
{
    if [[ ${FUNCNAME[-1]} != "source" ]]   # bash 4.2+, use ${FUNCNAME[@]: -1} for older
    then
        printf "Usage: source %s\n" "$0"
        exit 1
    fi
}
check

Answer 4

When you source a shell script, the shebang line is ignored. By putting in an invalid shebang, you can alert the user that the script was erroneously executed:

#!/bin/bash source-this-script
# ...

The error message will be this:

/bin/bash: source-this-script: No such file or directory

The (arbitrary) argument name already provides a strong hint, but the error message still isn't 100% clear. We can fix this with a utility script source-this-script that is placed somewhere in your PATH:

#!/bin/sh
echo >&2 "This script must be sourced, not executed${1:+: }${1:-!}"
exit 1

Now, the error message will be this:

This script must be sourced, not executed: path/to/script.sh

Comparison to other approaches

Compared to the other answers, this approach only requires minimal changes to each script (and having a shebang line helps with file type detection in editors and specifies the shell script dialect, so there are even benefits). The downside is a somewhat unclear error message, or the (one-time) addition of another shell script.

It does not prevent explicit invocation via bash path/to/script.sh, though (thanks @muru!).

Answer 5

Assuming it is just useless, rather than harmful, to execute the script, you can add

return 0 || printf 'Must be sourced, not executed\n' >&2

to the end of the script. return outside of a function has a non-zero exit code unless the file is being sourced.

Answer 6

Here are 4 techniques I've compiled. You can programmatically decide what to do if the script is being executed versus sourced.

From check_if_sourced_or_executed.sh in my eRCaGuy_hello_world repo:

#!/usr/bin/env bash

main() {
    echo "Running main function."

    # put your code here

    echo -e "\nTOTAL TIME TO RUN main func:"
}

# Set the global variable `run` to "true" if the script is being executed and `main` should run, and
# set `run` to "false" otherwise--ex: if the script is being sourced in order to import functions
# from the script, but `main` should NOT run.
run_check() {
    # DEMONSTRATE A FEW DIFFERENT TECHNIQUES

    echo "Technique 1 (can be placed anywhere):"
    echo "  See: https://unix.stackexchange.com/a/424495/114401"
    if [ "${BASH_SOURCE[0]}" -ef "$0" ]; then
        echo "  This script is being EXECUTED."
        run="true"
    else
        echo "  This script is being SOURCED."
    fi


    echo "Technique 2 [MY 2ND FAVORITE] (can be placed anywhere):"
    echo "  Modified from: https://stackoverflow.com/a/29967433/4561887"
    if [ "${BASH_SOURCE[0]}" == "$0" ]; then
        echo "  This script is being EXECUTED."
        run="true"
    else
        echo "  This script is being SOURCED."
    fi

    echo "Technique 3 (requires another line which MUST be **outside** all functions):"
    echo "  Modified from: https://stackoverflow.com/a/28776166/4561887"
    if [ "$script_is_being_executed" == "true" ]; then
        echo "  This script is being EXECUTED."
        run="true"
    else
        echo "  This script is being SOURCED."
    fi


    echo "Technique 4 [MY 1ST FAVORITE] (MUST be **inside** a function):"
    echo "  Modified from: https://stackoverflow.com/a/14706745/4561887"
    echo "  and https://unix.stackexchange.com/a/424552/114401"
    if [ "${FUNCNAME[-1]}" == "main" ]; then
        echo "  This script is being EXECUTED."
        run="true"
    elif [ "${FUNCNAME[-1]}" == "source" ]; then
        echo "  This script is being SOURCED."
    else
        echo "  ERROR: THIS TECHNIQUE IS BROKEN"
    fi

}

# ==================================================================================================
# Main program entry point
# ==================================================================================================

# Only run main function if this file is being executed, NOT sourced.

# For Technique 3. This `return` statement MUST be called at a top-level scope, outside of all
# functions, in order to work! See their detailed explanation here for how it works:
# https://stackoverflow.com/a/28776166/4561887
(return 0 2>/dev/null) && script_is_being_executed="false" || script_is_being_executed="true"

run="false"
run_check
if [ "$run" == "true" ]; then
    time main "$@"
fi

Test run commands:

# 1. Execute the script in 2 ways:
#   A. As an executable script
./bash/check_if_sourced_or_executed.sh
#   B. By calling the bash interpreter
bash ./bash/check_if_sourced_or_executed.sh

# 2. Source the script in 2 ways:
#   A. Bash source call
source ./bash/check_if_sourced_or_executed.sh
#   B. (Recommended) POSIX-compliant source call
. ./bash/check_if_sourced_or_executed.sh

See also where I described the 4 techniques on Stack Overflow here: https://stackoverflow.com/questions/2683279/how-to-detect-if-a-script-is-being-sourced/70662049#70662049