hns / helma-ng

Helma NG is a JavaScript runtime and shell based on Rhino providing a CommonJS conformant module library and web application framework.

This URL has Read+Write access

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