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