Thu, 23 May 2013 15:51:08 +0200
8012522: Clean up lexical contexts - split out stack based functionality in CodeGenerator and generify NodeVisitors based on their LexicalContext type to avoid casts
Reviewed-by: attila, jlaskey
1 - What is Nashorn?
3 Nashorn is a runtime environment for programs written in ECMAScript 5.1
4 that runs on top of JVM.
6 - How to find out more about ECMAScript 5.1?
8 The specification can be found at
10 http://www.ecma-international.org/publications/standards/Ecma-262.htm
12 - How to checkout sources of Nashorn project?
14 Nashorn project uses Mercurial source code control system. You can
15 download Mercurial from http://mercurial.selenic.com/wiki/Download
17 Information about the forest extension can be found at
19 http://mercurial.selenic.com/wiki/ForestExtension
21 and downlaoded using
23 hg clone https://bitbucket.org/gxti/hgforest
25 You can clone Nashorn Mercurial forest using this command:
27 hg fclone http://hg.openjdk.java.net/nashorn/jdk8 nashorn~jdk8
29 To update your copy of the forest (fwith the latest code:
31 (cd nashorn~jdk8 ; hg fpull)
33 Or just the nashorn subdirectory with
35 (cd nashorn~jdk8/nashorn ; hg pull -u)
37 To learn about Mercurial in detail, please visit http://hgbook.red-bean.com.
39 - How to build?
41 To build Nashorn, you need to install JDK 8. You may use the Nashorn
42 forest build (recommended) or down load from java.net. You will need to
43 set JAVA_HOME environmental variable to point to your JDK installation
44 directory.
46 cd nashorn~jdk8/nashorn/make
47 ant clean; ant
49 - How to run?
51 Use the jjs script (see RELESE_README):
53 cd nashorn~jdk8/nashorn
54 sh bin/jjs <your .js file>
56 Nashorn supports javax.script API. It is possible to drop nashorn.jar in
57 class path and request for "nashorn" script engine from
58 javax.script.ScriptEngineManager.
60 Look for samples under the directory test/src/jdk/nashorn/api/scripting/.
62 - Documentation
64 Comprehensive development documentation is found in the Nashorn JavaDoc. You can
65 build it using:
67 cd nashorn~jdk8/nashorn/make
68 ant javadoc
70 after which you can view the generated documentation at dist/javadoc/index.html.
72 - Running tests
74 Nashorn tests are TestNG based. Running tests requires downloading the
75 TestNG library and placing its jar file into the lib subdirectory:
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
82 After that, you can run the tests using:
83 cd make
84 ant test
86 You can also run the ECMA-262 test suite with Nashorn. In order to do
87 that, you will need to get a copy of it and put it in
88 test/script/external/test262 directory. A convenient way to do it is:
90 hg clone http://hg.ecmascript.org/tests/test262/ test/script/external/test262
92 Alternatively, you can check it out elsewhere and make
93 test/script/external/test262 a symbolic link to that directory. After
94 you've done this, you can run the ECMA-262 tests using:
96 cd nashorn~jdk8/nashorn/make
97 ant test262
99 These tests take time, so we have a parallelized runner for them that
100 takes advantage of all processor cores on the computer:
102 cd nashorn~jdk8/nashorn/make
103 ant test262parallel
105 - How to write your own test?
107 Nashorn uses it's own simple test framework. Any .js file dropped under
108 nashorn/test directory is considered as a test. A test file can
109 optionally have .js.EXPECTED (foo.js.EXPECTED for foo.js) associated
110 with it. The .EXPECTED file, if exists, should contain the output
111 expected from compiling and/or running the test file.
113 The test runner crawls these directories for .js files and looks for
114 JTReg-style @foo comments to identify tests.
116 * @test - A test is tagged with @test.
118 * @test/fail - Tests that are supposed to fail (compiling, see @run/fail
119 for runtime) are tagged with @test/fail.
121 * @test/compile-error - Test expects compilation to fail, compares
122 output.
124 * @test/warning - Test expects compiler warnings, compares output.
126 * @test/nocompare - Test expects to compile [and/or run?]
127 successfully(may be warnings), does not compare output.
129 * @subtest - denotes necessary file for a main test file; itself is not
130 a test.
132 * @run - A test that should be run is also tagged with @run (otherwise
133 the test runner only compiles the test).
135 * @run/fail - A test that should compile but fail with a runtime error.
137 * @run/ignore-std-error - script may produce output on stderr, ignore
138 this output.
140 * @argument - pass an argument to script.
142 * @option \ - pass option to engine, sample.
144 /**
145 * @option --dump-ir-graph
146 * @test
147 */