rubyduino 0.1.3 → 0.2.1

data/vendor/spinel/spinel

@@ -8,48 +8,123 @@
 #   spinel app.rb -c -o app.c     - generate C to specific file
 #   spinel app.rb -S               - print C to stdout
 #   spinel -e 'puts 42'            - compile inline source (default name: a)
+#   spinel -E app.rb a b c         - compile to /tmp, run, ARGV=[a, b, c]
 #
 # Options:
 #   -o FILE    Output file (binary or C depending on -c)
 #   -c         Generate C source only, don't compile
 #   -S         Print generated C to stdout
+#   -E         Run the compiled binary instead of saving it; the
+#              first .rb file ends spinel-flag parsing, and the rest
+#              of the command line becomes the binary's ARGV.
 #   -O LEVEL   Optimization level for cc (default: 2)
+#   --debug    Debug build: #line directives + non-inlined methods + -g -O0,
+#              so gdb/lldb step through the original .rb source
+#   -g         Add debug info + #line without forcing -O0
 #   --cc=CMD   C compiler command (default: cc)
 #   -e STR     Inline Ruby source (repeatable; multiple -e join with \n)
 
 DIR="$(cd "$(dirname "$(readlink -f "$0" 2>/dev/null || realpath "$0" 2>/dev/null || echo "$0")")" && pwd)"
 PARSE_BIN="$DIR/spinel_parse"
+ANALYZE_RB="$DIR/spinel_analyze.rb"
+ANALYZE_BIN="$DIR/spinel_analyze"
 CODEGEN_RB="$DIR/spinel_codegen.rb"
 CODEGEN_BIN="$DIR/spinel_codegen"
+RBS_EXTRACT_BIN="$DIR/spinel_rbs_extract"
 
 # On Windows (MSYS2 / Cygwin / MinGW) the compiled binaries carry a .exe
 # suffix; fall back to that when the unsuffixed path is absent.
 case "$(uname -s 2>/dev/null)" in
   MINGW*|MSYS*|CYGWIN*)
-    [ ! -x "$PARSE_BIN"   ] && [ -x "$PARSE_BIN.exe"   ] && PARSE_BIN="$PARSE_BIN.exe"
-    [ ! -x "$CODEGEN_BIN" ] && [ -x "$CODEGEN_BIN.exe" ] && CODEGEN_BIN="$CODEGEN_BIN.exe"
+    [ ! -x "$PARSE_BIN"       ] && [ -x "$PARSE_BIN.exe"       ] && PARSE_BIN="$PARSE_BIN.exe"
+    [ ! -x "$ANALYZE_BIN"     ] && [ -x "$ANALYZE_BIN.exe"     ] && ANALYZE_BIN="$ANALYZE_BIN.exe"
+    [ ! -x "$CODEGEN_BIN"     ] && [ -x "$CODEGEN_BIN.exe"     ] && CODEGEN_BIN="$CODEGEN_BIN.exe"
+    [ ! -x "$RBS_EXTRACT_BIN" ] && [ -x "$RBS_EXTRACT_BIN.exe" ] && RBS_EXTRACT_BIN="$RBS_EXTRACT_BIN.exe"
     ;;
 esac
 
 SOURCE=""
 OUTPUT=""
 C_ONLY=0
+EMIT_RBS=0
+EMIT_TYPES=0
+EMIT_SYMBOL_MAP=0
 STDOUT_MODE=0
+RUN_MODE=0
+# #line directives are on by default: they cost nothing at runtime (purely a
+# diagnostic directive; the binary is identical modulo line attribution) and
+# let the C toolchain report any compile error on the generated C against the
+# Ruby source line. Opt out with --no-line-map.
+LINE_MAP=1
 OPT_LEVEL="2"
 CC_CMD="cc"
 EXTRA_FLAGS=""
+DEBUG=0
 C_TMP=""
+C_TMP_DIR=""
+RUN_TMP_DIR=""
 EVAL_SCRIPT=""
 EVAL_USED=0
 EVAL_TMP=""
+RBS_DIR=""
+SEED_TMP=""
+INT_OVERFLOW="raise"
 
