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