<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY UTE "UTE">
]>

<sect1 id="ute_usage_standalone">
  <title>Standalone usage</title>
  <sect2 id="Overview">
    <title>Overview</title>
    <para>
      In the simplest case, UTE can be used standalone for quick execution of few tests with little configuration.
      If installed and configured with GTEE, it is enough to specify JDK location and test name (refer to
      <xref linkend="ute_usage_xrun"/>): UTE will correctly auto-detect settings, configure
      test harness (including different lists) and do the testing (provided that <code>xrun</code> has been set up properly,
      see <xref linkend="ute_xrun_setup"/>). Most of the settings can be overriden by additional options.
    </para>
    <para>
      <code>xrun</code> command uses <code>tlists</code> component configuration from GTEE to determine the component name
      for the test specified in the command line. This component name also determines how which lists are generated
      for <code>tlists</code> and how UTE configures the testrun, including the information about test harness, testbase
      and other locations (there is one configuration for each component).
    </para>
    <para>
      <code>run</code> command may be used in cases when automatic configuration is not necessary and all
      settings are specified in command line. Note that <code>xrun</code> command itself is implemented on
      top of <code>run</code> command.
    </para>
    <para>
      UTE is run directly from command line:
      <screen>
ute -jdk [jdk] -test [test] ...       (recommended, equivalent to xrun command)
ute xrun -jdk [jdk] -test [test] ...
ute run -harness [harness] ...
      </screen>
    </para>
    <para>
      Refer to 
      <itemizedlist>
        <listitem>
	  <xref linkend="ute_usage_xrun"/> for description of <code>xrun</code> command,
	</listitem>
        <listitem>
	  <xref linkend="ute_usage_run"/> for description of <code>run</code> command,
	</listitem>
        <listitem>
	  <xref linkend="ute_standalone_usage_examples"/> for list of examples of UTE usage,
	</listitem>
        <listitem>
	  <xref linkend="ute_harness_modules_common"/> for description of common command line options and settings,
	</listitem>
	<listitem>
	  Sections under <xref linkend="ute_harness_modules"/> for options and settings specific to harness module.
	</listitem>
      </itemizedlist>
    </para>
  </sect2>
  <sect2 id="ute_usage_xrun">
    <title>Usage of <code>xrun</code> command</title>
    <para>
      <code>xrun</code> command supports all common and harness-specific options (refer to 
      <xref linkend="ute_harness_modules_common"/> and subsequent sections). Note that the only
      required options are <code>-jdk</code> and <code>-test.</code> The values of other options
      are normally derived from <code>xrun</code> setup (refer to <xref linkend="ute_xrun_setup"/>).
    </para>
    <para>
      The current directory is used for results directory by default.
    </para>
    <para>
      In addition, the following options are supported:
      <table pgwide="1" id="ute_xrun_settings_table">
          <title><code>xrun</code> command options</title>
          <tgroup align="left" valign="top" cols="3">
            <colspec align="left" valign="top" name="Name"/>
            <colspec align="left" valign="top" name="Command line option"/>
            <colspec align="left" valign="top" name="Set by"/>
            <colspec align="left" valign="top" name="Default value"/>
            <colspec align="left" valign="top" name="Description"/>
            <thead>
              <row>
                <entry>Name</entry>
                <entry>Command line option</entry>
                <entry>Set by</entry>
                <entry>Default value</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>TLISTS</entry>
                <entry>-tlists</entry>
                <entry>user</entry>
                <entry></entry>
                <entry><code>tlists</code> processing mode</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
    </para>
    <para>
      Refer to <xref linkend="ute_standalone_usage_examples"/> for specific examples.
    </para>
  </sect2>
  <sect2 id="ute_usage_run">
    <title>Usage of <code>run</code> command</title>
    <para>
      <code>run</code> command also supports all common and harness-specific options (refer to
      <xref linkend="ute_harness_modules_common"/> and subsequent sections). However, unlike
      <code>xrun,</code> the values of these options have to be specified: nothing is derived
      from setup.
    </para>
  </sect2>
  <sect2 id="ute_standalone_usage_examples">
    <title>Examples of UTE standalone usage</title>
    <para>
      <itemizedlist>
        <listitem>
	  Run <code>vm</code> test <code>jit/Arrays/ArrayBounds</code> with JDK 6u10:
<screen>
ute -jdk /net/vmsqe.russia/export/jdk/6/build/u10/solaris-i586 -test jit/Arrays/ArrayBounds
</screen>
	</listitem>
	<listitem>
	  Run <code>vm</code> test <code>nsk/logging/ConsoleHandler/close/close001</code> from VM testbase 1.5 with JDK 6u10 in <code>comp</code> mode with <code>-XX:CompileThreshold=2</code> option:
<screen>
ute -jdk /net/vmsqe.russia/export/jdk/6/build/u10/solaris-i586 -test nsk/logging/ConsoleHandler/close/close001 \
-testbase /net/vmsqe.russia/export/testbase/sqe/vm/1.5/build/execution/vm -vmmode comp -vmopts -XX:CompileThreshold=2
</screen>
	</listitem>
	<listitem>
	  Run JavaSE (regression) test with JDK 6u10, 64-bit mode and <code>-server -Xint</code> options:
<screen>
ute -jdk /net/vmsqe.russia/export/jdk/6/build/u10/solaris-amd64 -test closed/compiler/6724218/Test.java -bits d64 -vmopts '-server -Xint'
</screen>
	</listitem>
	<listitem>
	  Run <code>runThese</code> <code>quick</code> suite with JDK 6u10:
<screen>
ute run -jdk /net/sqenfs-1.sfbay/export1/comp/vm/jdk/re/6u10/latest/binaries/linux-i586 -test runThese/quick
</screen>
	</listitem>
	<listitem>
	  Run tests with <code>rtj/dtrace/</code> prefix (from <code>realtime</code> testbase):
<screen>
ute -jdk /net/vmsqe.russia/export/jdk/rtj/2.1/build/b11/solaris-i586 -test rtj/dtrace/
</screen>
	</listitem>
	<listitem>
	  Run <code>dtrace/DTrace_rtsjProvider.java</code> from Java RTS testbase:
<screen>
ute -jdk /net/mackdrive.france/export/jrts_sqe/jdk/rtj/2.1/build/b11/solaris-i586/ -test dtrace/DTrace_rtsjProvider.java
</screen>
	</listitem>
	<listitem>
	  Run 2 iterations of <code>specjvm98 (refworkload)</code>
<screen>
ute run -harness refworkload -testbase /net/vmsqe.russia/export/testbase/refworkload \
-jdk /net/vmsqe.russia/export/jdk/rtj/2.1/build/b11/solaris-i586 -results . -benchmark specjvm98 -iterations 2
</screen>
	</listitem>
	<listitem>
	  Run 10 minutes of <code>Tomcat</code> bigapp:
<screen>
ute run -harness bigapps -testbase /net/vmsqe.russia/export/testbase/bigapps/Tomcat/apache-tomcat-5.5.26 \
-jdk /net/vmsqe.russia/export/jdk/rtj/2.1/build/b11/solaris-i586 -results . \
-runbigapp /net/vmsqe.russia/export/tool/runbigapp.sh -bigapp Tomcat -duration 10
</screen>
	</listitem>
      </itemizedlist>
    </para>
  </sect2>
  <sect2 id="ute_run_setup">
    <title>UTE setup for <code>run</code> command</title>
    <para>
      The following steps are required for UTE installation. These steps are only needed
      for standalone UTE. If UTE is installed as part of GTEE <code>(UTE_HOME = $GTEE_HOME/harness/ute),</code>
      it may be used as is without additional setup.
      <itemizedlist>
        <listitem>
	  Put UTE to a directory <code>(UTE_HOME)</code> either by unpacking it,
	  or by checking out from repository.
	</listitem>
	<listitem>
	  Ensure that <code>UTE_HOME/stable-jdk</code> points to directory with
	  binaries for stable JDK.
	</listitem>
	<listitem>
	  <code>etc/?</code>
	</listitem>
      </itemizedlist>
    </para>
  </sect2>
  <sect2 id="ute_xrun_setup">
    <title>UTE setup for <code>xrun</code> command</title>
    <para>
      Setup for UTE command <code>xrun</code> requires effort and knowledge of test configuration for particular component and
      locations for particular site.
    </para>
    <para>
      For each component, there is a component script under <ulink url="../../../etc/component/"><code>$UTE_HOME/etc/component</code></ulink>
      subdirectory which is sourced in context of <code>xrun</code> command once the component is determined (and has access to UTE internal
      variables). The script is responsible for configuring any additional settings for the component. At least <code>HARNESS</code> and
      <code>TESTBASE</code> and mandatory settings for the harness should be set.
    </para>
    <para>
      It is recommended for the component script to set most of the values to make it easier for users: any settings will not set have to be
      set by the user in the command line for each run.
    </para>
    <para>
      Note that the settings may depend on JDK release being tested: the value is accessible as <code>jdk_release</code> variable.
    </para>
    <para>
      Note that GTEE includes common configurations for most components
      (under <ulink url="../../../../../site/common/etc/ute/component/"><code>site/common/etc/ute</code></ulink>)
      which assumes certain structure of directories for particular site.
      and allow to define only base directory.
    </para>
  </sect2>
</sect1>
