Introduction

gsr is the standard GPSEE Script Runner ("scripting host"). This is a program, built with GPSEE-core, which allows users to run CommonJS programs in the GPSEE environment.

If you are using GPSEE simply to run CommonJS programs as shell scripts, then this the executable you are looking for. If you want a fancy interactive REPL, you might want to look at JSIE, or [gpsee-js].

If you are embedding GPSEE into your own software, gsr may provide an alternative to minimal.c as a starting point, and can serve as a test or evaluation platform.

Recommended Flags

• -dd when debugging your script
• -ddzz when debugging a native module (will cause crashes closer to GC hazards by forcing frequent garbage collection)

Reserved Options and Flags

• -r option is reserved for PageMail's SureLynx RC file library. It specifies an alternate RC file.
• -D option is reserved for PageMail's output redirector. It specifies a file to receive all terminal output.

Command Line Help

 gsr 1.0-pre1 - GPSEE Script Runner for GPSEE 0.2-pre1
 Copyright (c) 2007-2009 PageMail, Inc. All Rights Reserved.
 
 As an interpreter: #! gsr {-/*flags*/}
 As a command:      gsr [-z #] [-n] <[-c code]|[-f filename]>
                        {-/*flags*/} {[--] [arg...]}
 Command Options:
     -c code     Specifies literal JavaScript code to execute
     -f filename Specifies the filename containing code to run
     -F filename Like -f, but skip shebang if present.
     -h          Display this help
     -n          Engine will load and parse, but not run, the script
     flags       A series of one-character flags which can be used
                 in either file interpreter or command mode
     --          Arguments after -- are passed to the script
 
Valid Flags:
     a - Allow (read-only) access to caller's environment
     C - Disables compiler caching via JSScript XDR serialization
     d - Increase verbosity
     e - Do not limit regexps to n^3 levels of backtracking
     J - Disable nanojit
     S - Disable Strict mode
     R - Load RC file for interpreter (gsr) based on
         script filename.
     U - Disable UTF-8 C string processing
     W - Do not report warnings
     x - Parse <!-- comments --> as E4X tokens
 

Sample gsr program

#! /usr/bin/gsr -dd

print("Hello, world!");

Don't forget to give it execute permissions: chmod 755 myprogram.js

Shebang Path & /usr/bin/env

Historically, we have expected a link to your gsr installation in /usr/bin. A fixed location is required to do /usr/bin/env's inability to pass along shebang arguments (i.e. -dd above). An alternate solution, which will allow gsr to be found anywhere along your PATH, allows comment-embedded options. This is outlined in Issue 12.

Pre-compiled Code

By default, all GPSEE programs support pre-compiled JavaScript. What this means is that JavaScript byte code is recorded to disk when it is tokenized for the first time, and loaded on subsequent invocations rather than re-tokenizing.

When GSR is run with the -n option, the pre-compiled JavaScript will be generated even though the script is not executed. You can avoid this side effect with -nC if desired.

Pre-compilation requires that the user running the script have write access to the directory where the script is located. Inability to update to the pre-compiled tokens, due to permission errors or other reasons, will not affect the correct execution of the program.