window.markdeepOptions={tocStyle:"medium"} Start


  1.1  Download
    1.1.1  Source
    1.1.2  Fossil
  1.2  Building
    1.2.1  Linux
    1.2.2  Debian
    1.2.3  FreeBSD
    1.2.4  Windows
    1.2.5  Standalone
    1.2.6  Amalgamation
  1.3  Using
    1.3.1  Interactive
    1.3.2  Script
    1.3.3  Inline
  1.4  Help
    1.4.1  Switches
    1.4.2  Modules
  1.5  Apps
  1.6  Shell
  1.7  Autocomplete
  1.8  Editors
    1.8.1  Geany

Javascript Shell Interpreter

Types Builtin Reference  Index  Fossil  Demos Log Test Debug Misc



This page describes getting started with Jsi.



If you don't want to build Jsi from source, limited binaries are available here:



To download the zipped source:

mkdir jsi && cd jsi && wget -O && unzip

Then follow build directions.

Note: it is better to get the source with Fossil.



As Jsi is version-controlled with fossil, the easiest way to keep up to date is by cloning the Jsi repository:

mkdir jsi && cd jsi && fossil clone jsi.fossil && fossil open jsi.fossil

Then follow build directions.

To get fossil:



Jsi is written in C, but can be compiled as either native C, or native C++ (does not use extern C).

On Debian a few packages are required:

sudo apt-get install build-essential bison libreadline-dev libsqlite3-dev libwebsockets-dev libncurses-dev cmake libmysqlclient-dev

Some of these (eg. cmake) are only required for specific configurations.



To build the Linux target there are are two steps:


Do not be surprised to see comiler output from ./configure: it compiles the stripped down shell “jsimin”.

Next, run “make” to build the actual “jsish” executable.


If you want, you can see other available options using:

./configure --help

The directory Configs/, which contains a number of predefined configurations which can be copied to make.conf

The last step is to run the test suite (optional):

make test


If you are on a debian system, you can build then install as a package:

cd tools
sudo dpkg -i jsish-*


On FreeBSD use “gmake” instead of “make” and:

pkg install fetch gmake bison


Jsi can be cross compiled from Linux to Windows using the Mingw32 package:

sudo apt-get install gcc-mingw-w64

The sqlite and libwebsockets source needs to be downloaded and unpacked in "../sqlite” and "../websockets”. This now happens automatically.

Then configure using:

./configure --config=win

Certain features (eg. signals) are disabled in the Windows build. There are also differences in some of the file-system access functions.



The standalone build produces a static binary that contains no external library references. This is useful when you need a standalone executable with no external dependancies.

To create a static image, Jsi uses the Musl library.

The first step is to download Musl and unpack it. Then change to the musl dir and run configure/make, eg:

 ./configure --prefix=$HOME/usr && make install

Ensure that ~/usr/bin is in your path with export PATH=$PATH:$HOME/usr/bin. Then back in the jsi dir do the following:

echo '#define __P(x) x' > ~/usr/include/sys/cdefs.h
echo '#include <miniz zlib.h="">' >  ~/usr/include/zlib.h
cp -pr miniz ~/usr/include/

The sqlite and libwebsockets source needs to be downloaded and unpacked in ../sqlite and ../websockets.

The static jsish can then be built with:

./configure --config=musl


Amalgamated source is the easiest way to incorporate Jsi into an existing application: Here is a simple example:

#include "jsi.c"

int main(int argc, char *argv[])
    Jsi_Interp *interp = Jsi_InterpNew(NULL);
    Jsi_EvalString(interp, "for (var i=1; i<=3; i++)  puts('TEST:',i);", 0);
    Jsi_EvalFile(interp, argv[1], 0);

which we compile with:

gcc  myfile.c -lm -lz -ldl -lpthreads

Another alternative that simplifies debugging Jsi is using jsiOne.c



The following describes a few of the ways to use jsish.

The Jsish package comprises the scripts zipped to the end of the jsish executable that implement command-line option/utilities such as the debugger and parseOpts.



Interactive mode is the easiest way to try out code snippets, eg:

