README revision 776:1a9a2d8bd800 
1- What is Nashorn?
2
3Nashorn is a runtime environment for programs written in ECMAScript 5.1
4that runs on top of JVM.
5
6- How to find out more about ECMAScript 5.1?
7
8The specification can be found at
9
10    http://www.ecma-international.org/publications/standards/Ecma-262.htm
11
12- How to checkout sources of Nashorn project?
13
14Nashorn project uses Mercurial source code control system. You can
15download Mercurial from http://mercurial.selenic.com/wiki/Download
16
17Information about the forest extension can be found at
18
19    http://mercurial.selenic.com/wiki/ForestExtension
20
21and downlaoded using
22
23    hg clone https://bitbucket.org/gxti/hgforest
24
25You can clone Nashorn Mercurial forest using this command:
26
27    hg fclone http://hg.openjdk.java.net/nashorn/jdk8 nashorn~jdk8
28    
29To update your copy of the forest (fwith the latest code:
30
31    (cd nashorn~jdk8 ; hg fpull)
32    
33Or just the nashorn subdirectory with
34
35    (cd nashorn~jdk8/nashorn ; hg pull -u)
36    
37To learn about Mercurial in detail, please visit http://hgbook.red-bean.com.
38
39- How to build?
40
41To build Nashorn, you need to install JDK 8. You may use the Nashorn
42forest build (recommended) or down load from java.net.  You will need to
43set JAVA_HOME environmental variable to point to your JDK installation
44directory.
45
46    cd nashorn~jdk8/nashorn/make
47    ant clean; ant
48
49- How to run?
50
51Use the jjs script (see RELESE_README):
52
53    cd nashorn~jdk8/nashorn
54    sh bin/jjs <your .js file>
55
56Nashorn supports javax.script API. It is possible to drop nashorn.jar in
57class path and request for "nashorn" script engine from
58javax.script.ScriptEngineManager. 
59
60Look for samples under the directory test/src/jdk/nashorn/api/scripting/.
61
62- Documentation
63
64Comprehensive development documentation is found in the Nashorn JavaDoc. You can
65build it using:
66
67    cd nashorn~jdk8/nashorn/make
68    ant javadoc
69    
70after which you can view the generated documentation at dist/javadoc/index.html.
71
72- Running tests
73
74Nashorn tests are TestNG based. Running tests requires downloading the
75TestNG library and placing its jar file into the lib subdirectory:
76
77    # download and install TestNG
78    wget http://testng.org/testng-x.y.z.zip
79    unzip testng-x.y.z.zip
80    cp testng-x.y.z/testng-x.y.z.jar test/lib/testng.jar
81    
82After that, you can run the tests using:
83    cd make
84    ant clean test
85    
86You can also run the ECMA-262 test suite with Nashorn. In order to do
87that, you will need to get a copy of it and put it in
88test/script/external/test262 directory. A convenient way to do it is:
89
90   git clone https://github.com/tc39/test262 test/script/external/test262
91    
92Alternatively, you can check it out elsewhere and make
93test/script/external/test262 a symbolic link to that directory. After
94you've done this, you can run the ECMA-262 tests using:
95
96    cd nashorn~jdk8/nashorn/make
97    ant test262
98
99Ant target to get/update external test suites:
100
101    ant externals
102    ant update-externals
103    
104These tests take time, so we have a parallelized runner for them that
105takes advantage of all processor cores on the computer:
106
107    cd nashorn~jdk8/nashorn/make
108    ant test262parallel
109    
110- How to write your own test?
111
112Nashorn uses it's own simple test framework. Any .js file dropped under
113nashorn/test directory is considered as a test. A test file can
114optionally have .js.EXPECTED (foo.js.EXPECTED for foo.js) associated
115with it. The .EXPECTED file, if exists, should contain the output
116expected from compiling and/or running the test file.
117
118The test runner crawls these directories for .js files and looks for
119JTReg-style @foo comments to identify tests.
120
121    * @test - A test is tagged with @test.
122
123    * @test/fail - Tests that are supposed to fail (compiling, see @run/fail
124      for runtime) are tagged with @test/fail.
125
126    * @test/compile-error - Test expects compilation to fail, compares
127      output.
128
129    * @test/warning - Test expects compiler warnings, compares output.
130
131    * @test/nocompare - Test expects to compile [and/or run?]
132      successfully(may be warnings), does not compare output.
133
134    * @subtest - denotes necessary file for a main test file; itself is not
135      a test.
136
137    * @run - A test that should be run is also tagged with @run (otherwise
138      the test runner only compiles the test).
139
140    * @run/fail - A test that should compile but fail with a runtime error.
141
142    * @run/ignore-std-error - script may produce output on stderr, ignore
143      this output.
144
145    * @argument - pass an argument to script.
146
147    * @option \ - pass option to engine, sample.
148
149/**
150 * @option --dump-ir-graph
151 * @test
152 */
153