annotate README @ 356:2a377892c255

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