# var a = [1,2,3]; # for (var i in a) { puts(a[i]); } 1 2 3 ...


The script file to be executed is the first argument:

jsish prog.js arg1 arg2

Under unix, the first line of executable scripts can be #!:

#!/usr/bin/env jsish
for (var i in console.args)

The above allows jsish to be found in the path.



Javascript can also be evaluated from the command-line with -e, eg:

jsish -e 'var i = 0; while (i++<10) puts(i);'


To see the supported switches in jsish use -h

jsish -h
usage: jsish -h/--help | -v/--version | -d/--debug | -D/--debugui | -u/--unittest | -U/-UU | -s/--safe | -Z/--zip | -S/--sqliteui | -w/--wget | -W/--websrv | -H/--htmli | -J/--jsi | -C/--cssi | -c/--cdata | -M/--module | -m/--make | -e/--eval | -t/--tracecall | -a/--archive | -T/--typecheck OPT | -IOPT VAL | FILE arg arg ... Use --help for long help.


Available switches in Jsish are:

Options Description
-a/—archive FILE Mount an archive (zip, sqlar or fossil repo) and run module.
-c/—cdata FILE Generate .c or JSON output from a .jsc description.
-C/—cssi FILE Preprocess embedded CSS in .css file.
-d/—debug FILE Run console debugger on script.
-D/—debugui FILE Run web-gui debugger on script.
-e/—eval STRING Evaluate a javascript string and exit.
-h/—help Print help in short or long form.
-H/—htmli FILE Preprocess embedded jsi in .htmli file.
-J/—jsi FILE Preprocess a .jsi file to typecheck in standard javascript.
-m/—module FILE Source file and invoke runModule.
-M/—make FILE Preprocess script as a Jsi Makefile.
-s/—safe FILE Run script in safe sub-interp.
-S/—sqliteui DBFILE Run Sqlite web-gui.
-t/—tracecall Trace all function calls.
-T/—typecheck OPT Enable typechecking.
-u/—unittest FILE Run unit-tests on a script file, or a dir containing .js/.jsi files.
-U/-UU SCRIPT Show output from unit-test mode, omitting pass/fail compare.
-v/—version Print short/long version info and exit.
-Z/—zip Used to append/manage zip files at end of executable.
-w/—wget URL Web client to download file from url.
-W/—websrv FILE Serve out file in web server, with preprocessing.



Help for module commands can similarly be displayed, eg:

jsish -d -h
/zvfs/lib/Jsi_Debug.jsi:34: help: ... A command-line Debugger for Jsi scripts.. Options are: -echoCmd -safe Use --help for long help.

or the long form:

jsish -d --help
/zvfs/lib/Jsi_Debug.jsi:34: help: ... A command-line Debugger for Jsi scripts.. Options are: -echoCmd true // Echo user cmds. -safe false // Debug program in a safe interp (untested) Accepted by all .jsi modules: -Debug, -Trace, -Test

and use as in:

jsish -d -echoCmd true tests/while.js


Jsi is distributed with several demonstration web applications:

These can all be run as standalone applications.



You can use jsish as an enhanced replacement for !/usr/bin/env). This lets you run scripts from the command line with default arguments:

#!/usr/local/bin/jsish -T Debug %s -Trace true myinput1.txt
puts(console.args.join(' '));

(there must be a %s and at least one argument)

From geany you can now run the script with F9, and step through warnings and errors.

This also works for logging messages: mytest2



Autocompletion can be set-up on unix by adding to .bashrc:

complete -W '-h --help -v --version -d --debug -D --debugui -u -unittest -s --safe -Z --zip \
  -S --sqliteui -W --websrv -H --htmli -J --jsi -c --cdata -C --cssi -m --module -e --eval \
  -T --typecheck -t --tracecall' -f '*.jsi'  'jsish'

or running:

make setup.

Next time you login you can use autocompletion with TAB.

This can make running jsish from the command-line a little nicer.





Geany is a convenient editor to use with Jsi. To enable Jsi file completion with Geany:

Geany can also navigate through Jsi's gcc style scripting errors:

formatted by Markdeep 1.03