Getting Started with DRL

The Dynamic Runtime Layer (DRL) is a clean-room implementation of the Java* 2 Platform, Standard Edition (J2SE*) 1.5.0. The design keystones of the DRL virtual machine (VM) are clarity of concept, modularity, extensibility, and competitive performance. This document describes the first version of DRL deployed in March 2006.

To quickly start with DRL, walk through the provided scenarios. It is recommended that you strictly follow the instructions of this guide to ensure system stability and anticipated results.

Overview

Before You Start

Running an Application

Running an Application in Eclipse

Debugging an Application in Eclipse

Command-line Options

Disclaimer and Legal Information

Overview

In the Getting Started document, the first scenario illustrates running an application with DRL, and the two others demonstrate running and debugging an application in the Eclipse* integrated development environment. DRL is used to run both Eclipse* and the new application. After completing this guide, you will be able to run and debug your own applications with DRL.

Before You Start

By following the instructions in the README.txt file, install DRL and run acceptance tests to make sure that the installation is complete. You will have the default configuration installed on your system. To change the default DRL settings, use the Command-line Options listed in this document.

Notations Conventions

When following the scenarios described below, please make the following adjustments:

Back to top

Running an Application

This scenario provides step-by-step instructions on running the Hello application in the Windows* or the Linux* console. The scenario uses the Hello.class Java* class distributed with the product as the sample Java* application.

  1. To start DRL, change your current directory to the <installation folder>\bin directory.
  2. Check that you have files ij.exe on Windows* or ij on Linux* and Hello.class in the \bin directory.
    On Linux*, make sure that you can run applications and load dynamic libraries from the current directory. For example:
    export PATH=.:${PATH}
    export LD_LIBRARY_PATH=${PWD}:${LD_LIBRARY_PATH}
    If you are using the Intel(R) C++ compiler, make sure the LD_LIBRARY_PATH contains location of the ICC libraries.
  3. Run the Hello application by entering:
    ij Hello
    

    You will see “Hello World!" printed on the screen. This means that you have successfully launched the virtual machine, and that it has processed the Hello.class Java* class to execute the Hello application.

Back to top

Running an Application in Eclipse

This scenario provides step-by-step instructions on running a Java application in the Eclipse* environment. In the scenario, you will launch Eclipse*, create a new project and a new Java class within this project, and finally you will run the new application.

  1. Download the Eclipse* 3.1.1 package at http://download.eclipse.org/eclipse/downloads/, and unpack this distribution.
  2. Set the environment variable ECLIPSE_HOME to point to the location of the Eclipse* installation directory.
    On Linux*, if you are using the Intel(R) C++ compiler, additionally set the LD_LIBRARY_PATH variable to point to the location of the ICC libraries.
  3. On Windows*, edit the Eclipse* launch script <installation folder>/bin/eclipse.bat: make sure that BUILD_HOME variable points to the <installation folder>.
  4. Start Eclipse* by launching Eclipse starter script:
    on Windows*: <installation folder>/bin/eclipse.bat;
    on Linux*: <installation folder>/bin/eclipse.sh.
  5. After running Eclipse* starter script, the Workspace Launcher dialog opens. Specify the path to your workspace directory. In the example, click OK to set the default path.

    Specifying the Workspace directory for the Project

  6. The Welcome page of the Eclipse* environment opens. Close the window to proceed.
  7. Create a new project via File > New > Project…

    The New project dialog appears. Select Java Project, click Next and type the project name in the New Java Project field, in the example, Hello. Then click the Finish button.

    Dialog: New Java Project with Default Settings

    When prompted to switch to the Java Perspective, click Yes.

  8. The Package Explorer tab opens in the left-hand part of the workspace with the name of your project displayed.

    Eclipse Platform Workspace with the Package Explorer and the Hello Class

  9. Create a new class via File > New > Class

    The New Java Class wizard opens. Type in the class name, in the example, HelloWorld and select the public static void main(String[] args) check box at the bottom of the dialog window.

    Dialog New Java Class with Settings Configured as Required

  10. You have created the HelloWorld class. The workspace gets updated with the class information as shown below.

    In the Package Explorer window, you can see that the class is in the default package. The Outline window displays the one method of this class: the main method with an array of String parameters.

    Workspace with the HelloWorld.java Class conent Displayed

  11. In the body of the main method, type in the following:
    int i=18;
    System.out.println("Hello World");
    
  12. Save this file via File > Save.
  13. Run the HelloWorld class: right click HelloWorld.java in the Package Explorer tab and go Run > Java Application.

    running Java Application Dialog

    The result of the execution is printed out in the Console tab at the bottom of the page: "Hello World!" is printed.

    Result of Application Execution printed out

  14. To close Eclipse*, go File > Exit and then click OK.