+# Parse spinel-side flags. In `-E` (run) mode, the first positional
+# `.rb` arg marks the boundary between spinel flags and the script's
+# ARGV: everything after that point is passed straight to the
+# compiled binary. The same boundary trip fires on the first
+# unrecognized token in run mode so `spinel -E -e '...' arg1 arg2`
+# also hands the trailing positionals through.
 while [ $# -gt 0 ]; do
   case "$1" in
-    --source=*) SOURCE="${1#--source=}" ;;
-    --output=*) OUTPUT="${1#--output=}" ;;
-    --cc=*)     CC_CMD="${1#--cc=}" ;;
-    -o)         shift; OUTPUT="$1" ;;
-    -O)         shift; OPT_LEVEL="$1" ;;
+    --source=*) SOURCE="${1#--source=}"; shift ;;
+    --output=*) OUTPUT="${1#--output=}"; shift ;;
+    --cc=*)     CC_CMD="${1#--cc=}"; shift ;;
+    --rbs=*)    RBS_DIR="${1#--rbs=}"; shift ;;
+    --rbs)      shift; RBS_DIR="$1"; shift ;;
+    --int-overflow=*) INT_OVERFLOW="${1#--int-overflow=}"; shift ;;
+    --int-overflow)   shift; INT_OVERFLOW="$1"; shift ;;
+    --)         # `--` ends spinel-flag parsing (issue #835).
+                # In -E (run) mode the remaining args become ARGV
+                # for the compiled binary; in compile mode the next
+                # token is treated as the source path (matching ruby).
+                shift
+                if [ "$RUN_MODE" -eq 1 ]; then
+                  if [ -z "$SOURCE" ] && [ $# -gt 0 ]; then
+                    SOURCE="$1"
+                    shift
+                  fi
+                  break
+                fi
+                if [ -z "$SOURCE" ] && [ $# -gt 0 ]; then
+                  SOURCE="$1"
+                  shift
+                fi
+                # Anything left after the source is ignored in
+                # compile-only mode (matches ruby's behaviour where
+                # trailing args become ARGV — but spinel doesn't run
+                # the program here).
+                break
+                ;;
+    -o)         shift; OUTPUT="$1"; shift ;;
+    -O)         shift; OPT_LEVEL="$1"; shift ;;
+    --debug)    # Debug build: native-debugger stepping through Ruby.
+                # Emits #line directives + keeps methods non-inlined
+                # (SPINEL_DEBUG=1), forces -O0 and adds -g.
+                DEBUG=1; OPT_LEVEL="0"; shift ;;
+    -g)         # Debug info + #line, but leave -O as-is (a -g build at
+                # the default -O2 gives lossy DWARF; use --debug for
+                # faithful stepping).
+                DEBUG=1; shift ;;
+    --line-map) # Emit `#line` directives so a compile error on the
+                # generated C is reported against the Ruby source line,
+                # without --debug's -O0 / non-inlined / -g cost. On by
+                # default; this flag is kept for explicitness.
+                LINE_MAP=1; shift ;;
+    --no-line-map) # Suppress #line directives (smaller generated C; compile
+                # errors report against out.c instead of the Ruby source).
+                LINE_MAP=0; shift ;;
     -e)         shift
                 if [ "$EVAL_USED" -eq 0 ]; then
                   EVAL_SCRIPT="$1"
@@ -57,21 +132,101 @@ while [ $# -gt 0 ]; do
                   EVAL_SCRIPT="$EVAL_SCRIPT
 $1"
                 fi
-                EVAL_USED=1 ;;
-    -c)         C_ONLY=1 ;;
-    -S)         STDOUT_MODE=1 ;;
-    *.rb)       [ -z "$SOURCE" ] && SOURCE="$1" ;;
+                EVAL_USED=1
+                shift ;;
+    -c)         C_ONLY=1; shift ;;
+    --emit-rbs) # Analyze-only: dump inferred signatures as RBS, no binary.
+                EMIT_RBS=1; shift ;;
+    --emit-types) # Analyze-only: dump per-position inferred types + degrade
+                  # diagnostics as JSON (for the ruby-lsp addon). Needs node
+                  # positions, so it turns on SPINEL_DEBUG below.
+                EMIT_TYPES=1; DEBUG=1; shift ;;
+    --emit-symbol-map) # Dump emitted-symbol -> Ruby-name map as JSON (#1334).
+                  # Runs codegen (the mangling lives there) but writes no
+                  # binary. DEBUG on so node positions (file/line) are stamped.
+                EMIT_SYMBOL_MAP=1; DEBUG=1; shift ;;
+    -S)         STDOUT_MODE=1; shift ;;
+    -E)         RUN_MODE=1; shift ;;
+    *.rb)
+                if [ -z "$SOURCE" ]; then
+                  SOURCE="$1"
+                  shift
+                  [ "$RUN_MODE" -eq 1 ] && break
+                else
+                  shift
+                fi
+                ;;
+    *)
+                if [ "$RUN_MODE" -eq 1 ]; then
+                  break
+                fi
+                shift
+                ;;
   esac
