/ Download
DEMO | DOWNLOAD | DEPLOY | SEARCH
Login

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

Download

Note: you can download a static binaries here.

Source

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.

Fossil

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:

Building

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.

Linux

To build the Linux target there are are two steps:

./configure

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.

make

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

Debian

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

cd tools
./makedep.sh
sudo dpkg -i jsish-*

FreeBSD

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

pkg install fetch gmake bison

Windows

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.

Standalone

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
make

Embedding

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);
    Jsi_EvalFile(interp, argv[1], 0);
}

This is compile with:

gcc  myfile.c -o myfile -lm -lz -ldl -lpthreads
jsish -z -zvfs true myfile

Another alternative is to use jsiOne.c, if you need to debug Jsi itself.

Note: Jsi is written in C, and can be compiled as either native C, or native C++: it does not use extern C.

Using

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

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

  ./jsish

==>

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]); }
1
2
3
# 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;
21
# ^C

Script

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)
   puts(console.args[i]);

The above allows jsish to be found in the path.

Inline

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;'

Help

To see the supported switches in jsish use -h

jsish -h
USAGE:
  jsish [PREFIX-OPTS] [COMMAND-OPTS|FILE] ...

PREFIX-OPTS:
  --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.

COMMAND-OPTS:
  -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.

Modules

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    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

Apps

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.

Shell

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

Editors

Geany

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.

Vim

Here is how to setup/use vim with Jsi:

:set filetype javascript
:set makeprg=jsish\ %
:copen

Then to run scripts just use:

:make

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