Back to top

Debugging an Application in Eclipse

This scenario provides instructions on how to debug a simple application in Eclipse*.

  1. Repeat steps 1 to 11 of the previous scenario to set up the workspace and create a new class in the new project.
  2. Setup the breakpoint. Place the cursor at the following line:
    System.out.println ("Hello World!");
    

    Go Run > Toggle Line Breakpoint.

    Menu Item for Inserting the Toggle Line Breakpoint

    A blue circle appears on the left border of the HelloWorld.java tab.

    HelloWorld.java class content selected

  3. Start the debug operation.
    1. Right-click HelloWorld.java in the Package Explorer tab and and go Debug As > Debug... . The Debug window appears.
    2. Go to Java Application in the left tab and select the HelloWorld application configuration. If this configuration is not listed, click New. The configuration details of the HelloWord application appear on the right side of the workspace.
    3. Select the Arguments pane and type -Xint in the VM arguments field.
    4. Press the Debug button to start the debug operation. You will be prompted to switch to the debug perspective. Click Yes.

Menu Item for Debugging a Java Application

  1. The workspace gets updated.

    The Debug tab appears in the top right-hand corner with the main method selected on line 18 in the HelloWorld class. The Variables tab also appears with the values of local variables i and args.

    Code Highlighted

  2. To finish the HelloWorld application, go Run > Resume.
    When the application has finished, the Debug and the Console tab get updated. The Console tab at the bottom displays the result of execution: Hello World!

    Code Highlighted

  3. Close Eclipse* via File > Exit and then click OK.

Back to top

Supported Command-line Options

Supported Standard Options

Use the standard supported options listed in this section to apply custom configuration settings to your system.

-classpath and -cp specify the class search path for directories and .zip and .jar files.

Note

Multiple values for directories and file locations go in a list separated by the character “:” on Linux* and the character “;” on Windows*.

-D<name>=<value> sets the system property to be accessible for the user application through the java.lang.System class.

-showversion prints the product version and continues execution.

-version prints the product version and exits.

-fullversion prints the full product version and exits.

-verbose [:class|:gc|:jni] enables verbose output.

-agentlib:<library name>[=<agent options>] loads the JVMTI agent library. The library name is platform-independent.

-agentpath:<library name>[=<agent options] loads the JVMTI agent library. The library name is platform-dependent.

-verify triggers full bytecode verification. Minimal verification is performed even without this option specified.

-? and -help print the help message.

-X prints help information on non-standard options.

-jar <jar file> specifies the name of the archive containing the class and resource files for the application, with the startup class indicated in the manifest file.

Supported Non-Standard Options

Below supported non-standard options are grouped by their functionality.

Virtual Machine Options

Use these command-line options to further configure DRLVM.

Common Virtual Machine Options

-Xbootclasspath:<PATH> sets the boot class path to the specified value.

-Xbootclasspath/a:<PATH> appends the specified directories and files to the boot class path.

-Xbootclasspath/p:<PATH> prepends the specified directories and files to the boot class path.

-Xstats <mask> generates various statistics.

-Xdebug does nothing, is a compatibility option.

-Xnoagent does nothing, is a compatibility option.

-Xrun does the same as the -agentlib option for backward compatibility with JVMDI.

