test: support switching godot versions in check.sh

Allows easily testing against a given version of Godot simply by passing
a version to the -a/--api-version parameter and/or the -g/--use-gdvm
parameter.

-a/--api-version is used to specify the Godot API version to use for
building the Rust bindings.

-g/--use-gdvm indicates that the script should use gdvm to match the
Godot version to the API version. It also accepts a version of Godot to
use instead, which allows testing for compatibility between versions of
Godot and the Rust bindings' API version.

Examples:

Test with Godot API version 4.2.1 and the detected version of Godot. If
gdvm is installed, it will use the version of Godot that matches the API
version.

    ./check.sh itest -a 4.2.1

Test with Godot API version 4.2.1 and Godot version 4.3.0.

    ./check.sh itest -g 4.3.0 -a 4.2.1

This commit also adds detection support for gdvm, such that if a user
has gdvm installed, the script will use it as the path to the Godot
executable, unless overridden by the GODOT4_BIN environment variable.
This way it can ensure passing the --console flag to gdvm, useful for
Windows users who otherwise default to the version of Godot that does
not attach to the console. This also enables the version selection
functionality described above.

check.sh

@@ -34,10 +34,16 @@ Commands:
     dok           generate docs and open in browser
 
 Options:
-    -h, --help          print this help text
-    --double            run check with double-precision
-    -f, --filter <arg>  only run integration tests which contain any of the
-                        args (comma-separated). requires itest.
+    -h, --help                 print this help text
+    --double                   run check with double-precision
+    -f, --filter <arg>         only run integration tests which contain any of the
+                               args (comma-separated). requires itest.
+    -a, --api-version <ver>    specify the Godot API version to use (e.g. 4.3.0, 4.3.1).
+                               If gdvm is installed, this will also set the Godot version,
+                               unless -g/--godot-version is specified.
+    -g, --godot-version <ver>  (works only if GODOT4_BIN is not set and gdvm is in
+                               the PATH) if specified, uses gdvm to run Godot with
+                               the specified version.
 
 Examples:
     check.sh fmt clippy
@@ -61,6 +67,21 @@ function log() {
     echo "$@" >&2
 }
 
+# Converts a x.x.x version string to a feature string.
+# e.g. 4.3.0 -> godot/api-4-3, 4.3.1 -> godot/api-4-3-1
+function version_to_feature() {
+    echo "godot/api-$(echo "$1" | sed 's/\./-/g' | sed 's/-0$//')"
+}
+
+# Validates that the given string is a valid x.x.x version string.
+function validate_version_string() {
+    if [[ ! "$1" =~ ^4\.[0-9]+\.[0-9]+$ ]]; then
+        log "Invalid Godot version string '$1'."
+        log "The version string should be in the form 'x.x.x' and the major version should be at least 4."
+        exit 2
+    fi
+}
+
 # Echoes the given command to stderr, then executes it.
 function run() {
     # https://stackoverflow.com/a/76153233/14637
@@ -78,12 +99,34 @@ function findGodot() {
     # $godotBin previously detected.
     if [[ -v godotBin ]]; then
         return
+    fi
+
+    gdvmArgs=()
 
     # User-defined GODOT4_BIN.
-    elif [[ -n "$GODOT4_BIN" ]]; then
+    if [[ -n "$GODOT4_BIN" ]]; then
         log "Using environment variable GODOT4_BIN=$(printf %q "$GODOT4_BIN")"
         godotBin="$GODOT4_BIN"
 
+    # gdvm
+    elif command -v gdvm >/dev/null; then
+        log "Found 'gdvm' executable"
+        godotBin="gdvm"
+        gdvmArgs+=("run")
+
+        # If Godot version is not specified, use the API version if it is specified
+        if [[ -n "$apiVersion" && -z "$gdvmGodotVersion" ]]; then
+            gdvmGodotVersion="$apiVersion"
+
+            echo "Using Godot version that corresponds to API version $apiVersion"
+        fi
+
+        if [[ -n "$gdvmGodotVersion" ]]; then
+            gdvmArgs+=("$gdvmGodotVersion" "--force")
+        fi
+
+        gdvmArgs+=("--console" "--")
+
     # Executable in path.
     elif command -v godot4 >/dev/null; then
         log "Found 'godot4' executable"
@@ -95,7 +138,7 @@ function findGodot() {
         log "Found 'godot4.bat' script"
         godotBin="godot4.bat"
 
-    # This should come last: only use this as a last resort as `godot` may refer to a 
+    # This should come last: only use this as a last resort as `godot` may refer to a
     # Godot 3.x installation.
     elif command -v godot >/dev/null; then
         # Check if `godot` actually is Godot 4.x
@@ -157,7 +200,7 @@ function cmd_test() {
 function cmd_itest() {
     findGodot && \
         run cargo build -p itest "${extraCargoArgs[@]}" && \
-        run "$godotBin" --path itest/godot --headless -- "[${extraArgs[@]}]"
+        run "$godotBin" "${gdvmArgs[@]}" --path itest/godot --headless -- "[${extraArgs[@]}]"
 }
 
 function cmd_doc() {
@@ -176,10 +219,11 @@ function cmd_dok() {
 # `itest` compilations and `check.sh` runs. Note that this means some runs are different from CI.
 extraCargoArgs=("--no-default-features")
 cmds=()
-nextArgIsFilter=false
 extraArgs=()
+apiVersion=""
 
-for arg in "$@"; do
+while [[ $# -gt 0 ]]; do
+    arg="$1"
     case "$arg" in
         -h | --help | help)
             echo "$HELP_TEXT"
@@ -196,22 +240,57 @@ for arg in "$@"; do
             ;;
         -f | --filter)
             if [[ "${cmds[*]}" =~ itest ]]; then
-                nextArgIsFilter=true
+                if [[ -z "$2" ]]; then
+                    log "-f/--filter requires an argument."
+                    exit 2
+                fi
+
+                extraArgs+=("$2")
+                shift
             else
                 log "-f/--filter requires 'itest' to be specified as a command."
                 exit 2
             fi
             ;;
-        *)
-            if $nextArgIsFilter; then
-                extraArgs+=("$arg")
-                nextArgIsFilter=false
-            else
-                log "Unrecognized argument '$arg'. Use '$0 --help' to see what's available."
+        -a | --api-version)
+            if [[ -z "$2" || "$2" == -* ]]; then
+                log "-a/--api-version requires an argument."
                 exit 2
             fi
+
+            apiVersion="$2"
+            validate_version_string "$apiVersion"
+
+            apiFeature=$(version_to_feature "$apiVersion")
+            extraCargoArgs+=("--features" "$apiFeature")
+
+            echo "Using Godot API version $apiVersion with feature $apiFeature"
+            shift
+            ;;
+        -g | --godot-version)
+            if ! command -v gdvm >/dev/null; then
+                log "The -g/--godot-version option requires 'gdvm' to be in the PATH."
+                exit 2
+            elif [[ -n "$GODOT4_BIN" ]]; then
+                log "The -g/--godot-version option cannot be used when GODOT4_BIN is set."
+                exit 2
+            fi
+
+            if [[ -z "$2" || "$2" == -* ]]; then
+                log "-g/--godot-version requires an argument."
+                exit 2
+            fi
+
+            validate_version_string "$2"
+            gdvmGodotVersion="$2"
+            shift
+            ;;
+        *)
+            log "Unrecognized argument '$arg'. Use '$0 --help' to see what's available."
+            exit 2
             ;;
     esac
+    shift
 done
 
 # Default if no commands are explicitly given.