2) An interactive shell with support for autocompletion and history.
For more information, check out the RingoJS homepage and wiki:
RingoJS requires Java 1.5 and uses Apache Ant as its build environment. If you have these installed, building RingoJS is straightforward:
Check out RingoJS from Git:
git clone git://github.com/ringo/ringojs.git
Change to the ringojs directory and run ant to compile:
If this succeeds you should now have a file called run.jar and be ready to go.
To run RingoJS, add the ringojs/bin directory to your PATH environment variable:
To start a shell session, just run the ringo command without any arguments:
To run a script simply pass it to ringo on the command line:
If you run a script that is contained in RingoJS’ module path you can also use the simpler abstract module name instead of the file name. For example, to run the RingoJS test suite:
To create a new web application, use the ringo-admin create script. This will copy a simple skeleton app to the location you define. You can pass the application directory as command line argument, or the script will prompt you for it.
ringo-admin create [appdir]
Run ringo with the -h or –help switch to get more information about available command line options. For example, the -i or –interactive option allows you to run an application and use the shell at the same time, which can be really handy.
Module Path Setup
RingoJS uses the concept of a module path to look up and load modules that is similar to the PATH environment variable used to find executables on most operating systems. By default, the module path consists of two entries:
1. The application root, which is the parent directory of the command line script, or the current working directory if called without script argument. 2. The system modules root, which corresponds to the modules directory in the RingoJS home directory.
RingoJS provides several ways to access and set the module path. The simplest is to set the RINGO_MODULE_PATH environment variable, separating multiple entries with ‘:’ or whatever character is used to separate PATH entries on your system:
Alternatively, you can define the module path using the ringo.modulepath Java system property, and you can add entries to the module path using the addRepository() method in the ringo/system module.
Module and Resource Loading
RingoJS provides three functions with different semantics to load modules:
The require function provides the functionality defined in the CommonJS Modules proposal. It tries to locate a module in the module path, loads it and returns its exports object.
The import function builds on top of require, additionally setting a property in the calling module scope whose name is the name of the loaded module and whose value is the loaded module's exports object.
The include function builds on top of require, additionally copying all exported properties of the loaded module to the calling module scope.
The export function provides an alternative method to the exports object to define exported properties in a module by passing the names of exported properties as arguments.
This function adds a jar file or directory to the classpath. By default, all jar files in the RingoJS lib directory are included in the classpath.
To run the demo application that is part of RingoJS run the following command:
This starts and serves the demo web app on port 8080:
The demo app showcases a number of tools and libraries to build web apps. As RingoJS is still pretty young, many features are still missing, most notably a persistence layer. These features are currently being implemented.
Visit http://ringojs.org/ and join the RingoJS mailing list to keep up with RingoJS core and module development!