-  shift
 done
 
+# Mode-conflict checks: `-E` short-circuits to "run the produced
+# binary" so output-saving flags (`-o`, `-c`, `-S`) don't make sense
+# alongside it.
+if [ "$RUN_MODE" -eq 1 ]; then
+  if [ -n "$OUTPUT" ]; then
+    echo "spinel: -E (run) cannot be combined with -o" >&2
+    exit 2
+  fi
+  if [ "$C_ONLY" -eq 1 ]; then
+    echo "spinel: -E (run) cannot be combined with -c" >&2
+    exit 2
+  fi
+  if [ "$STDOUT_MODE" -eq 1 ]; then
+    echo "spinel: -E (run) cannot be combined with -S" >&2
+    exit 2
+  fi
+fi
+
+# --emit-rbs is analyze-only (stops before codegen), so the binary/C-output
+# modes would be silently ignored alongside it — reject the conflict up front.
+if [ "$EMIT_RBS" -eq 1 ]; then
+  if [ "$RUN_MODE" -eq 1 ]; then
+    echo "spinel: --emit-rbs cannot be combined with -E (run)" >&2
+    exit 2
+  fi
+  if [ "$C_ONLY" -eq 1 ]; then
+    echo "spinel: --emit-rbs cannot be combined with -c (C source only)" >&2
+    exit 2
+  fi
+  if [ "$STDOUT_MODE" -eq 1 ]; then
+    echo "spinel: --emit-rbs cannot be combined with -S (stdout)" >&2
+    exit 2
+  fi
+fi
+
+# --emit-types is likewise analyze-only — reject the binary/C-output modes.
+if [ "$EMIT_TYPES" -eq 1 ]; then
+  if [ "$RUN_MODE" -eq 1 ]; then
+    echo "spinel: --emit-types cannot be combined with -E (run)" >&2
+    exit 2
+  fi
+  if [ "$C_ONLY" -eq 1 ]; then
+    echo "spinel: --emit-types cannot be combined with -c (C source only)" >&2
+    exit 2
+  fi
+  if [ "$STDOUT_MODE" -eq 1 ]; then
+    echo "spinel: --emit-types cannot be combined with -S (stdout)" >&2
+    exit 2
+  fi
+fi
+
 # `-e` mode: write the accumulated inline script to a temp file and
 # treat it as the source. Default output name is `a` since the
 # inline form has no .rb basename to derive from. If both -e and a
 # .rb file were given, -e wins (consistent with `ruby -e ... script.rb`
 # where the .rb file becomes ARGV — Spinel only consumes the source).
 if [ "$EVAL_USED" -eq 1 ]; then
-  EVAL_TMP="$(mktemp /tmp/spinel_eval.XXXXXX).rb"
+  # Issue #794: mktemp creates the file; appending .rb to the variable
+  # leaves the original (no-.rb) file leaked. Use -u to skip file
+  # creation, then create the .rb directly via the redirect.
+  EVAL_BASE="$(mktemp -u /tmp/spinel_eval.XXXXXX)"
+  EVAL_TMP="${EVAL_BASE}.rb"
   printf '%s\n' "$EVAL_SCRIPT" > "$EVAL_TMP"
   SOURCE="$EVAL_TMP"
 fi
@@ -84,14 +239,28 @@ if [ -z "$SOURCE" ]; then
   echo "       spinel app.rb -c           - generate app.c only" >&2
   echo "       spinel app.rb -S           - print C to stdout" >&2
   echo "       spinel -e 'puts 42'        - compile inline source" >&2
