After JSUS has been installed, the traditional "hello world" program can be created, using any text editor, as a single line text file:
say("Hello World, I'm baaack . . .\n");
Save this file in the current directory (e.g. as "hello") and then, from the command prompt, run it through the JSUS program:
jsus ./hello
Assuming correct installation (and no typos) this will inevitably result in display of the string "Hello World, I'm baaack . . ." in the terminal display. This "program" consists of a single statement invoking the built-in say() function, one of many extensions to the JavaScript language provided by JSUS. This function simply prints its single string argument on stdout. Other built-in JSUS functions provide access to the most commonly used features of the entire Unix run-time library.
In principle, this is all that is required to create JavaScript programs that run under JSUS in any supported Unix-like operating system. Since every JavaScript "main" program is executed in the global context, there is no need for any "containing" code or return statements (although they may be used, if desired). The full format of the jsus command is as follows:
jsus [-option . . .] program-path [argument . . .]
For this command, the path to the target JavaScript program file should be either absolute or relative to the current working directory (/path/name or ./name or ../name, etc.). Otherwise, it must be the simple file name of a JavaScript program located somewhere along the list of directories in the PATH environment variable. In other words, the program-path must always be specified exactly as it would be at the beginning of a normal command line. The -option arguments are passed only to the JSUS shell, never to the JavaScript program. The target program's argument list is entered after the program-path and is not processed by JSUS.
This is a rather verbose method of executing JavaScript programs, however, and is normally used only during development where it may be necessary to change run-time options passed to JSUS itself (below). More often, JSUS programs are executed directly, by typing the path to the program as an operating system command (optionally followed by the program's own argument list).
All modern versions of Unix allow script files to be executed just like compiled programs, by recognizing the "shebang" characters (#!) at the beginning of the first line as a token or "magic number", followed by the absolute path to the interpreter used to process the rest of the script. JSUS JavaScript programs can be invoked in this way using the following shebang line:
#!/path/to/jsus [ -option . . . ]
There are two problems with this. First, the #! characters are not legal JavaScript code at the beginning of a program. JSUS solves this by replacing #! with // before passing the program to the compiler (effectively converting the first line into a comment). Less easily fixed is the fact that #! must be followed by the absolute path to the JSUS program, which may vary from one system to another. So, when a program is imported from a different system, it must be inspected (and possibly modified) to ensure it will execute correctly on the local system.
Fortunately Linux, at least, offers a more general method of passing "executable" files to interpreters, emulators, virtual machines, etc. The binfmt_misc special file system allows any interpreter to be invoked using a private token or magic number (or even a particular file extension). During a standard installation, the system boot procedure is modified to register //// as the magic number for JSUS. This turns the first program line into a legal comment and eliminates the need for an absolute path to JSUS, making programs more portable. This is called the "four-stroke" token, as an intentional pun on the name of the V8 JavaScript engine (around which JSUS is built).
In addition to the very first line, the four-stroke token may also be used on following lines to identify them as option directives to JSUS and the V8 engine (next). A line beginning with 5 or more strokes is treated as a comment directive by JSUS. These (and lines beginning with 2 or 3 strokes) are treated as ordinary comments by the JavaScript compiler.
Note: For both of these methods the permissions of the source file must be set to "executable", just like any other program file. This is not necessary when executing via the JSUS shell program command, above.
The arguments (options) listed below can be passed to JSUS itself in three different ways. If a shebang line (#!) is used for invocation, the arguments may be included on that line, after the path to JSUS. Or, they may be included on a command line invoking JSUS, as shown above. In this case, command line options override those given in shebang or four-stroke lines at the beginning of the program (the third and most common method, shown below). Using command line options to override in-program options can be useful during program development (for example, the -c option is often used to syntax check the source program).
By design, all contiguous lines at the top of a program beginning with four-stroke tokens are considered to be commands or options to JSUS itself. Lines with five or more strokes are considered to be comments and are ignored. A four-stroke token which is not followed by white space and the dash (-) introducing an option is also treated as a comment. Multiple options may be given on a single line, separated by white space, and these may be followed by comments. The option block is terminated by any line which doesn't begin with four strokes, including an "empty" line. The following example shows all available options (although some make sense only on a JSUS command line).
////////////////////
////
//// Program description comments . . .
////
////////////////////
////
//// -aN
//// Auto-throw if any error above level "N" is
//// detected within JSUS itself (default -a1).
////
//// -c
//// Check syntax only, then exit.
////
//// -d
//// Debug assistance features, turn on.
////
//// -j LIB
//// load() and execute a library file before
//// the program file itself is even compiled.
////
//// -V
//// Print JSUS and engine versions, then exit.
/// This line is not in the option block . . .
/// (We recommend using three strokes for JavaScript
/// comments, to visually differentiate from C/C++).
The LIB part of the -j option must be a simple file name, without any path information. For security, the file must be located in the same directory as the program file itself or one of the system directories /lib/jsus, /usr/lib/jsus or /usr/local/lib/jsus. This option is implemented via the load() function, which searches the same directories, in the same order, but which may be issued at any point in the program.
The JSUS program is normally installed SUID root. This allows some JavaScript programs to run SUID, but ONLY if they are installed within /sbin, /usr/sbin, /bin or /usr/bin AND if they are owned and writable only by root. If not, privileges are dropped before the script is even compiled. Breaching this requires the user already have root access, in which case all bets are off!
Testing JavaScript programs Program execution environment Executing JavaScript libraries