/ Download

Following is an overview of getting, installing, building and using Jsi.


Note: you can download a static binaries here.


To download the zipped source:

mkdir jsi
cd jsi
wget http://jsish.org/jsi/zip -O jsish.zip
unzip jsish.zip

Then follow build directions.


A better way uses fossil, to simplify keeping up to date:

mkdir jsi
cd jsi
fossil clone https://jsish.org/jsi jsi.fossil
fossil open jsi.fossil

If you don't have fossil:


Jsi requires a few packages to build, eg. on Debian:

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

Note: Packages such as cmake are required only 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.


Note: during the build sqlite and libwebsockets will be downloaded.

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

make test

If you want to see other available options try:

./configure --help

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


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

cd tools
sudo dpkg -i jsish-*


On FreeBSD you will need to use gmake instead of make:

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

Then configure using:

./configure --config=win

Warning: Features such as signals are disabled in the Windows build. As you would expect, there are also obvious differences in the file-system.


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 download/unpack Musl then do:

 ./configure --prefix=$HOME/usr
 make install
 export PATH=$PATH:$HOME/usr/bin

Next, a few files need to be fixed up:

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

Finally cd back to the jsi dir and:

./configure --config=musl


Amalgamated source with jsi.c is the easiest way to incorporate Jsi into an existing application, eg:

#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);
    if (argc>1)
        Jsi_EvalFile(interp, Jsi_ValueNewStringDup(interp, argv[1]), 0);

Then compile with:

gcc  myfile.c -o myfile -lm -lz -ldl -lpthread

More extensive examples are in c-demos.

In particular minimal.c, used to create minimalsh that handles Jsi arguments then returns control to application:

$ make -C c-demos minimalsh
$ c-demos/minimalsh -v


2.8.12 2.081 6b18cee9a7a458d892df9f9b05b7558e23539948 2019-03-31 20:50:48 UTC

Note: Jsi is written in C, and can be compiled as either native C, or native C++: it does not use extern 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:



Jsish interactive: see 'help [cmd]'.  \ cancels > input.  ctrl-c aborts running script.
# var a = [1,2,3];
# for (var i in a) { puts(a[i]); }
# help require
require(name:string=void, version:number|string=1):number|array|object
Load/query packages.
With no arguments, returns the list of all loaded packages.
With one argument, loads the package (if necessary) and returns its version.
With two arguments, returns object containing: version, loadFile, func.
An error is thrown if requested version is greater than actual version.
# for (i=
> \
abandoned input# 
# 9+12;
# ^C


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 final value, add a return:

jsish -e 'var i = 0; i++; return i;'


To see the supported switches in jsish use -h

jsish -h

  --F           Trace all function calls/returns.
  --I OPT:VAL   Interp option: equivalent to Interp.conf({OPT:VAL}).
  --T OPT       Typecheck option: equivalent to "use OPT".
  --U           Display unittest output, minus pass/fail compare.
  --V           Same as --U, but adds file and line number to output.

  -a            Archive: mount an archive (zip, sqlar or fossil repo) and run module.
  -c            CData: generate .c or JSON output from a .jsc description.
  -d            Debug: console script debugger.
  -e STRING     Eval: run javascript in STRING and exit.
  -g            Gendeep: generate html output from markdeep source.
  -h            Help: show this help.
  -m MOD        Module: invoke runModule, after source if file.
  -s            Safe: runs script in safe sub-interp.
  -u            UnitTest: test script file(s) or directories .js/.jsi files.
  -w            Wget: web client to download file from url.
  -v            Version: show version info.
  -z            Zip: append/manage zip files at end of executable.
  -D            DebugUI: web-gui script debugger.
  -S            SqliteUI: web-gui for sqlite database file.
  -W            Websrv: web server to serve out content.

Interp options may also be set via the environment eg. JSI_INTERP_OPTS='{coverage:true}'

You can also get help for commands from the command-line:

jsish -help require


require(name:string=void, version:number|string=1):number|array|object
Load/query packages.
With no arguments, returns the list of all loaded packages.
With one argument, loads the package (if necessary) and returns its version.
With two arguments, returns object containing: version, loadFile, func.
An error is thrown if requested version is greater than actual version.


Help for module commands can similarly be displayed, eg:

jsish -d -h
/zvfs/lib/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:

  • DebugUI: a Debugger user interface for Jsi scripts.
  • SqliteUI: a web user interface to Sqlite.
  • LedgerJS: an accounting program.

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



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

  • Copy tools/geany/filetypes.javascript to ~/.config/geany/filedefs/.
  • Open geany and navigate to Tools->Configuration Files->filetypes_extensions.conf, then:
  • Add ".jsi;.jsc" to Javascript, ".md.html;.htmli;" to HTML and "*.cssi;" to CSS
  • Keep the file tools/protos.jsi open in the editor so Geany knows how to complete Jsi functions.

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

  • Start by editing a .jsi file.
  • From the Geany Build menu, select Set Build Commands.
  • Click on the first blank label in Javascript and enter Jsish.
  • In the command section enter the pathspec to jsish, eg. $HOME/bin/jsish %f
  • Click Ok

Now hit F8 to run the script. Upon errors, you should be able to navigate to the highlighted lines, and see warnings in the bottom pane.

Alternatively, you can just create a Makefile to run jsish.

Also, if using the logging feature in Jsi, you can also navigate through debug messages when using F9 or shell exec.

To run scripts that honor the shebang, repeat the above but set the command section to jsish -# %f.

Caveat: one limitation of Geany is that a function with a return type will likely not show up in the symbols list.


Here is how to setup/use vim with Jsi:

:set filetype javascript
:set makeprg=jsish\ %

Then to run scripts just use:


And much of what was said about navigation in Geany also applies to Vim.

To enable syntax highlighting, run "sudo vi $(locate filetype.vim)", search for javascript, and add ,*.jsi.