1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/README Fri Dec 21 16:36:24 2012 -0400
1.3 @@ -0,0 +1,147 @@
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 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 + hg clone http://hg.ecmascript.org/tests/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 +These tests take time, so we have a parallelized runner for them that
1.103 +takes advantage of all processor cores on the computer:
1.104 +
1.105 + cd nashorn~jdk8/nashorn/make
1.106 + ant test262parallel
1.107 +
1.108 +- How to write your own test?
1.109 +
1.110 +Nashorn uses it's own simple test framework. Any .js file dropped under
1.111 +nashorn/test directory is considered as a test. A test file can
1.112 +optionally have .js.EXPECTED (foo.js.EXPECTED for foo.js) associated
1.113 +with it. The .EXPECTED file, if exists, should contain the output
1.114 +expected from compiling and/or running the test file.
1.115 +
1.116 +The test runner crawls these directories for .js files and looks for
1.117 +JTReg-style @foo comments to identify tests.
1.118 +
1.119 + * @test - A test is tagged with @test.
1.120 +
1.121 + * @test/fail - Tests that are supposed to fail (compiling, see @run/fail
1.122 + for runtime) are tagged with @test/fail.
1.123 +
1.124 + * @test/compile-error - Test expects compilation to fail, compares
1.125 + output.
1.126 +
1.127 + * @test/warning - Test expects compiler warnings, compares output.
1.128 +
1.129 + * @test/nocompare - Test expects to compile [and/or run?]
1.130 + successfully(may be warnings), does not compare output.
1.131 +
1.132 + * @subtest - denotes necessary file for a main test file; itself is not
1.133 + a test.
1.134 +
1.135 + * @run - A test that should be run is also tagged with @run (otherwise
1.136 + the test runner only compiles the test).
1.137 +
1.138 + * @run/fail - A test that should compile but fail with a runtime error.
1.139 +
1.140 + * @run/ignore-std-error - script may produce output on stderr, ignore
1.141 + this output.
1.142 +
1.143 + * @argument - pass an argument to script.
1.144 +
1.145 + * @option \ - pass option to engine, sample.
1.146 +
1.147 +/**
1.148 + * @option --dump-ir-graph
1.149 + * @test
1.150 + */
