GettingStarted.md

This is a very short tutorial on how to install and start using RingoJS.

Which Version

We try to release often - at least every 2 months - but Ringo is moving fast and with the git version you will always get the newest features. All Ringo developers use the git version for their projects and the git master is usually very stable.

But, using the most recent git version means you should keep an eye on the Ringo mailing list - big changes that might break your code will be discussed on the list beforehand.

Ringo requires Java 1.5+

We recommend the Java Sun Package. Either download it from the Oracle download page or on debian simply apt-get it:

$ apt-get install sun-java6-jdk

Option 1: Get the latest official release

Download the latest Ringo release:

Install the deb or unpack the archive if you downloaded the zip or tar.gz release. See the sections below on how start hacking Ringo applications.

Option 2: Install from Git

In addition to Java you will need Apache Ant to create the jar files, get it from the Ant Homepage or on debian:

$ apt-get install ant

Get the current git snapshot with:

$ git clone git://github.com/ringo/ringojs.git

Change to the ringojs directory you just checked out and run ant with the jar target

$ ant jar

If this worked then you should now have a file called lib/ringo.jar. Ringo is now ready to use.

Starting the Ringo Shell

Run the ringo script in the bin directory without arguments:

$ ./bin/ringo

This should start a shell session with a >> prompt. Use the include, require, or import functions to load any RingoJS modules.

>> var fs = require('fs');
>> var file = fs.open('README.txt');
>> var lines = [line for (line in file)];

Tips:

Hitting Tab will try to auto-complete your current input.
You can scroll through your session history using the Up and Down keys
Ringo supports most of JavaScript 1.8 and ECMAScript 5 - you can read more about that [here][modern javascript support].

Running the demo webapp

Simply pass the main file of the app to the ringo command:

$ bin/ringo apps/demo/main.js

This will start the RingoJS demo app on port 8080. Access the app in your browser by going to http://localhost:8080/

Tips:

You can also run an application and the shell at the same time by adding the -i or --interactive option before the application name
Use Ringo's -h or --help options for more information on available options.

Starting your own application

To start hacking on your own RingoJS application, use the ringo-admin create script to create a new app:

$ bin/ringo-admin create [app directory]

If you don't pass the app directory on the command line the script will prompt you for it. Once the application has been created you can start it by running its main.js script:

$ bin/ringo appname/main.js

More Help

If you like RingoJS drop a note on the mailing list or the IRC channel!

oberhamsi/GettingStarted.md