+  echo "       spinel -E app.rb a b c     - compile + run with ARGV=[a, b, c]" >&2
   echo "" >&2
   echo "Options:" >&2
   echo "  -o FILE     Output file" >&2
   echo "  -c          C source only (don't compile)" >&2
+  echo "  --emit-rbs  Dump inferred type signatures as RBS (-> app.rbs), no binary" >&2
+  echo "  --emit-types Dump per-position inferred types + degrade diagnostics as JSON" >&2
   echo "  -S          Print C to stdout" >&2
+  echo "  -E          Run the compiled binary; leftover args become its ARGV" >&2
   echo "  -O LEVEL    Optimization level (default: 2)" >&2
+  echo "  --debug     Debug build: step through the .rb in gdb/lldb" >&2
+  echo "              (emits #line, keeps methods non-inlined, -g -O0)" >&2
+  echo "  -g          Add debug info + #line without forcing -O0" >&2
+  echo "  --no-line-map  Suppress #line directives (smaller C; compile errors" >&2
+  echo "              report against generated C, not the Ruby source)" >&2
   echo "  --cc=CMD    C compiler (default: cc)" >&2
   echo "  -e STR      Inline Ruby source (repeatable; joined with newlines)" >&2
+  echo "  --rbs DIR   Seed analyzer with RBS signatures from DIR (advisory)" >&2
+  echo "  --int-overflow=MODE  Int +/-/* overflow handling (default: raise)" >&2
+  echo "              raise   raise RangeError on overflow (CRuby-incompatible but safe)" >&2
+  echo "              wrap    silent two's-complement wrap (fastest, no check)" >&2
+  echo "              promote escalate to arbitrary-precision Integer (CRuby-compatible)" >&2
   exit 1
 fi
 
@@ -106,7 +275,32 @@ else
   BASENAME="$(basename "$SOURCE" .rb)"
 fi
 AST_TMP="$(mktemp /tmp/spinel_ast.XXXXXX)"
-trap 'rm -f "$AST_TMP" "$C_TMP" "$EVAL_TMP"' EXIT
+IR_TMP="$(mktemp /tmp/spinel_ir.XXXXXX)"
+trap 'rm -f "$AST_TMP" "$IR_TMP" "$EVAL_TMP" "$SEED_TMP"; [ -n "$C_TMP_DIR" ] && rm -rf "$C_TMP_DIR"; [ -n "$RUN_TMP_DIR" ] && rm -rf "$RUN_TMP_DIR"' EXIT
+
+# Debug mode signal, read by the parser (per-node line stamps) and the
+# codegen (#line emission + non-inlined methods). Must be exported
+# before the parse step below since spinel_parse reads it at init.
+# --line-map: stamp #line directives (parser + codegen) for Ruby-mapped
+# compile errors, but keep the normal optimized build (no -O0/-g/-rdynamic).
+# --debug implies it; SPINEL_DEBUG already turns on the same #line path.
+if [ "$LINE_MAP" -eq 1 ] && [ "$DEBUG" -eq 0 ]; then
+  export SPINEL_LINE_MAP=1
+fi
+if [ "$DEBUG" -eq 1 ]; then
+  export SPINEL_DEBUG=1
+  EXTRA_FLAGS="$EXTRA_FLAGS -g"
+  # Native Exception#backtrace on Linux: glibc's backtrace_symbols only
+  # resolves frames whose symbols are in the dynamic symbol table. Debug
+  # builds emit user methods with external linkage; -rdynamic exports them
+  # so backtrace_symbols can name them. macOS resolves via the Mach-O symbol
+  # table already; Windows has no backtrace (SP_BT_AVAILABLE=0) and -rdynamic
+  # is ELF-only — so it's a Linux/BSD-only flag (skip Darwin *and* MinGW/Cygwin).
+  case "$(uname -s 2>/dev/null)" in
+    Darwin|MINGW*|MSYS*|CYGWIN*) ;;
+    *) EXTRA_FLAGS="$EXTRA_FLAGS -rdynamic" ;;
+  esac
+fi
 
 # Step 1: Parse. spinel_parse is C-only; build it via `make parse`
 # (or `make all`) before invoking spinel.
@@ -120,12 +314,92 @@ if [ $? -ne 0 ]; then
   exit 1
 fi
 
