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

Contents

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
 DOWNLOAD / DEVELOP / DEPLOY

Types Builtin Reference  Index  Fossil  Demos Log Test Debug Misc

   

Start

This page describes getting started with Jsi.

   

Download

If you don't want to build Jsi from source, limited binaries are available here: https://jsish.org/jsi-bin

   

Source

To download the zipped source:

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

Then follow build directions.

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

   

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 https://jsish.org/jsi jsi.fossil && fossil open jsi.fossil

Then follow build directions.

To get fossil:

   

Building

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.

   

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

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
   

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 use “gmake” instead of “make” and:

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

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.

   

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

Amalgamation

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

   

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
# var a = [1,2,3]; # for (var i in a) { puts(a[i]); } 1 2 3 ...
   

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

Help

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.
   

Switches

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.

   

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

Apps

Jsi is distributed with several demonstration web applications:

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

   

Autocomplete

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.

   

Editors

   

Geany

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