1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/README Wed Apr 27 01:36:41 2016 +0800 1.3 @@ -0,0 +1,152 @@ 1.4 +- What is Nashorn? 1.5 + 1.6 +Nashorn is a runtime environment for programs written in ECMAScript 5.1 1.7 +that runs on top of JVM. 1.8 + 1.9 +- How to find out more about ECMAScript 5.1? 1.10 + 1.11 +The specification can be found at 1.12 + 1.13 + http://www.ecma-international.org/publications/standards/Ecma-262.htm 1.14 + 1.15 +- How to checkout sources of Nashorn project? 1.16 + 1.17 +Nashorn project uses Mercurial source code control system. You can 1.18 +download Mercurial from http://mercurial.selenic.com/wiki/Download 1.19 + 1.20 +Information about the forest extension can be found at 1.21 + 1.22 + http://mercurial.selenic.com/wiki/ForestExtension 1.23 + 1.24 +and downlaoded using 1.25 + 1.26 + hg clone https://bitbucket.org/gxti/hgforest 1.27 + 1.28 +You can clone Nashorn Mercurial forest using this command: 1.29 + 1.30 + hg fclone http://hg.openjdk.java.net/nashorn/jdk8 nashorn~jdk8 1.31 + 1.32 +To update your copy of the forest (fwith the latest code: 1.33 + 1.34 + (cd nashorn~jdk8 ; hg fpull) 1.35 + 1.36 +Or just the nashorn subdirectory with 1.37 + 1.38 + (cd nashorn~jdk8/nashorn ; hg pull -u) 1.39 + 1.40 +To learn about Mercurial in detail, please visit http://hgbook.red-bean.com. 1.41 + 1.42 +- How to build? 1.43 + 1.44 +To build Nashorn, you need to install JDK 8. You may use the Nashorn 1.45 +forest build (recommended) or down load from java.net. You will need to 1.46 +set JAVA_HOME environmental variable to point to your JDK installation 1.47 +directory. 1.48 + 1.49 + cd nashorn~jdk8/nashorn/make 1.50 + ant clean; ant 1.51 + 1.52 +- How to run? 1.53 + 1.54 +Use the jjs script (see RELESE_README): 1.55 + 1.56 + cd nashorn~jdk8/nashorn 1.57 + sh bin/jjs <your .js file> 1.58 + 1.59 +Nashorn supports javax.script API. It is possible to drop nashorn.jar in 1.60 +class path and request for "nashorn" script engine from 1.61 +javax.script.ScriptEngineManager. 1.62 + 1.63 +Look for samples under the directory test/src/jdk/nashorn/api/scripting/. 1.64 + 1.65 +- Documentation 1.66 + 1.67 +Comprehensive development documentation is found in the Nashorn JavaDoc. You can 1.68 +build it using: 1.69 + 1.70 + cd nashorn~jdk8/nashorn/make 1.71 + ant javadoc 1.72 + 1.73 +after which you can view the generated documentation at dist/javadoc/index.html. 1.74 + 1.75 +- Running tests 1.76 + 1.77 +Nashorn tests are TestNG based. Running tests requires downloading the 1.78 +TestNG library and placing its jar file into the lib subdirectory: 1.79 + 1.80 + # download and install TestNG 1.81 + wget http://testng.org/testng-x.y.z.zip 1.82 + unzip testng-x.y.z.zip 1.83 + cp testng-x.y.z/testng-x.y.z.jar test/lib/testng.jar 1.84 + 1.85 +After that, you can run the tests using: 1.86 + cd make 1.87 + ant clean test 1.88 + 1.89 +You can also run the ECMA-262 test suite with Nashorn. In order to do 1.90 +that, you will need to get a copy of it and put it in 1.91 +test/script/external/test262 directory. A convenient way to do it is: 1.92 + 1.93 + git clone https://github.com/tc39/test262 test/script/external/test262 1.94 + 1.95 +Alternatively, you can check it out elsewhere and make 1.96 +test/script/external/test262 a symbolic link to that directory. After 1.97 +you've done this, you can run the ECMA-262 tests using: 1.98 + 1.99 + cd nashorn~jdk8/nashorn/make 1.100 + ant test262 1.101 + 1.102 +Ant target to get/update external test suites: 1.103 + 1.104 + ant externals 1.105 + ant update-externals 1.106 + 1.107 +These tests take time, so we have a parallelized runner for them that 1.108 +takes advantage of all processor cores on the computer: 1.109 + 1.110 + cd nashorn~jdk8/nashorn/make 1.111 + ant test262parallel 1.112 + 1.113 +- How to write your own test? 1.114 + 1.115 +Nashorn uses it's own simple test framework. Any .js file dropped under 1.116 +nashorn/test directory is considered as a test. A test file can 1.117 +optionally have .js.EXPECTED (foo.js.EXPECTED for foo.js) associated 1.118 +with it. The .EXPECTED file, if exists, should contain the output 1.119 +expected from compiling and/or running the test file. 1.120 + 1.121 +The test runner crawls these directories for .js files and looks for 1.122 +JTReg-style @foo comments to identify tests. 1.123 + 1.124 + * @test - A test is tagged with @test. 1.125 + 1.126 + * @test/fail - Tests that are supposed to fail (compiling, see @run/fail 1.127 + for runtime) are tagged with @test/fail. 1.128 + 1.129 + * @test/compile-error - Test expects compilation to fail, compares 1.130 + output. 1.131 + 1.132 + * @test/warning - Test expects compiler warnings, compares output. 1.133 + 1.134 + * @test/nocompare - Test expects to compile [and/or run?] 1.135 + successfully(may be warnings), does not compare output. 1.136 + 1.137 + * @subtest - denotes necessary file for a main test file; itself is not 1.138 + a test. 1.139 + 1.140 + * @run - A test that should be run is also tagged with @run (otherwise 1.141 + the test runner only compiles the test). 1.142 + 1.143 + * @run/fail - A test that should compile but fail with a runtime error. 1.144 + 1.145 + * @run/ignore-std-error - script may produce output on stderr, ignore 1.146 + this output. 1.147 + 1.148 + * @argument - pass an argument to script. 1.149 + 1.150 + * @option \ - pass option to engine, sample. 1.151 + 1.152 +/** 1.153 + * @option --dump-ir-graph 1.154 + * @test 1.155 + */