-# Step 2: Codegen
+# Optional RBS seed extraction. spinel_rbs_extract walks the given
+# dir for *.rbs files and emits seed lines on stdout that the
+# analyzer consumes via ARGV[2]. Per the design note, the seeded
+# types are *advisory* -- inference still widens on observed
+# disagreement -- so this is safe even when the RBS files contradict
+# the implementation.
+#
+# `--rbs DIR` is a silent no-op when DIR is absent or empty, or when
+# the extractor binary hasn't been built: spinel still compiles, just
+# without seeds. Real failures during extraction warn to stderr.
+if [ -n "$RBS_DIR" ] && [ -x "$RBS_EXTRACT_BIN" ] && [ -d "$RBS_DIR" ]; then
+  SEED_TMP="$(mktemp /tmp/spinel_seed.XXXXXX)"
+  if ! "$RBS_EXTRACT_BIN" "$RBS_DIR" > "$SEED_TMP"; then
+    echo "spinel: --rbs extraction failed; proceeding without seeds" >&2
+    rm -f "$SEED_TMP"
+    SEED_TMP=""
+  elif [ ! -s "$SEED_TMP" ]; then
+    rm -f "$SEED_TMP"
+    SEED_TMP=""
+  fi
+fi
+
+# Step 2: Analyze (whole-program type inference; emits .ir).
+# Export the int-overflow mode so analyze / codegen can rewrite all
+# int locals as bigint when mode == promote. Raise / wrap modes
+# only care about the cc-time preprocessor switch added below.
+export SPINEL_INT_OVERFLOW="$INT_OVERFLOW"
+# RBS export mode: tell the analyzer to also dump inferred signatures.
+# (Conflicting-mode checks are done up front with the other mode-conflict guards.)
+if [ "$EMIT_RBS" -eq 1 ]; then
+  RBS_OUT="${OUTPUT:-$BASENAME.rbs}"
+  export SPINEL_EMIT_RBS="$RBS_OUT"
+fi
+if [ "$EMIT_TYPES" -eq 1 ]; then
+  TYPES_OUT="${OUTPUT:-$BASENAME.types.json}"
+  export SPINEL_EMIT_TYPES="$TYPES_OUT"
+fi
+if [ -x "$ANALYZE_BIN" ]; then
+  "$ANALYZE_BIN" "$AST_TMP" "$IR_TMP" $SEED_TMP
+else
+  ruby "$ANALYZE_RB" "$AST_TMP" "$IR_TMP" $SEED_TMP
+fi
+if [ $? -ne 0 ]; then
+  echo "spinel: analyze failed" >&2
+  exit 1
+fi
+
+# --emit-rbs / --emit-types are analyze-only: the artifact is written by the
+# analyzer; stop before codegen.
+if [ "$EMIT_RBS" -eq 1 ]; then
+  echo "Wrote $RBS_OUT" >&2
+  exit 0
+fi
+if [ "$EMIT_TYPES" -eq 1 ]; then
+  echo "Wrote $TYPES_OUT" >&2
+  exit 0
+fi
+
+# --emit-symbol-map needs codegen (the C name-mangling lives there) but emits
+# no binary: run codegen with SPINEL_EMIT_SYMBOL_MAP set, route the C output
+# to a temp, and stop.
+if [ "$EMIT_SYMBOL_MAP" -eq 1 ]; then
+  SYM_OUT="${OUTPUT:-$BASENAME.symbols.json}"
+  export SPINEL_EMIT_SYMBOL_MAP="$SYM_OUT"
+  SYM_C_TMP="$(mktemp /tmp/spinel_symc.XXXXXX)"
+  if [ -x "$CODEGEN_BIN" ]; then
+    "$CODEGEN_BIN" "$AST_TMP" "$IR_TMP" "$SYM_C_TMP"
+  else
+    ruby "$CODEGEN_RB" "$AST_TMP" "$IR_TMP" "$SYM_C_TMP"
+  fi
+  cg_rc=$?
+  rm -f "$SYM_C_TMP"
+  if [ $cg_rc -ne 0 ]; then
+    echo "spinel: codegen failed" >&2
+    exit 1
+  fi
+  echo "Wrote $SYM_OUT" >&2
+  exit 0
+fi
+
+# Step 3: Codegen
 if [ $STDOUT_MODE -eq 1 ]; then
   if [ -x "$CODEGEN_BIN" ]; then
