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