Helma Logo
main list history

Version 1 by hannes on 28. September 2009, 16:35

1Helma NG
2========
3
4Helma NG is a general purpose Javascript runtime and web application framework.
5"NG" stands for "next generation", meaning that it is more of a rewrite of
6Helma 1 than simply a new version.
7
8Helma NG consists of several components that can be used together or alone:
9
10 1. A compact JavaScript runtime environment based on Mozilla Rhino. It adds
11    to Rhino a reloading module system that is compatible to the ServerJS
12    Securable Module proposal.
13
14 2. An interactive shell with support for autocompletion and history.
15
16 3. A module library implemented in JavaScript, covering basic functionality
17    such as extensions to the built-in objects, file I/O, logging, persistence,
18    client and server side HTTP support and more.
19
20For more information, check out the Helma NG homepage and wiki at
21<http://helma.org/wiki/Helma+NG/>
22
23Building Helma
24--------------
25
26Helma requires Java 1.5 and uses Apache Ant as its build environment. If you have
27these installed, building Helma NG is straightforward:
28
29Check out Helma NG from Git:
30
31    git clone git://github.com/hns/helma-ng.git
32
33Change to the helma-ng directory and run ant to compile:
34
35    ant jar
36
37If this succeeds you should now have a file called run.jar and be ready to go.
38
39JavaScript Runtime and Shell
40----------------------------
41
42The Helma JavaScript runtime is based on [Mozilla Rhino][rhino] and supports
43JavaScript 1.7 with partial support for JavaScript 1.8 features.
44
45  [rhino]: http://www.mozilla.org/rhino/
46
47To run Helma NG, add the helma-ng/bin directory to your PATH environment
48variable:
49
50    export PATH=$PATH:/path/to/helma-ng/bin
51
52To start a shell session, just run the helma command without any arguments:
53
54    helma
55
56To run a script simply pass it to helma on the command line:
57
58    helma apps/demo/main.js
59
60If you run a script that is contained in Helma's module path you can also
61use the simpler abstract module name instead of the file name. For example,
62to run the helma test suite:
63
64    helma test/all
65
66To create a new web application, use the admin/create script. This will copy
67an simple skeleton app to the location you define. You can pass the
68application directory as command line argument, or the script will prompt you
69for it.
70
71    helma admin/create [appdir]
72
73Run helma with the -h or --help switch to get more information about available
74command line options. For example, the -i or --interactive option allows you
75to run an application and use the shell at the same time, which can be really
76handy.
77
78Module Path Setup
79-----------------
80
81Helma NG loads JavaScript resources using a module loader that is compliant with
82the ServerJS Securable Modules proposal:
83
84  <https://wiki.mozilla.org/ServerJS/Modules/SecurableModules>
85
86Helma NG actually goes one step further and makes sure every module has its own
87top level scope, so modules are fully isolated from each other, providing a
88programming environment that resembles that of Python environment more than
89the one of ordinary client-side JavaScript runtime.
90
91Helma uses the concept of a module path to look up and load modules that is
92similar to the PATH environment variable used to find executables on most
93operating systems. By default, the module path consists of two entries:
94
95  1. The application root, which is the parent directory of the command line
96    script, or the current working directory if called without script
97    argument.
98
99  2. The system modules root, which corresponds to the modules directory in
100    the Helma NG home directory.
101
102Helma NG provides several ways to access and set the module path. The simplest
103is to set the HELMA_MODULE_PATH environment variable, separating multiple entries
104with ':' or whatever character is used to separate PATH entries on your system:
105
106    export HELMA_MODULE_PATH=../foo/lib:../my/lib
107
108Alternatively, you can define the module path using the helma.modulepath Java
109system property, and you can add entries to the module path using the
110addRepository() method in the helma/system module.
111
112Module and Resource Loading
113---------------------------
114
115Helma NG provides three functions with different semantics to load modules:
116
117`require(moduleName)`
118
119> The require function provides the functionality defined in the ServerJS
120> Securable Modules proposal. It tries to locate a module in the module path,
121> loads it and returns its exports object.
122
123`import(moduleName)`
124
125> The import function builds on top of require, additionally setting a
126> property in the calling module scope whose name is the name of the
127> loaded module and whose value is the loaded module's exports object.
128
129`include(moduleName)`
130
131> The include function builds on top of require, additionally copying
132> all exported properties of the loaded module to the calling module scope.
133
134`export(propertyName[, ...])`
135
136> The export function provides an alternative method to the exports object
137> to define exported properties in a module by passing the names of exported
138> properties as arguments.
139
140`addToClasspath(pathName)`
141
142> This function adds a jar file or directory to the classpath. By default,
143> all jar files in the Helma NG lib directory are included in the classpath.
144
145`getResource(pathName)`
146
147> This looks for a file with the given path name in the module path and
148> returns a resource object. This can be used to load resources other than
149> JavaScript files using the same lookup rules as the module loader.
150
151Web Framework
152-------------
153
154The Helma Web Framework is a web application framework written mostly in JavaScript
155built on top of the Helma Runtime.
156
157To run the demo application that is part of Helma NG run the following command:
158
159    helma apps/demo/main.js
160
161This starts and serves the demo web app on port 8080:
162
163  <http://localhost:8080/>
164
165The demo app showcases a number of tools and libraries to build web apps.
166As Helma NG is still pretty young, many features found in Helma 1.6 are still
167missing, most notably a persistence layer. These features are currently being
168implemented.
169
170The exciting thing is that it will be possible to implement much of it in
171Javascript, meaning you can help doing so without hacking on helma core.
172The new modular concept will even allow to use Helma NG with several
173frameworks, even on the same server instance.
174
175Visit <http://helma.org/wiki/Helma+NG/> and join the Helma NG mailing list to keep up
176with Helma NG core and module development!
177