README
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 downloaded 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/jdk9 nashorn~jdk9
28
29To update your copy of the forest (fwith the latest code:
30
31 (cd nashorn~jdk9 ; hg fpull)
32
33Or just the nashorn subdirectory with
34
35 (cd nashorn~jdk9/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 9. You may use the Nashorn
42forest build (recommended) or download from java.net. You will need to
43set JAVA_HOME environmental variable to point to your JDK installation
44directory.
45
46 cd nashorn~jdk9/nashorn/make
47 ant clean; ant
48
49- How to run?
50
51Use the jjs script (see RELESE_README):
52
53 cd nashorn~jdk9/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~jdk9/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 test/lib subdirectory. This is
76done automatically when executing the "ant externals" command to get external
77test suites (see below).
78
79Once TestNG is properly installed, you can run the tests using:
80 cd make
81 ant clean test
82
83You can also run the ECMA-262 test suite with Nashorn. In order to do
84that, you will need to get a copy of it and put it in
85test/script/external/test262 directory. A convenient way to do it is:
86
87 git clone https://github.com/tc39/test262 test/script/external/test262
88
89Alternatively, you can check it out elsewhere and make
90test/script/external/test262 a symbolic link to that directory. After
91you've done this, you can run the ECMA-262 tests using:
92
93 cd nashorn~jdk9/nashorn/make
94 ant test262
95
96Ant target to get/update external test suites:
97
98 ant externals
99 ant update-externals
100
101These tests take time, so we have a parallelized runner for them that
102takes advantage of all processor cores on the computer:
103
104 cd nashorn~jdk9/nashorn/make
105 ant test262parallel
106
107- How to write your own test?
108
109Nashorn uses it's own simple test framework. Any .js file dropped under
110nashorn/test directory is considered as a test. A test file can
111optionally have .js.EXPECTED (foo.js.EXPECTED for foo.js) associated
112with it. The .EXPECTED file, if exists, should contain the output
113expected from compiling and/or running the test file.
114
115The test runner crawls these directories for .js files and looks for
116JTReg-style @foo comments to identify tests.
117
118 * @test - A test is tagged with @test.
119
120 * @test/fail - Tests that are supposed to fail (compiling, see @run/fail
121 for runtime) are tagged with @test/fail.
122
123 * @test/compile-error - Test expects compilation to fail, compares
124 output.
125
126 * @test/warning - Test expects compiler warnings, compares output.
127
128 * @test/nocompare - Test expects to compile [and/or run?]
129 successfully(may be warnings), does not compare output.
130
131 * @subtest - denotes necessary file for a main test file; itself is not
132 a test.
133
134 * @run - A test that should be run is also tagged with @run (otherwise
135 the test runner only compiles the test).
136
137 * @run/fail - A test that should compile but fail with a runtime error.
138
139 * @run/ignore-std-error - script may produce output on stderr, ignore
140 this output.
141
142 * @argument - pass an argument to script.
143
144 * @option \ - pass option to engine, sample.
145
146/**
147 * @option --dump-ir-graph
148 * @test
149 */
150