Description:
New page
VJETV is the validation feature which can be added to a continuous build
== VJETV Abstractvjetv [ options ] [ sourcefiles ] [ @argfiles ]Arguments may be in any order. ==
[http://java.sun.com/javase/6/docs/technotes/tools/windows/javac.html#options options]
Command-line options.
sourcefiles
One or more source files to be compiled (such as MyType.js).
@argfiles
One or more files that lists options and source files. The -V options are not allowed in these files.
Note - vjetv entry points may be different depending on integration. See section on integrations.
== Description ==
The '''vjetv''' tool reads ctype, mtype, itype, otype, and etype definitions, written in the VJET and JS programming language, and validates these files.
There are two ways to pass source code file names to '''vjetv''':
* For a small number of source files, simply list the file names on the command line.
* For a large number of source files, list the file names in a file, separated by blanks or line breaks. Then use the list file name on the '''vjetv''' command line, preceded by an '''@''' character.
Source code file names must have .js suffixes these files must have root names that identify the type. For example, a class called MyClass would be written in a source file called MyClass.js.
You should arrange source files in a directory tree that reflects their package tree. For example, if you keep all your source files in '''C:\workspace''', the source code for com.mysoft.mypack.MyClass should be in '''C:\workspace\com\mysoft\mypack\MyClass.js'''.
== Command Line Options ==
'''vjetv''' has a set of standard options that are supported on the current development environment and will be supported in future releases. An additional set of non-standard options are specific to the current virtual machine and validator implementations and are subject to change in the future. Non-standard options begin with '''-X'''.
== Standard Options ==
'''-bp''' ''path'' or '''-buildpath''' ''path''
Specify where to find user source files. This buildpath overrides the user build path in the '''VJETBUILDPATH''' environment variable. If neither '''VJETBUILDPATH''', '''-bp''' nor '''-buildpath''' is specified, the user build path consists of the current directory.
As a special convenience, a build path element containing a basename of * is considered equivalent to specifying a list of all the files in the directory with the extension .jar or .JAR.
For example, if directory foo contains a.jar and b.JAR, then the build path element foo/* is expanded to A.jar;b.JAR, except that the order of jar files is unspecified. All jar files in the specified directory, even hidden ones, are included in the list. A buildpath entry consisting simply of * expands to a list of all the jar files in the current directory. The VJETBUILDPATH environment variable, where defined, will be similarly expanded. '''Note:''' Depending of the configuration of your command line environment, you may have to quote the wild card character, for example, vjetv -bp "*.jar" MyClass.js.
'''-g'''
Generate all debugging information, including local variables. By default, only line number and source file information is generated.
'''-g:none'''
Do not generate any debugging information.
'''-g:'''{_}
{keyword list}
_
Generate only some kinds of debugging information, specified by a comma separated list of keywords. Valid keywords are:
'''source'''
Source file debugging information
'''lines'''
Line number debugging information
'''vars'''
Local variable debugging information
'''-help'''
Print a synopsis of standard options.
'''-nowarn'''
Disable warning messages.
'''-vjetversion''' ''release''
Specifies the VJET runtime version of source code accepted. The following values for ''release'' are allowed:
1.0
1 (synonym for 1.0)
'''-jsversion release'''
Specifies the JavaScript version that is supported. Currently only 1.5 is supported.
'''1.5'''
'''5 (synonym for 1.5)'''
'''-verbose'''
Verbose output. This includes information about each java class and vjet type that is loaded and each source file that is validated.
'''-deprecation'''
Show a description of each use or override of a deprecated member or class. Without '''-deprecation''', '''javac''' shows a summary of the source files that use or override deprecated members or classes. '''-deprecation''' is shorthand for '''-Xlint:deprecation'''.
'''-encoding''' ''encoding''
Set the source file encoding name, such as EUC-JP and UTF-8. If '''-encoding''' is not specified, the platform default converter is used.
'''-bootpath''' ''bootpath''
Validate against the specified set of boot classes. As with the user class path, boot path entries are separated by semicolons (''';''') and can be directories, JAR archives, or ZIP archives. This is used to replace Javascript core library or VJET core functions.
== Command Line Argument Files ==
To shorten or simplify the vjetv command line, you can specify one or more files that themselves contain arguments to the vjetv command. This enables you to create vjetv commands of any length on any operating system.
An argument file can include vjetv options and source filenames in any combination. The arguments within a file can be space-separated or newline-separated. If a filename contains embedded spaces, put the whole filename in double quotes, and double each backslash ("My Files
Stuff.js").
Filenames within an argument file are relative to the current directory, not the location of the argument file. Wildcards (*) are not allowed in these lists (such as for specifying *.js). Use of the '@' character to recursively interpret files is not supported.
When executing vjetv, pass in the path and name of each argument file with the '@' leading character. When vjetv encounters an argument beginning with the character `@', it expands the contents of that file into the argument list.
=== Example - Single Arg File ===
You could use a single argument file named "argfile" to hold all vjetv arguments: C:> vjetv @argfile
This argument file could contain the contents of both files shown in the next example.
=== Example - Two Arg Files ===
You can create two argument files -- one for the vjetv options and the other for the source filenames: (Notice the following lists have no line-continuation characters.)
Create a file named "options" containing: -g
-jsversion 1.5
-vjetversion 1
Create a file named "types" containing: MyCType.js
MyCType2.js
MyCType3.js
You would then run '''javac''' with: C:> vjetv @options @types
=== Example - Arg Files with Paths ===
The argument files can have paths, but any filenames inside the files are relative to the current working directory (not path1 or path2): C:> vjetv @path1\options @path2\classes
== Searching for Types ==
When validating a source file, the validator often needs information about a type whose definition did not appear in the source files given on the command line. The validator needs type information for every type used, inherited, expected, mixed in, or satisfied in the source file. This includes type not explicitly mentioned in the source file but which provide information through inheritance.
For example, when you subclass '''vjet.java.util.Arrays''', you are also using '''Array's''' required types.
When the validator needs type information, it looks for a source file that defines the type. The validator searches for type files first in the bootstrap and extension types, then in the user build path (which by default is the current directory). The user class path is defined by setting the '''VJETBUILDPATH''' environment variable or by using the '''-buildpath''' command line option.
You can specify different bootstrap or extension classes with the '''--bootbuildpath'''. This can be used to replace the vjet bootstrap or Javascript core types.
A successful type search may produce a js file, a binary ser, or both. If both are found, you can use the -Xprefer option to instruct the validator which to use. If '''newer''' is given, the validator will use the newer of the two files. If '''source''' is given, it will use the source file. The default is '''source not ser'''.
== Validator API ==
'''vjetv''' supports the VJET Validator API defined by the classes and interfaces in the com.ebay.vjo.tool.validatorpackage.
=== Example ===
To perform a compilation using arguments as you would give on the command line, you can use the following:
This will write any diagnostics to the standard output stream, and return the exit code that '''vjetv''' would give when invoked from the command line.
You can use other methods on the com.ebay.vjo.tool.validator.IVjetValidator interface to handle diagnostics, control where files are read from and written to, and so on.
=== Interface ===
The args parameter represents any of the command line arguments that would normally be passed to the vjetv program and are outlined in the above Abstract section.
The out parameter indicates where the validator's diagnostic output is directed.
The return value is equivalent to the exit value from '''vjetv'''.
== Examples ==
=== Validating a Simple Program ===
One source file, Hello.java, defines a class called '''greetings.Hello'''. The greetings directory is the package directory both for the source file and the class file and is off the current directory. This allows us to use the default user class path. It also makes it unnecessary to specify a separate destination directory with '''-d'''.
=== Compiling Multiple Source Files ===
This example validates all the source files in the package greetings.
=== Specifying a User Class Path ===
Having changed one of the source files in the previous example, we re-validate it:
Since greetings.Hi refers to other classes in the greetings package, the compiler needs to find these other classes. The example above works, because our default user class path happens to be the directory containing the package directory. But suppose we want to recompile this file and not worry about which directory we're in? Then we need to add \examples to the user class path. We can do this by setting '''CLASSPATH''', but here we'll use the '''-classpath''' option.
If we change greetings.Hi again, to use a banner utility, that utility also needs to be accessible through the user class path.
To execute a class in greetings, we need access both to greetings and to the classes it uses.
=== Cross-Compilation Example ===
Here we use '''vjetv''' to compile code that will run on a 1.5 VJET runtime.% vjetv -jstarget 1.5 -bootclasspath JsNativeResource\1.5\JsNativeResource.jar -extdirs "" OldCode.js
The '''-target 1.5''' option ensures that the generated class files will be compatible with 1.5 VMs. By default, '''javac''' compiles for JDK 6.
The VJET Platform SDK's '''vjetv''' would also by default compile against its own bootstrap classes, so we need to tell '''vjetv''' to validate against SDK 1.5 bootstrap classes instead. We do this with '''-bootclasspath''' and '''-extdirs'''. Failing to do this might allow compilation against a VJET Platform API that would not be present on a 1.5 RT and would fail at runtime.
== Default Reporting Example (using Javac as example) ==
==== One Java file in one package: ====
Using the Java example of reporting errors here we can see some examples:
==== Two Java files in one package: ====
== Dependencies ==
The vjetv tool should only depend on the following:
# Java SE 1.6.
# DsfPrebuild - typespace, parser, and validation logic
# JsNativeResource - Js and DOM default data types
# VjoSelfDescribed library - VJET spec
== Integration ==
=== Java Main in Java Jar integration ===
Main-Class: com.ebay.vjo.tool.VjetV
java --jar vjetv.jar [ options ] [ sourcefiles ] [ @argfiles ]
This one is problematic since you need a batch job to wrap the location of the dependent jars. Using VJET_HOME we could simplify some of this. We want to have a completely independent version of VJETV without Eclipse.
Dependencies should not be increased at this level.
=== Eclipse 3.3\+ Integration Default ===
When someone installs VJET into Eclipse they should be able to run using the OSGI bundles for example:
eclipsec --application com.ebay.vjo.tool.VjetV [ options ] [ sourcefiles ] [ @argfiles ]
This will not require the java bootstrapping and classpath setup since the user has VJET UI already installed the command line can be accessed within the Eclipse environment and linking in the editor can be enabled to resources that have errors.
The dependencies in the Eclipse 3.3 integration should not use any eclipse workbench or UI functions. It must be able to start without UI and completely use the command line.
Dependencies can be increased to depend on the headless application plug-in registration.
=== Maven Build Integration ===
TBD
[[Category:VJET]]