Emulator Command Line Options

You can launch the emulator independent of the GUI using bin/emulator. The syntax is as follows:

emulator options

The syntax for the emulator command is as follows:

The general options are as follows:

• -classpath path

  -cp path

  Specifies a search path for application classes. The path consists of directories, ZIP files, and JAR files separated by colons.

• -Dproperty=value

  Sets a system property value.

• -help

  Display a list of valid options.

• -version

  Display version information about the emulator.

• -Xdevice:skin-name

  Run an application on the emulator using the given device instance name. See Device Names .

• -Xquery

  Print emulator skin information on the standard output stream and exit immediately. The information includes the skin name, screen size, and other capabilities.

emulator also supports MIDlet Options, and Debugging and Tracing Options.

MIDlet Options

Options for running MIDlets in the emulator are as follows:

• -Xautotest:JAD-file-URL

  Run in autotest mode. This option installs a MIDlet suite from a URL, runs it, removes it, and repeats the process. The purpose is to run test compatibility kits (TCKs) with the emulator, using a test harness such as JT Harness, JavaTest™ or Java Device Test Suite (JDTS). For example:

  emulator -Xautotest:http://localhost:8080/test/getNextApp.jad

  Given the above command, -Xautotest causes the emulator to repeatedly install, run, and remove the first MIDlet from the MIDlet suite provided through the HTTP URL. Once the emulator starts, it queries the test harness, which then downloads and installs the TCK MIDletAgent.

• -Xdescriptor:jad-file

  Install a MIDlet, run it, and uninstall it after it finishes.

• -Xdomain:domain-name

  Set the MIDlet suite’s security domain.

The Xjam argument runs an application remotely using the Application Management Software (AMS) to run OTA provisioning. If no application is specified with the argument, the graphical AMS is run.

• -Xjam:-Xjam:install=jad-file-url |force|list| [storageNames|StorageNumber]

  Installs the application with the specified JAD file onto a device.

  • force. If an existing application has the same storage name as the application to be installed, force removes the existing application before installing the new application.

  • list. List all the applications installed on the device and exit. The list is written to standard output before the emulator exits.

  • storageNames. List all applications installed on the device. The list is written to standard output before the emulator exits. Each line contains one storage name in numerical order. The list contains only the name so the order is important. For example the first storage name must be storage number 1.

• -xJam:run=[storage-name | storage-number]

  Run a previously installed application. The application is specified by its valid storage name or storage number.

• -xJam:remove=[storage-name | storage-number | all]

  Remove a previously installed application. The application is identified by its valid storage name or storage number. If all is supplied, all previously installed applications are removed.

• transient=jad-file-url

  Install, run, and remove the application with the specified JAD file. Specifying transient causes the application to be installed and run and then removed three times.

This example includes OTA installation:

emulator -Xjam:install=http://www.myserver.com/apps/MyApp.jad -Xdevice:DefaultCldcMsaPhone2

The above command returns the ID of the installed application. Once you obtain the ID you can run it with: emulator=Xjam:run=ID

See also Emulator Command Line Options and Debugging and Tracing Options.

Debugging and Tracing Options

You can use the following options with the emulator for debugging and tracing CLDC projects.

• -Xdebug

  Enable runtime debugging. The -Xrunjdwp option must be called to support -Xdebug.

• -Xrunjdwp:debug-settings

  Start a Java debug wire protocol session, as specified by a list of comma-separated debug settings. Both -Xrunjdwp and -Xdebug must be called.

  Valid debug settings include the following:

  • transport=transport-mechanism - Transport mechanism used to communicate with the debugger. The only transport mechanism supported is dt_socket.

  • address=host:port - Transport address for the debugger connection. If host is omitted, localhost is assumed to be the host machine.

  • server={y|n} - Starts the debug agent as a server. The debugger must connect to the port specified. The possible values are y and n. Currently, only y is supported (the emulator must act as a server).

  • suspend={y|n} - The possible values are y and n.

    When suspend is set to n, the application starts immediately and the debugger can be attached at any time during its run.

    When suspend is set to y, the application does not start until a debugger attaches to the debugging port and sends a resume command. This means that an application can be debugged from the very beginning.

• -Xverbose:trace-options

  Display trace output, as specified by a list of comma-separated options, as follows:

  • gc - Trace garbage collection

  • class - Trace class loading

  • all - Use all tracing options

See also MIDlet Options and Emulator Command Line Options.