-    "$CODEGEN_BIN" "$AST_TMP"
+    "$CODEGEN_BIN" "$AST_TMP" "$IR_TMP"
   else
-    ruby "$CODEGEN_RB" "$AST_TMP"
+    ruby "$CODEGEN_RB" "$AST_TMP" "$IR_TMP"
   fi
   exit $?
 fi
@@ -133,14 +407,15 @@ fi
 if [ $C_ONLY -eq 1 ]; then
   C_FILE="${OUTPUT:-$BASENAME.c}"
 else
-  C_TMP="$(mktemp /tmp/spinel_out.XXXXXX.c)"
+  C_TMP_DIR="$(mktemp -d /tmp/spinel_out.XXXXXX)" || { echo "spinel: mktemp -d failed" >&2; exit 1; }
+  C_TMP="$C_TMP_DIR/out.c"
   C_FILE="$C_TMP"
 fi
 
 if [ -x "$CODEGEN_BIN" ]; then
-  "$CODEGEN_BIN" "$AST_TMP" "$C_FILE"
+  "$CODEGEN_BIN" "$AST_TMP" "$IR_TMP" "$C_FILE"
 else
-  ruby "$CODEGEN_RB" "$AST_TMP" "$C_FILE"
+  ruby "$CODEGEN_RB" "$AST_TMP" "$IR_TMP" "$C_FILE"
 fi
 if [ $? -ne 0 ]; then
   echo "spinel: codegen failed" >&2
@@ -153,7 +428,15 @@ if [ $C_ONLY -eq 1 ]; then
 fi
 
 # Step 3: Compile C -> binary
-BIN_FILE="${OUTPUT:-$BASENAME}"
+# In -E (run) mode the binary is short-lived: drop it into a fresh
+# temp dir so the cwd stays clean and the trap reaps the file when
+# the script exits (including via signal).
+if [ "$RUN_MODE" -eq 1 ]; then
+  RUN_TMP_DIR="$(mktemp -d /tmp/spinel_run.XXXXXX)" || { echo "spinel: mktemp -d failed" >&2; exit 1; }
+  BIN_FILE="$RUN_TMP_DIR/$BASENAME"
+else
+  BIN_FILE="${OUTPUT:-$BASENAME}"
+fi
 # Runtime library (bigint + regexp)
 SP_RT_LIB="$DIR/lib/libspinel_rt.a"
 INCLUDE_FLAGS="-I$DIR/lib"
@@ -182,10 +465,25 @@ case "$(uname -s 2>/dev/null)" in
   MINGW*|MSYS*|CYGWIN*) EXTRA_FLAGS="$EXTRA_FLAGS -Wl,--stack,67108864" ;;
 esac
 
+case "$INT_OVERFLOW" in
+  raise)   EXTRA_FLAGS="$EXTRA_FLAGS -DSP_INT_OVERFLOW_MODE_RAISE" ;;
+  wrap)    EXTRA_FLAGS="$EXTRA_FLAGS -DSP_INT_OVERFLOW_MODE_WRAP" ;;
+  promote) EXTRA_FLAGS="$EXTRA_FLAGS -DSP_INT_OVERFLOW_MODE_PROMOTE" ;;
+  *) echo "spinel: --int-overflow expects raise|wrap|promote, got '$INT_OVERFLOW'" >&2; exit 2 ;;
+esac
 $CC_CMD -O${OPT_LEVEL} -Wno-all -ffunction-sections -fdata-sections $INCLUDE_FLAGS $FFI_CFLAGS "$C_FILE" -lm $EXTRA_FLAGS $FFI_LINKS $GC_FLAG -o "$BIN_FILE"
 if [ $? -ne 0 ]; then
   echo "spinel: C compilation failed" >&2
   exit 1
 fi
 
+if [ "$RUN_MODE" -eq 1 ]; then
+ # Hand off to the freshly compiled binary, forwarding the
+ # leftover positionals as its ARGV. Run as a subprocess (not
+ # exec) so the EXIT trap reaps RUN_TMP_DIR after the child
+ # returns. Propagate the child's exit code.
+  "$BIN_FILE" "$@"
+  exit $?
+fi
+
 echo "$SOURCE -> $BIN_FILE" >&2