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