-Xverbose[:<category>[:<file>] switches on logging for a specified category and logs that category to a file.

-Xwarn[:<category>[:<file>] switches off verbose logging off for a specified category and logs that category to a file.

-Xverboseconf:<file> sets up logging via the log4cxx configuration file.

-Xverboselog:<file> logs verbose output to a file.

Memory Heap Options

-Xms<size> sets the Java* heap size.

-Xmx<size> sets the maximum Java* heap size, for example:

-Xms80m
-Xmx60000000

Logging Options

-Xfileline adds source information to logging messages.

-Xthread adds the thread ID to logging messages.

-Xcategory adds the category name to logging messages.

-Xtimestamp adds the timestamp to logging messages.

-Xfunction adds the function signature to logging messages.

-Xlog[:<category>[:<file>] switches on debug logging for a specified category and logs that category to a file.

-Xtrace[:<category>[:<file>] switches on trace logging for a specified category and logs that category to a file.

Execution Manager Options

-Xem jet:[<path to JIT library>] runs the virtual machine with a single baseline just-in-time compiler.

-Xem opt:[<path to JIT library>] runs the virtual machine with a single optimizing just-in-time compiler.

-verbose:em prints detailed information on execution management.

Other

-Xint enables using the interpreter to execute the program.

-Xem <em options> specifies the execution manager specific options.

-Xdll <dll name> indicates a specific .dll file.

-Xno_parallel_jit prohibits compilation in the parallel mode.

-Xdumpfile <file> specifies the file name for the dump.

Just-in-time Compiler Options

Use the following command-line options to configure operation of the optimizing just-in-time compiler.

–Xem opt: -Xjit LOG=\"root=all\" enables the single-JIT mode for the optimizing JIT compiler and logs all information to stdout.

–Xem opt: -Xjit LOG=\"root=ir,file\" does the same as above and dumps the intermediate representation (IR) logs to file system.

–Xem opt: -Xjit LOG=\"filter=file:\" generates a list of JIT-compiled methods into the file named file.

–Xem opt: -Xjit LOG=\"opt=ir,file,filter=file:1-3\" dumps the high-level representation (HIR) of the first three methods from the file file (generated by the previous option).

–Xem opt: -Xjit METHODS=\"file:1-3\" -Xjit ia32::itrace=on traces, that is, logs to stdout, entries and exits to and from the first three methods from the file file.

–Xem opt: -Xjit opt::skip=off –Xjit tra::guardedInlining=off enables all high-level optimizations and disables translation-time guarded inlining.

–Xem opt: -Xjit opt::skip=off –Xjit tra::guardedInlining=off -Xjit LOG=\"root=ir,file,filter=java/lang/Object::\" -Xjit opt::dumpdot=on -Xjit ia32::dumpdot=on enables printing methods intermediate representations in the form of .dot files after major high- and low-level IR transformation stages. The resulting .dot files can be converted to a graphical representation. With these settings, only methods of the Object class are logged.

Note

General syntax of the JIT log system options is the following:

 -Xjit LOG=\"[file|singlefile][filter=filter_expression]{<category_name> =<log_level>}\"

Garbage Collection Options

-Xgc fixed runs GC in a non-moving mode.

Disclaimer and Legal Information

(C) Copyright 2005-2006 Intel Corporation

(C) Copyright 2005-2006 The Apache Software Foundation or its licensors, as applicable.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Portions, Copyright © 1991-2005 Unicode, Inc. The following applies to Unicode.

COPYRIGHT AND PERMISSION NOTICE

Copyright © 1991-2005 Unicode, Inc. All rights reserved. Distributed under the Terms of Use in http://www.unicode.org/copyright.html. Permission is hereby granted, free of charge, to any person obtaining a copy of the Unicode data files and any associated documentation (the "Data Files") or Unicode software and any associated documentation (the "Software") to deal in the Data Files or Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Data Files or Software, and to permit persons to whom the Data Files or Software are furnished to do so, provided that (a) the above copyright notice(s) and this permission notice appear with all copies of the Data Files or Software, (b) both the above copyright notice(s) and this permission notice appear in associated documentation, and (c) there is clear notice in each modified Data File or in the Software as well as in the documentation associated with the Data File(s) or Software that the data or software has been modified.

THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA FILES OR SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in these Data Files or Software without prior written authorization of the copyright holder.

2. Additional terms from the Database:

Copyright © 1995-1999 Unicode, Inc. All Rights reserved.

Disclaimer

The Unicode Character Database is provided as is by Unicode, Inc. No claims are made as to fitness for any particular purpose. No warranties of any kind are expressed or implied. The recipient agrees to determine applicability of information provided. If this file has been purchased on magnetic or optical media from Unicode, Inc., the sole remedy for any claim will be exchange of defective media within 90 days of receipt. This disclaimer is applicable for all other data files accompanying the Unicode Character Database, some of which have been compiled by the Unicode Consortium, and some of which have been supplied by other sources.

Limitations on Rights to Redistribute This Data

Recipient is granted the right to make copies in any form for internal distribution and to freely use the information supplied in the creation of products supporting the UnicodeTM Standard. The files in the Unicode Character Database can be redistributed to third parties or other organizations (whether for profit or not) as long as this notice and the disclaimer notice are retained. Information can be extracted from these files and used in documentation or programs, as long as there is an accompanying notice indicating the source.

Back to top

 

* Other brands and names are the property of their respective owners.

Last update: March'31 2006