help.py revision babb65232cbb7de2365d117f3593cdea8a263f05 
1# Copyright 2011 Google Inc. All Rights Reserved.
2"""Module to print help message."""
3
4from __future__ import print_function
5
6import sys
7import textwrap
8from settings_factory import BenchmarkSettings
9from settings_factory import GlobalSettings
10from settings_factory import LabelSettings
11
12
13class Help(object):
14  """The help class."""
15
16  def GetUsage(self):
17    return """%s [OPTIONS] EXPERIMENT_FILE""" % (sys.argv[0])
18
19  def _WrapLine(self, line):
20    return '\n'.join(textwrap.wrap(line, 80))
21
22  def _GetFieldDescriptions(self, fields):
23    res = ''
24    for field_name in fields:
25      field = fields[field_name]
26      res += 'Field:\t\t%s\n' % field.name
27      res += self._WrapLine('Description:\t%s' % field.description) + '\n'
28      res += 'Type:\t\t%s\n' % type(field).__name__.replace('Field', '')
29      res += 'Required:\t%s\n' % field.required
30      if field.default:
31        res += 'Default:\t%s\n' % field.default
32      res += '\n'
33    return res
34
35  def GetHelp(self):
36    global_fields = self._GetFieldDescriptions(GlobalSettings('').fields)
37    benchmark_fields = self._GetFieldDescriptions(BenchmarkSettings('').fields)
38    label_fields = self._GetFieldDescriptions(LabelSettings('').fields)
39
40    return """%s is a script for running performance experiments on
41ChromeOS. It allows one to run ChromeOS Autotest benchmarks over
42several images and compare the results to determine whether there
43is a performance difference.
44
45Comparing several images using %s is referred to as running an
46"experiment". An "experiment file" is a configuration file which holds
47all the information that describes the experiment and how it should be
48run. An example of a simple experiment file is below:
49
50--------------------------------- test.exp ---------------------------------
51name: my_experiment
52board: x86-alex
53remote: chromeos2-row1-rack4-host7.cros 172.18.122.132
54
55benchmark: page_cycler_v2.morejs {
56  suite: telemetry_Crosperf
57  iterations: 3
58}
59
60my_first_image {
61  chromeos_image: /usr/local/chromeos-1/chromiumos_image.bin
62}
63
64my_second_image {
65  chromeos_image:  /usr/local/chromeos-2/chromiumos_image.bin
66}
67----------------------------------------------------------------------------
68
69This experiment file names the experiment "my_experiment". It will be
70run on the board x86-alex. Benchmarks will be run using two remote
71devices, one is a device specified by a hostname and the other is a
72device specified by it's IP address. Benchmarks will be run in
73parallel across these devices.  There is currently no way to specify
74which benchmark will run on each device.
75
76We define one "benchmark" that will be run, page_cycler_v2.morejs. This
77benchmark has two "fields", one which specifies that this benchmark is
78part of the telemetry_Crosperf suite (this is the common way to run
79most Telemetry benchmarks), and the other which specifies how many
80iterations it will run for.
81
82We specify one or more "labels" or images which will be compared. The
83page_cycler_v2.morejs benchmark will be run on each of these images 3
84times and a result table will be output which compares them for all
85the images specified.
86
87The full list of fields that can be specified in the experiment file
88are as follows:
89=================
90Global Fields
91=================
92%s
93=================
94Benchmark Fields
95=================
96%s
97=================
98Label Fields
99=================
100%s
101
102Note that global fields are overidden by label or benchmark fields, if
103they can be specified in both places. Fields that are specified as
104arguments override fields specified in experiment files.
105
106%s is invoked by passing it a path to an experiment file,
107as well as any options (in addition to those specified in the
108experiment file).  Crosperf runs the experiment and caches the results
109(or reads the previously cached experiment results out of the cache),
110generates and displays a report based on the run, and emails the
111report to the user.  If the results were all read out of the cache,
112then by default no email is generated.
113""" % (sys.argv[0], sys.argv[0], global_fields, benchmark_fields, label_fields,
114       sys.argv[0])
115