README revision 776:1a9a2d8bd800
1218885Sdim- What is Nashorn? 2218885Sdim 3218885SdimNashorn is a runtime environment for programs written in ECMAScript 5.1 4218885Sdimthat runs on top of JVM. 5218885Sdim 6218885Sdim- How to find out more about ECMAScript 5.1? 7218885Sdim 8218885SdimThe specification can be found at 9218885Sdim 10218885Sdim http://www.ecma-international.org/publications/standards/Ecma-262.htm 11218885Sdim 12226633Sdim- How to checkout sources of Nashorn project? 13218885Sdim 14218885SdimNashorn project uses Mercurial source code control system. You can 15218885Sdimdownload Mercurial from http://mercurial.selenic.com/wiki/Download 16249423Sdim 17249423SdimInformation about the forest extension can be found at 18226633Sdim 19249423Sdim http://mercurial.selenic.com/wiki/ForestExtension 20218885Sdim 21218885Sdimand downlaoded using 22218885Sdim 23218885Sdim hg clone https://bitbucket.org/gxti/hgforest 24218885Sdim 25226633SdimYou can clone Nashorn Mercurial forest using this command: 26218885Sdim 27218885Sdim hg fclone http://hg.openjdk.java.net/nashorn/jdk8 nashorn~jdk8 28218885Sdim 29218885SdimTo update your copy of the forest (fwith the latest code: 30218885Sdim 31226633Sdim (cd nashorn~jdk8 ; hg fpull) 32218885Sdim 33218885SdimOr just the nashorn subdirectory with 34218885Sdim 35218885Sdim (cd nashorn~jdk8/nashorn ; hg pull -u) 36218885Sdim 37218885SdimTo learn about Mercurial in detail, please visit http://hgbook.red-bean.com. 38218885Sdim 39226633Sdim- How to build? 40226633Sdim 41226633SdimTo build Nashorn, you need to install JDK 8. You may use the Nashorn 42226633Sdimforest build (recommended) or down load from java.net. You will need to 43226633Sdimset JAVA_HOME environmental variable to point to your JDK installation 44226633Sdimdirectory. 45226633Sdim 46218885Sdim cd nashorn~jdk8/nashorn/make 47226633Sdim ant clean; ant 48218885Sdim 49249423Sdim- How to run? 50218885Sdim 51218885SdimUse the jjs script (see RELESE_README): 52218885Sdim 53226633Sdim cd nashorn~jdk8/nashorn 54226633Sdim sh bin/jjs <your .js file> 55218885Sdim 56218885SdimNashorn supports javax.script API. It is possible to drop nashorn.jar in 57218885Sdimclass path and request for "nashorn" script engine from 58218885Sdimjavax.script.ScriptEngineManager. 59218885Sdim 60218885SdimLook for samples under the directory test/src/jdk/nashorn/api/scripting/. 61218885Sdim 62218885Sdim- Documentation 63218885Sdim 64218885SdimComprehensive development documentation is found in the Nashorn JavaDoc. You can 65218885Sdimbuild it using: 66218885Sdim 67218885Sdim cd nashorn~jdk8/nashorn/make 68218885Sdim ant javadoc 69218885Sdim 70218885Sdimafter which you can view the generated documentation at dist/javadoc/index.html. 71226633Sdim 72218885Sdim- Running tests 73226633Sdim 74226633SdimNashorn tests are TestNG based. Running tests requires downloading the 75226633SdimTestNG library and placing its jar file into the lib subdirectory: 76218885Sdim 77226633Sdim # download and install TestNG 78226633Sdim wget http://testng.org/testng-x.y.z.zip 79226633Sdim unzip testng-x.y.z.zip 80226633Sdim cp testng-x.y.z/testng-x.y.z.jar test/lib/testng.jar 81226633Sdim 82218885SdimAfter that, you can run the tests using: 83218885Sdim cd make 84218885Sdim ant clean test 85218885Sdim 86226633SdimYou can also run the ECMA-262 test suite with Nashorn. In order to do 87226633Sdimthat, you will need to get a copy of it and put it in 88218885Sdimtest/script/external/test262 directory. A convenient way to do it is: 89226633Sdim 90218885Sdim git clone https://github.com/tc39/test262 test/script/external/test262 91226633Sdim 92226633SdimAlternatively, you can check it out elsewhere and make 93226633Sdimtest/script/external/test262 a symbolic link to that directory. After 94226633Sdimyou've done this, you can run the ECMA-262 tests using: 95226633Sdim 96226633Sdim cd nashorn~jdk8/nashorn/make 97226633Sdim ant test262 98226633Sdim 99218885SdimAnt target to get/update external test suites: 100226633Sdim 101226633Sdim ant externals 102226633Sdim ant update-externals 103226633Sdim 104226633SdimThese tests take time, so we have a parallelized runner for them that 105226633Sdimtakes advantage of all processor cores on the computer: 106226633Sdim 107218885Sdim cd nashorn~jdk8/nashorn/make 108218885Sdim ant test262parallel 109218885Sdim 110218885Sdim- How to write your own test? 111218885Sdim 112226633SdimNashorn uses it's own simple test framework. Any .js file dropped under 113226633Sdimnashorn/test directory is considered as a test. A test file can 114226633Sdimoptionally have .js.EXPECTED (foo.js.EXPECTED for foo.js) associated 115226633Sdimwith it. The .EXPECTED file, if exists, should contain the output 116218885Sdimexpected from compiling and/or running the test file. 117226633Sdim 118226633SdimThe test runner crawls these directories for .js files and looks for 119226633SdimJTReg-style @foo comments to identify tests. 120226633Sdim 121226633Sdim * @test - A test is tagged with @test. 122218885Sdim 123218885Sdim * @test/fail - Tests that are supposed to fail (compiling, see @run/fail 124218885Sdim for runtime) are tagged with @test/fail. 125218885Sdim 126218885Sdim * @test/compile-error - Test expects compilation to fail, compares 127218885Sdim output. 128226633Sdim 129226633Sdim * @test/warning - Test expects compiler warnings, compares output. 130226633Sdim 131218885Sdim * @test/nocompare - Test expects to compile [and/or run?] 132218885Sdim successfully(may be warnings), does not compare output. 133226633Sdim 134218885Sdim * @subtest - denotes necessary file for a main test file; itself is not 135226633Sdim a test. 136226633Sdim 137218885Sdim * @run - A test that should be run is also tagged with @run (otherwise 138218885Sdim the test runner only compiles the test). 139218885Sdim 140218885Sdim * @run/fail - A test that should compile but fail with a runtime error. 141218885Sdim 142226633Sdim * @run/ignore-std-error - script may produce output on stderr, ignore 143218885Sdim this output. 144218885Sdim 145218885Sdim * @argument - pass an argument to script. 146218885Sdim 147218885Sdim * @option \ - pass option to engine, sample. 148218885Sdim 149218885Sdim/** 150218885Sdim * @option --dump-ir-graph 151218885Sdim * @test 152218885Sdim */ 153218885Sdim