diff options
| author | Michael Larabel <michael@phx-laptop.(none)> | 2008-05-30 17:37:34 -0400 |
|---|---|---|
| committer | Michael Larabel <michael@phx-laptop.(none)> | 2008-05-30 17:37:34 -0400 |
| commit | a39a09c8166e49708dbc63e961420596def2875f (patch) | |
| tree | 425e032dd36baea631cc92cd290383c815438947 | |
| parent | 1d5a4bc8b76e64c8464ccc69fb49ab801f6dd1cf (diff) | |
| download | phoronix-test-suite-upstream-a39a09c8166e49708dbc63e961420596def2875f.tar.gz phoronix-test-suite-upstream-a39a09c8166e49708dbc63e961420596def2875f.tar.xz phoronix-test-suite-upstream-a39a09c8166e49708dbc63e961420596def2875f.zip | |
Another Documentation Push
| -rw-r--r-- | documentation/credits.html | 29 | ||||
| -rw-r--r-- | documentation/includes/pts-documentation.css | 91 | ||||
| -rw-r--r-- | documentation/includes/pts-documentation.png | bin | 0 -> 4675 bytes | |||
| -rw-r--r-- | documentation/index.html | 54 | ||||
| -rw-r--r-- | documentation/pts_options.html | 143 | ||||
| -rw-r--r-- | documentation/specifications_xml_download.html | 43 | ||||
| -rw-r--r-- | documentation/specifications_xml_suite.html | 65 | ||||
| -rw-r--r-- | documentation/specifications_xml_test.html | 220 | ||||
| -rw-r--r-- | documentation/txt/guide-write-test-profile.txt | 83 | ||||
| -rw-r--r-- | documentation/txt/specification-test-downloads.txt | 34 | ||||
| -rw-r--r-- | documentation/txt/specification-test-profile.txt | 226 | ||||
| -rw-r--r-- | documentation/txt/specification-test-suite.txt | 65 | ||||
| -rw-r--r-- | documentation/writing_your_first_test.html | 122 | ||||
| -rwxr-xr-x | phoronix-test-suite | 4 | ||||
| -rw-r--r-- | pts-core/pts-run-cmd.php | 2 |
15 files changed, 1178 insertions, 3 deletions
diff --git a/documentation/credits.html b/documentation/credits.html new file mode 100644 index 0000000..09ccb93 --- /dev/null +++ b/documentation/credits.html @@ -0,0 +1,29 @@ +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<Title>Phoronix Test Suite - Credits</Title> +<link href="includes/pts-documentation.css" rel="stylesheet" type="text/css" /> +</head> +<body> +<div id="pts_doc_header"><div class="pts_doc_fixed"><div id="pts_doc_logo"></div></div></div> +<div class="pts_doc_fixed"> +<div class="pts_doc_notice"><div style="float: left"><a href="index.html"><< Documentation Home</a></div><div style="float: right;">Credits</div></div> +<div class="pts_doc_main"> +<!-- PTS AREA --> +<h1>Phoronix Test Suite</h1> +<div style="width: 1px; height: 20px;"></div> +<p>The phoronix-test-suite, pts_Graph, and tandem_Xml are open-source projects by <a href="http://www.phoronixmedia.com/">Phoronix Media</a>.</p> +<p>The default font that ships with the Phoronix Test Suite for the results graphing is from the Liberation (GPL-licensed) font collection from <a href="https://www.redhat.com/promo/fonts/">Red Hat</a>.</p> +<h2>Lead Developers</h2> +<p>- Michael Larabel</p> +<p>- Wuppermann</p> +<p>- Andrew Schofield</p> +<h2>Special Thanks To</h2> +<p>- Pekka Panula</p> +<p>- Stefan Doesinger</p> +<p>- Jörg Schirottke</p> +<p>- Laminar Research / Ben Supnik</p> +<p>- Peter Kraus</p> +<!-- END OF PTS AREA --> +</div></div><div class="pts_doc_fixed"><div class="pts_doc_bottom"><div style="float: left;"><a href="http://www.phoronix-test-suite.com/">Phoronix-Test-Suite.com</a></div><div style="float: right;">Copyright © 2008 by <a href="http://www.phoronixmedia.com/">Phoronix Media</a>.</div></div></div> +</body> +</html> diff --git a/documentation/includes/pts-documentation.css b/documentation/includes/pts-documentation.css new file mode 100644 index 0000000..c70d763 --- /dev/null +++ b/documentation/includes/pts-documentation.css @@ -0,0 +1,91 @@ +body +{ + text-align: center; + margin: 0; + padding: 0; + font-family: arial, helvetica, sans-serif; + font-size: 13px; + background-color: #F9F9F9; + color: #000; +} +a +{ + color: #3B433A; +} +div#pts_doc_header +{ + width: 100%; + margin: 0; + background-color: #000; +} +div#pts_doc_logo +{ + width: 255px; + height: 70px; + padding: 1px; + background: #000 url(pts-documentation.png) no-repeat; + position: relative; + left: 452px; +} +div.pts_doc_fixed +{ + width: 700px; + margin: 0 auto; +} +div.pts_doc_main +{ + border: solid #737373; + border-width: 0 1px; + text-align: left; + padding: 30px 20px; + min-height: 670px; +} +div.pts_doc_notice +{ + border: solid #737373; + border-width: 0 1px; + background-color: #4e4e4e; + text-align: left; + overflow: hidden; + padding: 4px 8px; + color: #FFF; + font-weight: bold; +} +div.pts_doc_bottom +{ + background-color: #000; + color: #FFF; + text-align: left; + padding: 3px 8px; + font-size: 12px; + overflow: hidden; +} +div.pts_doc_bottom a, div.pts_doc_notice a +{ + color: #FFF; + text-decoration: none; +} +h3 +{ + text-indent: 30px; +} +h3 a +{ + text-decoration: none; +} +div.pts_doc_bottom a:hover, div.pts_doc_notice a:hover, h3 a:hover +{ + text-decoration: underline; +} +h1 +{ + font-size: 22px; +} +h2 +{ + font-size: 18px; +} +h3 +{ + font-size: 15px; +} diff --git a/documentation/includes/pts-documentation.png b/documentation/includes/pts-documentation.png Binary files differnew file mode 100644 index 0000000..40962e2 --- /dev/null +++ b/documentation/includes/pts-documentation.png diff --git a/documentation/index.html b/documentation/index.html new file mode 100644 index 0000000..e64ce75 --- /dev/null +++ b/documentation/index.html @@ -0,0 +1,54 @@ +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<Title>Phoronix Test Suite</Title> +<link href="includes/pts-documentation.css" rel="stylesheet" type="text/css" /> +</head> +<body> +<div id="pts_doc_header"><div class="pts_doc_fixed"><div id="pts_doc_logo"></div></div></div> +<div class="pts_doc_fixed"> +<div class="pts_doc_notice"><div style="float: right;">Documentation</div></div> +<div class="pts_doc_main"> +<!-- PTS AREA --> +<h1>Phoronix Test Suite</h1> +<div style="width: 1px; height: 20px;"></div> +<h2>Welcome</h2> +<p>Phoronix Test Suite 1.0 (codenamed "Trondheim") is the most comprehensive testing and +benchmarking platform available for Linux and is designed to carry out qualitative +and quantitative benchmarks in a clean, reproducible, and easy-to-use manner. +This software is based upon the internal tools and extensive Linux benchmarking +work done by <a href="http://www.phoronix.com/">Phoronix.com</a> since 2004, with +input from tier-one computer hardware vendors. This software is open-source and +licensed under the <a href="http://www.gnu.org/licenses/quick-guide-gplv3.html">GNU +GPLv3</a> and consists of a lightweight framework (<em>pts-core</em>) with each benchmark consisting +of an XML-based profile with related utility scripts. The process from the benchmark +installation, to the actual benchmarking, to the parsing of important hardware +and software components is heavily automated and completely repeatable, asking +users only for confirmation of actions.</p> +<p>The Phoronix Test Suite can be used for simply comparing your +computer's performance with your friends and co-workers or can also be used at +your company for internal quality assurance purposes under Linux. Results from +the Phoronix Test Suite are displayed in a results viewer with optional support +for uploading them to <a href="http://global.phoronix-test-suite.com/">PTS Global</a>. +PTS Global allows you to browse all uploaded results, search these results, and comparing other results against your own system.</p> +<p>If you're interested in getting involved with the Phoronix Test +Suite as either a developer, profile/suite maintainer for your favorite software +package(s) (or other software that you develop), or support for your company, please contact <em>phoronix [at] phoronix.com</em>.</p> +<p>Additionally, there are the <a href="http://www.phoronix.com/forums/forumdisplay.php?f=49">Phoronix Test Suite Forums</a> for support questions and related discussions as well as the <a href="http://phoronix-test-suite.com/mailman/listinfo/trondheim-pts_phoronix-test-suite.com">Phoronix Test Suite mailing list</a>.</p> +<h2>Documentation</h2> +<h3><a href="pts_options.html">Explanation Of User Options</a></h3> +<h3><a href="writing_your_first_test.html">Writing Your First Test Profile</a></h3> +<h3><a href="10_press_release.html">1.0 Press Release</a></h3> +<h3><a href="credits.html">Development Credits</a></h3> +<h2>XML Syntax / Specifications</h2> +<h3><a href="specifications_xml_test.html">Test Profile</a></h3> +<h3><a href="specifications_xml_download.html">Downloads Profile</a></h3> +<h3><a href="specifications_xml_suite.html">Suite Profile</a></h3> +<h2>Relevant Links</h2> +<h3><a href="http://www.phoronix-test-suite.com/">Phoronix-Test-Suite.com</a></h3> +<h3><a href="http://www.phoronix.com/">Phoronix.com</a></h3> +<h3><a href="http://www.phorogit.com/index.php?p=phoronix-test-suite.git">Git Development Repository</a></h3> +<h3><a href="http://global.phoronix-test-suite.com/">PTS Global</a></h3> +<!-- END OF PTS AREA --> +</div></div><div class="pts_doc_fixed"><div class="pts_doc_bottom"><div style="float: left;"><a href="http://www.phoronix-test-suite.com/">Phoronix-Test-Suite.com</a></div><div style="float: right;">Copyright © 2008 by <a href="http://www.phoronixmedia.com/">Phoronix Media</a>.</div></div></div> +</body> +</html> diff --git a/documentation/pts_options.html b/documentation/pts_options.html new file mode 100644 index 0000000..5ebed3e --- /dev/null +++ b/documentation/pts_options.html @@ -0,0 +1,143 @@ +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<Title>Phoronix Test Suite - Phoronix Test Suite Options</Title> +<link href="includes/pts-documentation.css" rel="stylesheet" type="text/css" /> +</head> +<body> +<div id="pts_doc_header"><div class="pts_doc_fixed"><div id="pts_doc_logo"></div></div></div> +<div class="pts_doc_fixed"> +<div class="pts_doc_notice"><div style="float: left"><a href="index.html"><< Documentation Home</a></div><div style="float: right;">Phoronix Test Suite Options</div></div> +<div class="pts_doc_main"> +<!-- PTS AREA --> +<h1>Phoronix Test Suite Options</h1> +<h2>Installation Options</h2> +<p><strong>install <To Install></strong></p> +<p>This option will install the selected test(s) inside the testing environment +directory (defaults to ~/.phoronix-test-suite/installed-tests). The install process +from downloading of the test files to the installation is fully automated. The +install option needs to be supplied with the test name or suite as an argument. +Optionally, a PTS Global ID or the name of a saved results file can be supplied +as well and the test(s) to install will automatically be extracted from that information. +If the test is already installed and was ran by the latest version of the installation +process, no action will be taken.</p> +<p><strong>install-dependencies <To Install></strong></p> +<p>This option will install the external dependencies needed by the selected test(s) +using the distribution's package management system. For example, some tests depend +upon GCC for compiling code. If GCC is not detected on the system, the Phoronix +Test Suite will attempt to install GCC using the distribution's package management +system. If you're running this command as a local user, you may be prompted for +the root password while the process is running. The distributions supported at +this time are CentOS, Fedora, Mandriva Linux, and Ubuntu. For unsupported distributions, +the dependency names will be displayed along with common names for the package. +The install-dependencies option needs to be supplied with the test name or suite +as an argument. Optionally, a PTS Global ID or the name of a saved results file +can be supplied as well and the external dependencies will automatically be extracted +from that information. The install-dependencies option will only install the dependencies +on tests that utilize this feature. When using the install option, the external +dependencies are automatically checked.</p> +<p><strong>install-all</strong></p> +<p>This option will install all available test(s) inside the testing environment +directory (defaults to ~/.phoronix-test-suite/installed-tests). The install process +from downloading of the test files to the installation is fully automated.</p> +<p><strong>list-installed-tests</strong></p> +<p>This option will list all tests that have been installed by the Phoronix Test +Suite.</p> +<h2>Testing Options</h2> +<p><strong>benchmark <To Run></strong></p> +<p>This option will install the selected test(s) (if needed) and will proceed +to run the test(s). This option is equivalent to running phoronix-test-suite with +the install option followed by the run option. The name of the test or suite must +be supplied or the PTS Global ID or saved local file name.</p> +<p><strong>run <To Run></strong></p> +<p>This option will run the selected test(s). The name of the test or suite must +be supplied or the PTS Global ID or saved local file name.</p> +<p><strong>list-tests</strong></p> +<p>This option will list all available tests. The name, title, status, and license +are displayed for each test.</p> +<p><strong>list-suites</strong></p> +<p>This option will list all available test suites. The name, title, and type +are displayed for each suite.</p> +<h2>Batch Testing Options</h2> +<p><strong>batch-setup</strong></p> +<p>This option is used to configure the batch mode options for the Phoronix Test +Suite, which is subsequently written to the user configuration file. Among the +options are whether to automatically upload the test results to PTS Global and +prompting for the saved file name.</p> +<p><strong>batch-run <To Run></strong></p> +<p>This option and its arguments are equivalent to the run option, but the process +will be ran in the Phoronix Test Suite batch mode.</p> +<p><strong>batch-benchmark <To Run></strong></p> +<p>This option and its arguments are equivalent to the benchmark option, but the +process will be ran in the Phoronix Test Suite batch mode.</p> +<h2>Result Viewing Options</h2> +<p><strong>list-results</strong></p> +<p>This option will list all saved results. The file name, title, test(s) performed, +and result identifiers are displayed.</p> +<p><strong>show-result <To Show></strong></p> +<p>This option will show the test results of the selected file (set as the first +argument) in the default web browser.</p> +<p><strong>remove-result <To Remove></strong></p> +<p>This option will permanently remove the saved file reset that is set as the +first argument.</p> +<p><strong>remove-all-results</strong></p> +<p>This option will permanently remove all saved results.</p> +<p><strong>merge-results <To Merge> <To Merge> <To Save As></strong></p> +<p>This option will manually merge two sets of test results generated by the Phoronix +Test Suite. The merged results will then be saved to a new file if the targeted +save name is specified as the third argument otherwise the results will be re-saved +to first file. For the first two arguments, the name of the test or suite must +be supplied or the PTS Global ID or saved local file name.</p> +<p><strong>upload <To Upload></strong></p> +<p>This option allows you to upload a saved result to PTS Global.</p> +<p><strong>login</strong></p> +<p>This option allows you to log-in to your PTS Global account and will store +this information automatically. A new PTS Global account can be created (for free) +at http://global.phoronix-test-suite.com/.</p> +<h2>Miscellaneous Options</h2> +<p><strong>make-download-cache</strong></p> +<p>This option will backup all files that were automatically downloaded by the +Phoronix Test Suite during the installation of tests. These files are automatically +backed up by default to ~/.phoronix-test-suite/download-cache/. By backing up +these files, one can easily transfer these files to another system running the +Phoronix Test Suite thereby conserving bandwidth and reducing time. Through modifying +the user configuration file, the download cache location can be adjusted. The +Phoronix Test Suite supports reading from download caches over the network and +on remote file-systems.</p> +<p><strong>info <To Show></strong></p> +<p>This option will show details about the test or suite that's supplied as the +first argument to this option. When supplying the name of a test, the version, +maintainer, type, download size, license information, and suites using this test +are displayed. When supplying the name of a suite, the version, maintainer, type, +and tests that make up the suite are displayed.</p> +<p><strong>system-info</strong></p> +<p>This option will show installed system hardware and software that has been +detected by the Phoronix Test Suite.</p> +<p><strong>sensor-options</strong></p> +<p>This option will show system sensors that can be monitored through the Phoronix +Test Suite.</p> +<p><strong>diagnostics</strong></p> +<p>This option will print informaiton that is useful to developers when debugging +problems with the Phoronix Test Suite.</p> +<p><strong>version</strong></p> +<p>This option will print the Phoronix Test Suite version.</p> +<h2>Other Options</h2> +<p><strong>force-install <To Install></strong></p> +<p>This option will force the installation (or re-installation) of a test or suite. +The arguments and process is similar to the install option but even if the test +is installed, the entire installation process will automatically be executed. +This option should only be used when debugging a test installation problem.</p> +<p><strong>force-install-all</strong></p> +<p>This option will force the installation (or re-installation) of all tests. +The process is similar to the install-all option but even if a test is installed, +the entire installation process will automatically be executed. This option should +only be used when debugging a test installation problem.</p> +<p><strong>refresh-graphs <Saved Name></strong></p> +<p>This option will re-render and save all result graphs within a saved file. +This option can be used when making modifications to the graphing code or its +color/option configuration file and testing the changes.</p> +<p><strong>initial-config</strong></p> +<p>This option will generate a new user configuration (user-config.xml) file.</p> +<!-- END OF PTS AREA --> +</div></div><div class="pts_doc_fixed"><div class="pts_doc_bottom"><div style="float: left;"><a href="http://www.phoronix-test-suite.com/">Phoronix-Test-Suite.com</a></div><div style="float: right;">Copyright © 2008 by <a href="http://www.phoronixmedia.com/">Phoronix Media</a>.</div></div></div> +</body> +</html> diff --git a/documentation/specifications_xml_download.html b/documentation/specifications_xml_download.html new file mode 100644 index 0000000..4150647 --- /dev/null +++ b/documentation/specifications_xml_download.html @@ -0,0 +1,43 @@ +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<Title>Phoronix Test Suite - XML Downloads Syntax</Title> +<link href="includes/pts-documentation.css" rel="stylesheet" type="text/css" /> +</head> +<body> +<div id="pts_doc_header"><div class="pts_doc_fixed"><div id="pts_doc_logo"></div></div></div> +<div class="pts_doc_fixed"> +<div class="pts_doc_notice"><div style="float: left"><a href="index.html"><< Documentation Home</a></div><div style="float: right;">PTS Downloads Specification</div></div> +<div class="pts_doc_main"> +<!-- PTS AREA --> +<h1>Phoronix Test Suite 1.0 Downloads Specification</h1> +<p>This document describes the XML tags for writing a test downloads.xml file.</p> +<h2>PhoronixTestSuite/Downloads/Package/</h2> +<p><strong>Tag:</strong> URL<br> +<strong>Location:</strong> PhoronixTestSuite/Downloads/Package/<br> +<strong>Internal Reference:</strong> P_DOWNLOADS_PACKAGE_URL<br> +<strong>Required:</strong> Yes<br> +<strong>Description:</strong> The URL(s) to download the package from. If multiple URLs are supplied +(delimited by a comma), the Phoronix Test Suite will randomly choose one URL but +will fallback to other URLs if one fails.</p> +<p><strong>Tag:</strong> MD5<br> +<strong>Location:</strong> PhoronixTestSuite/Downloads/Package/<br> +<strong>Internal Reference:</strong> P_DOWNLOADS_PACKAGE_MD5<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> The MD5 check-sum for the file to be downloaded. This is done to +ensure file integrity.</p> +<p><strong>Tag:</strong> FileName<br> +<strong>Location:</strong> PhoronixTestSuite/Downloads/Package/<br> +<strong>Internal Reference:</strong> P_DOWNLOADS_PACKAGE_FILENAME<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> If this tag is set, once the file is downloaded it will be renamed +to this value. If this tag is not set, the remote file-name will be maintained.</p> +<p><strong>Tag:</strong> DownloadTo<br> +<strong>Location:</strong> PhoronixTestSuite/Downloads/Package/<br> +<strong>Internal Reference:</strong> P_DOWNLOADS_PACKAGE_DESTINATION<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> If this tag is set to PTS_SHARED, the package will be download to +the pts-shared/ folder instead of the test's environment folder.</p> +<!-- END OF PTS AREA --> +</div></div><div class="pts_doc_fixed"><div class="pts_doc_bottom"><div style="float: left;"><a href="http://www.phoronix-test-suite.com/">Phoronix-Test-Suite.com</a></div><div style="float: right;">Copyright © 2008 by <a href="http://www.phoronixmedia.com/">Phoronix Media</a>.</div></div></div> +</body> +</html> diff --git a/documentation/specifications_xml_suite.html b/documentation/specifications_xml_suite.html new file mode 100644 index 0000000..b33dcfe --- /dev/null +++ b/documentation/specifications_xml_suite.html @@ -0,0 +1,65 @@ +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<Title>Phoronix Test Suite - XML Suite Syntax</Title> +<link href="includes/pts-documentation.css" rel="stylesheet" type="text/css" /> +</head> +<body> +<div id="pts_doc_header"><div class="pts_doc_fixed"><div id="pts_doc_logo"></div></div></div> +<div class="pts_doc_fixed"> +<div class="pts_doc_notice"><div style="float: left"><a href="index.html"><< Documentation Home</a></div><div style="float: right;">PTS Suite Specification</div></div> +<div class="pts_doc_main"> +<!-- PTS AREA --> +<h1>Phoronix Test Suite 1.0 Suite Specification</h1> +<p>This document describes the XML tags for writing a test suite.</p> +<h2>PhoronixTestSuite/SuiteInformation/</h2> +<p><strong>Tag:</strong> Title<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_SUITE_TITLE<br> +<strong>Required:</strong> Yes<br> +<strong>Description:</strong> The full string title of the suite.</p> +<p><strong>Tag:</strong> Version<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_SUITE_VERSION<br> +<strong>Required:</strong> Yes<br> +<strong>Description:</strong> The version of the test suite.<br> +<strong>Supported Values:</strong> ( Formatted: x.x.x )</p> +<p><strong>Tag:</strong> Description<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_SUITE_DESCRIPTION<br> +<strong>Required:</strong> Recommended<br> +<strong>Description:</strong> A short description of the test suite.</p> +<p><strong>Tag:</strong> TestType<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_SUITE_TYPE<br> +<strong>Required:</strong> Recommended<br> +<strong>Description:</strong> The hardware area of the system that this suite is designed to stress.<br> +<strong>Supported Values:</strong> System, Processor, Graphics, Disk, Memory, Motherboard</p> +<p><strong>Tag:</strong> Maintainer<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_SUITE_MAINTAINER<br> +<strong>Required:</strong> Recommended<br> +<strong>Description:</strong> The name of the maintainer of this suite.</p> +<h2>PhoronixTestSuite/RunTest/<br> +NOTE: Multiple instances of these tags are allowed for multiple tests in a suite</h2> +<p><strong>Tag:</strong> Test<br> +<strong>Location:</strong> PhoronixTestSuite/RunTest/<br> +<strong>Internal Reference:</strong> P_SUITE_TEST_NAME<br> +<strong>Required:</strong> Yes<br> +<strong>Description:</strong> The name (identifier) of the test to run.</p> +<p><strong>Tag:</strong> Arguments<br> +<strong>Location:</strong> PhoronixTestSuite/RunTest/<br> +<strong>Internal Reference:</strong> P_SUITE_TEST_ARGUMENTS<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> Only the default arguments are extracted from the test profile. All +other arguments you wish to supply (as the end-user isn't prompted of any options +when running a suite) should be supplied as a value in this tag.</p> +<p><strong>Tag:</strong> Description<br> +<strong>Location:</strong> PhoronixTestSuite/RunTest/<br> +<strong>Internal Reference:</strong> P_SUITE_TEST_DESCRIPTION<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> A short description describing this test and its options, which is +displayed on the graph in the PTS Results Viewer.</p> +<!-- END OF PTS AREA --> +</div></div><div class="pts_doc_fixed"><div class="pts_doc_bottom"><div style="float: left;"><a href="http://www.phoronix-test-suite.com/">Phoronix-Test-Suite.com</a></div><div style="float: right;">Copyright © 2008 by <a href="http://www.phoronixmedia.com/">Phoronix Media</a>.</div></div></div> +</body> +</html> diff --git a/documentation/specifications_xml_test.html b/documentation/specifications_xml_test.html new file mode 100644 index 0000000..a43d939 --- /dev/null +++ b/documentation/specifications_xml_test.html @@ -0,0 +1,220 @@ +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<Title>Phoronix Test Suite - XML Test Syntax</Title> +<link href="includes/pts-documentation.css" rel="stylesheet" type="text/css" /> +</head> +<body> +<div id="pts_doc_header"><div class="pts_doc_fixed"><div id="pts_doc_logo"></div></div></div> +<div class="pts_doc_fixed"> +<div class="pts_doc_notice"><div style="float: left"><a href="index.html"><< Documentation Home</a></div><div style="float: right;">PTS Test Specification</div></div> +<div class="pts_doc_main"> +<!-- PTS AREA --> +<h1>Phoronix Test Suite 1.0 Test Specification</h1> +<p>This document describes the XML tags for writing a test profile.</p> +<h2>PhoronixTestSuite/TestProfile/</h2> +<p><strong>Tag:</strong> Version<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_TEST_PTSVERSION<br> +<strong>Required:</strong> Yes<br> +<strong>Description:</strong> The version of the test profile itself, not dependent upon the main +Phoronix Test Suite version or the version of the software package itself.<br> +<strong>Supported Values:</strong> ( Formatted: x.x.x )</p> +<p><strong>Tag:</strong> TestType<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_TEST_HARDWARE_TYPE<br> +<strong>Required:</strong> Recommended<br> +<strong>Description:</strong> The hardware area of the system that this test is designed to stress.<br> +<strong>Supported Values:</strong> System, Processor, Graphics, Disk, Memory, Motherboard</p> +<p><strong>Tag:</strong> SoftwareType<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_TEST_SOFTWARE_TYPE<br> +<strong>Required:</strong> Recommended<br> +<strong>Description:</strong> The type of software that this test consists of.<br> +<strong>Supported Values:</strong> Game, Utility, Simulator, Other</p> +<p><strong>Tag:</strong> Maintainer<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_TEST_MAINTAINER<br> +<strong>Required:</strong> Yes<br> +<strong>Description:</strong> The name of this profile's maintainer.</p> +<p><strong>Tag:</strong> License<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_TEST_LICENSE<br> +<strong>Required:</strong> Yes<br> +<strong>Description:</strong> The license of the software itself.<br> +<strong>Supported Values:</strong> FREE, NON-FREE, RESTRICTED (Will only work with certain hardware +configurations), UNKNOWN</p> +<p><strong>Tag:</strong> Status<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_TEST_STATUS<br> +<strong>Required:</strong> Yes<br> +<strong>Description:</strong> The status of the test profile itself.<br> +<strong>Supported Values:</strong> VERIFIED, UNVERIFIED, BROKEN</p> +<p><strong>Tag:</strong> SupportedArchitectures<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_TEST_SUPPORTEDARCHS<br> +<strong>Required:</strong> No - Defaults to assume all architectures are supported<br> +<strong>Description:</strong> If the test software is limited to running on select system architectures, +list them in this tag with each architecture delimited by a comma.<br> +<strong>Supported Values:</strong> ( Examples: x86, x86_64 )</p> +<p><strong>Tag:</strong> RequiresRoot<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_TEST_ROOTNEEDED<br> +<strong>Required:</strong> No - Defaults to assume false<br> +<strong>Description:</strong> If root access is needed by the software encapsulated by this profile, +the value of this tag should be 1.<br> +<strong>Supported Values:</strong> 0, 1</p> +<p><strong>Tag:</strong> DownloadSize<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_TEST_DOWNLOADSIZE<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> The estimated size (in megabytes) that this test takes up in files +downloaded.<br> +<strong>Supported Values:</strong> ( Values must be in MB )</p> +<p><strong>Tag:</strong> EnvironmentSize<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_TEST_ENVIRONMENTSIZE<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> The estimated size (in megabytes) that this test takes up in its +environment directory when downloaded files have been extracted, etc.<br> +<strong>Supported Values:</strong> ( Values must be in MB )</p> +<p><strong>Tag:</strong> EstimatedLength<br> +<strong>Location:</strong> PhoronixTestSuite/TestProfile/<br> +<strong>Internal Reference:</strong> P_TEST_ESTIMATEDTIME<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> The estimated length (in minutes) that it takes this benchmark to +run in total.<br> +<strong>Supported Values:</strong> ( Values must be in minutes )</p> +<h2>PhoronixTestSuite/TestInformation/</h2> +<p><strong>Tag:</strong> Title<br> +<strong>Location:</strong> PhoronixTestSuite/TestInformation/<br> +<strong>Internal Reference:</strong> P_TEST_TITLE<br> +<strong>Required:</strong> Yes<br> +<strong>Description:</strong> The string title of the test, used for display purposes.</p> +<p><strong>Tag:</strong> SubTitle<br> +<strong>Location:</strong> PhoronixTestSuite/TestInformation/<br> +<strong>Internal Reference:</strong> P_TEST_SUBTITLE<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> If a value is supplied, this is a static sub-title when rendering +the graph results. Otherwise the test options (if applicable) are displayed.</p> +<p><strong>Tag:</strong> Version<br> +<strong>Location:</strong> PhoronixTestSuite/TestInformation/<br> +<strong>Internal Reference:</strong> P_TEST_VERSION<br> +<strong>Required:</strong> Recommended<br> +<strong>Description:</strong> The version of the software game/application/program itself</p> +<p><strong>Tag:</strong> Description<br> +<strong>Location:</strong> PhoronixTestSuite/TestInformation/<br> +<strong>Internal Reference:</strong> P_TEST_DESCRIPTION<br> +<strong>Required:</strong> Recommended<br> +<strong>Description:</strong> A few sentence description of the test.</p> +<p><strong>Tag:</strong> ExternalDependencies<br> +<strong>Location:</strong> PhoronixTestSuite/TestInformation/<br> +<strong>Internal Reference:</strong> P_TEST_EXDEP<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> The external dependencies needed for the test. Multiple dependencies +need to be delimited by a comma.<br> +<strong>Supported Values:</strong> ( See pts/distro-xml/generic-packages.xml for a list of currently +supported external dependencies. )</p> +<p><strong>Tag:</strong> ResultScale<br> +<strong>Location:</strong> PhoronixTestSuite/TestInformation/<br> +<strong>Internal Reference:</strong> P_TEST_SCALE<br> +<strong>Required:</strong> Yes<br> +<strong>Description:</strong> The scale the results are reported in.<br> +<strong>Supported Values:</strong> ( Examples: Seconds, Average FPS, Mflops )</p> +<p><strong>Tag:</strong> ResultQuantifier<br> +<strong>Location:</strong> PhoronixTestSuite/TestInformation/<br> +<strong>Internal Reference:</strong> P_TEST_QUANTIFIER<br> +<strong>Required:</strong> No - Defaults to AVG<br> +<strong>Description:</strong> When running a test multiple times, how should the final result be +calculated.<br> +<strong>Supported Values:</strong> AVG (Average), MAX (Maximum), MIN (Minimum)</p> +<p><strong>Tag:</strong> ResultFormat<br> +<strong>Location:</strong> PhoronixTestSuite/TestInformation/<br> +<strong>Internal Reference:</strong> P_TEST_RESULTFORMAT<br> +<strong>Required:</strong> No - Defaults to BAR_GRAPH<br> +<strong>Description:</strong> The type of graph/visual representation to be used when viewing the +test results.<br> +<strong>Supported Values:</strong> BAR_GRAPH (Bar Graph), LINE_GRAPH (Line Graph), PASS_FAIL (Pass-Fail +Graph)</p> +<p><strong>Tag:</strong> Proportion<br> +<strong>Location:</strong> PhoronixTestSuite/TestInformation/<br> +<strong>Internal Reference:</strong> P_TEST_PROPORTION<br> +<strong>Required:</strong> No - Defaults to HIB<br> +<strong>Description:</strong> The scale for the test, whether lower or higher results yield better +performance.<br> +<strong>Supported Values:</strong> LIB (Lower Is Better), HIB (Higher Is Better)</p> +<p><strong>Tag:</strong> Executable<br> +<strong>Location:</strong> PhoronixTestSuite/TestInformation/<br> +<strong>Internal Reference:</strong> P_TEST_EXECUTABLE<br> +<strong>Required:</strong> No - Defaults to name (identifier) of test<br> +<strong>Description:</strong> When looking for the test to execute in the path directory or the +benchmarking environment directory, this is the string of the file-name.</p> +<p><strong>Tag:</strong> TimesToRun<br> +<strong>Location:</strong> PhoronixTestSuite/TestInformation/<br> +<strong>Internal Reference:</strong> P_TEST_RUNCOUNT<br> +<strong>Required:</strong> No - Defaults to 1<br> +<strong>Description:</strong> The number of times to run the test.<br> +<strong>Supported Values:</strong> ( Integer Values )</p> +<p><strong>Tag:</strong> IgnoreFirstRun<br> +<strong>Location:</strong> PhoronixTestSuite/TestInformation/<br> +<strong>Internal Reference:</strong> P_TEST_IGNOREFIRSTRUN<br> +<strong>Required:</strong> No - Defaults to 0<br> +<strong>Description:</strong> If the test is being run multiple times, should the first value be +ignored. If the value is set to 1, the first result will be void.<br> +<strong>Supported Values:</strong> 0, 1</p> +<p><strong>Tag:</strong> PreRunMessage<br> +<strong>Location:</strong> PhoronixTestSuite/TestInformation/<br> +<strong>Internal Reference:</strong> P_TEST_PRERUNMSG<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> If the user needs to be alerted about something dealing with this +test, this tag can contain a string that will be shown to the user before the +test begins.</p> +<h2>PhoronixTestSuite/TestSettings/Default/</h2> +<p><strong>Tag:</strong> Arguments<br> +<strong>Location:</strong> PhoronixTestSuite/TestSettings/Default/<br> +<strong>Internal Reference:</strong> P_TEST_DEFAULTARGUMENTS<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> Any arguments to supply to the test executable by default each and +every time.</p> +<p><strong>Tag:</strong> PossiblePaths<br> +<strong>Location:</strong> PhoronixTestSuite/TestSettings/Default/<br> +<strong>Internal Reference:</strong> P_TEST_POSSIBLEPATHS<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> As an alternative to using the testing environment directory, this +tag can containe different paths to check for the test executable. Multiple paths +need to be separated by a comma.</p> +<h2>PhoronixTestSuite/TestSettings/Option/<br> +NOTE: Multiple instances of these tags are allowed for multiple options in the +test</h2> +<p><strong>Tag:</strong> DisplayName<br> +<strong>Location:</strong> PhoronixTestSuite/TestSettings/Option/<br> +<strong>Internal Reference:</strong> P_TEST_OPTIONS_DISPLAYNAME<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> If the end-user is presented with options for this test, this tag +is the full string shown to the user to describe this option.</p> +<p><strong>Tag:</strong> ArgumentName<br> +<strong>Location:</strong> PhoronixTestSuite/TestSettings/Option/<br> +<strong>Internal Reference:</strong> P_TEST_OPTIONS_ARGUMENTNAME<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> The argument that will be appended to the Arguments tag and is pre-fixed +to the Identifier tag selected by the user.</p> +<p><strong>Tag:</strong> Identifier<br> +<strong>Location:</strong> PhoronixTestSuite/TestSettings/Option/<br> +<strong>Internal Reference:</strong> P_TEST_OPTIONS_IDENTIFIER<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> The internal ID to describe this option.</p> +<p><strong>Tag:</strong> Name<br> +<strong>Location:</strong> PhoronixTestSuite/TestSettings/Option/Menu/<br> +<strong>Internal Reference:</strong> P_TEST_OPTIONS_MENU_GROUP_NAME<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> The string shown to the user to describe one of the available options +within the option.</p> +<p><strong>Tag:</strong> Value<br> +<strong>Location:</strong> PhoronixTestSuite/TestSettings/Option/Menu/<br> +<strong>Internal Reference:</strong> P_TEST_OPTIONS_MENU_GROUP_VALUE<br> +<strong>Required:</strong> No<br> +<strong>Description:</strong> The string post-fixed to the ArgumentName tag and appended to the +end of the Arguments tag, which is then supplied to the executable binary as arguments.</p> +<!-- END OF PTS AREA --> +</div></div><div class="pts_doc_fixed"><div class="pts_doc_bottom"><div style="float: left;"><a href="http://www.phoronix-test-suite.com/">Phoronix-Test-Suite.com</a></div><div style="float: right;">Copyright © 2008 by <a href="http://www.phoronixmedia.com/">Phoronix Media</a>.</div></div></div> +</body> +</html> diff --git a/documentation/txt/guide-write-test-profile.txt b/documentation/txt/guide-write-test-profile.txt new file mode 100644 index 0000000..471f09c --- /dev/null +++ b/documentation/txt/guide-write-test-profile.txt @@ -0,0 +1,83 @@ +======================================== +A Quick Guide To Writing A Test Profile +======================================== + +Writing a test profile for the Phoronix Test Suite is a relatively quick and easy process for anyone familiar with common Linux commands and the basics of XML. To help you understand the design of the Phoronix Test Suite, this guide covers the steps needed to write a testing profile for a very simple application. + +The first step in the profile writing process is to, well, have a piece of software you'd like to use with the Phoronix Test Suite. This software can be closed-source or open-source and be virtually anything as long as it is compatible with the Linux operating system. + +For this guide, the piece of software being used for demonstration is just a simple C++ program that calculates Pi to 8,765,4321 digits using the Leibniz formula. Below is this sample piece of software intended just for demonstration purposes. + +#include <iostream> +#include <math.h> + +int main() +{ + double pi = 0; + + for(long int i = 1; i <= 87654321; i++) + pi += (double) pow(-1, i + 1) / (2 * i - 1); + + pi *= 4; + std::cout << "Done Calculating Pi..." << endl; + return 0; +} + +The first step in the actual profile writing process is to name it. If you're looking to ultimately push this profile to be included in the Phoronix Test Suite, its name must be all lower case and consist of just alpha-numeric characters, but can contain dashes (-). For this sample profile, we're calling it sample-program and the file-name would be sample-program.xml. Our (very basic) profile is showcased below. + +<PhoronixTestSuite> + <TestProfile> + <Version>1.0</Version> + <TestType>Processor</TestType> + <SoftwareType>Utility</SoftwareType> + <License>FREE</License> + <Status>PRIVATE</Status> + <Maintainer>Phoronix Media</Maintainer> + </TestProfile> + <TestInformation> + <Title>Sample Pi Program</Title> + <TimesToRun>3</TimesToRun> + <ResultScale>Seconds</ResultScale> + <Proportion>LIB</Proportion> + <Description>A simple C++ program that calculates Pi to 8,765,4321 digits using the Leibniz formula.</Description> + <ExternalDependencies>build-utilities</ExternalDependencies> + </TestInformation> +</PhoronixTestSuite> + +This XML profile is what interfaces with the Phoronix Test Suite and provides all the needed information about the test as well as other attributes. For a complete listing of all the supported profile options, look at the specification files in the documentation folder. In the case of sample-program, it lets the Phoronix Test Suite know that it's composed of free software, is designed to test the processor, is intended for private use only, and this profile is maintained by Phoronix Media. In addition, it tells the Phoronix Test Suite to execute this program three times and as no result quantifier is set, the average of the three runs will be taken. This profile also tells the Phoronix Test Suite that the generic build-utilities package is needed, which will attempt to ensure that GCC and the standard development utilities/libraries are installed on your Linux distribution. This is needed as the C++ source-code will need to be built from source. + +The next step is to write the install.sh file, which once called by the Phoronix Test Suite is intended to install the test locally for benchmarking purposes. The install.sh file is technically optional, but is generally used by all tests. Alternatively, the file may be named install.php if you wish to write the install script in PHP instead of a shell script. Note: The first argument supplied to the install script is the directory that the test needs to be installed to. The install.sh file (in our instance) is to be placed inside pts/test-resources/sample-program. Below is the install.sh for the sample-program. + +#!/bin/sh + +tar -xjf sample-pi-program-1.tar.bz2 +g++ sample-pi-program.cpp -o sample-pi-program + +echo "#!/bin/sh + +time -f \"Pi Calculation Time: %e Seconds\" ./sample-pi-program 2>&1 | grep Seconds" > sample-program +chmod +x sample-program + +This install file builds the code with GCC, and then creates a small script that is run by the Phoronix Test Suite, which times how long it takes to run the software. Where does the source-code come into play? Well, it needs to be downloaded now from a web server. The Phoronix Test Suite has built-in support for managing downloads from multiple servers in a random over, fall-back support if one mirror is done, and verification of MD5 check-sums. Below is the downloads.xml file for sample-program that covers all of this. + +<PhoronixTestSuite> + <Downloads> + <Package> + <URL>http://www.phoronix-test-suite.com/benchmark-files/sample-pi-program.cpp</URL> + <MD5>e90fb790df8d1544696a1439c9b5bd8d</MD5> + </Package> + </Downloads> +</PhoronixTestSuite> + +The final step in the profile writing process is to write a parser to strip all information but the reported result from the standard output. The standard output is submitted to parse-results.sh/parse-results.php as the first argument in quotes. In the case of sample-program, all that's done inside parse-results.php is: + +<?php +$BENCHMARK_RESULTS = substr($argv[1], strrpos($argv[1], "Pi Calculation Time:") + 20); +echo trim(substr($BENCHMARK_RESULTS, 0, strpos($BENCHMARK_RESULTS, "Seconds"))); +?> + +After that, with all the files in their correct locations, just run: phoronix-test-suite benchmark sample-program. The Phoronix Test Suite should now handle the rest by installing the test, running the test, and recording the results (if you so choose). There is no additional work that needs to be done for the results to be recorded in the PTS Results Viewer or even reporting the results to PTS Global. + +For more information, visit http://www.phoronix-test-suite.com/ and its resources. + +Notice: This guide covers the PTS 1.0 specification for writing test profiles, which is compatible with all Phoronix Test Suite releases from 0.8.0 onwards. diff --git a/documentation/txt/specification-test-downloads.txt b/documentation/txt/specification-test-downloads.txt new file mode 100644 index 0000000..2fefee9 --- /dev/null +++ b/documentation/txt/specification-test-downloads.txt @@ -0,0 +1,34 @@ +### +### This document describes the XML tags for writing a test downloads.xml file. +### For additional information, explore the other included documentation, the mailing list, and the test profiles shipping with the Phoronix Test Suite. +### Phoronix Test Suite 1.0 Downloads Specification +### + +### +### PhoronixTestSuite/Downloads/Package/ +### NOTE: Multiple instances of these tags are allowed for multiple downloads. +### + +Tag: URL +Location: PhoronixTestSuite/Downloads/Package/ +Internal Reference: P_DOWNLOADS_PACKAGE_URL +Required: Yes +Description: The URL(s) to download the package from. If multiple URLs are supplied (delimited by a comma), the Phoronix Test Suite will randomly choose one URL but will fallback to other URLs if one fails. + +Tag: MD5 +Location: PhoronixTestSuite/Downloads/Package/ +Internal Reference: P_DOWNLOADS_PACKAGE_MD5 +Required: No +Description: The MD5 check-sum for the file to be downloaded. This is done to ensure file integrity. + +Tag: FileName +Location: PhoronixTestSuite/Downloads/Package/ +Internal Reference: P_DOWNLOADS_PACKAGE_FILENAME +Required: No +Description: If this tag is set, once the file is downloaded it will be renamed to this value. If this tag is not set, the remote file-name will be maintained. + +Tag: DownloadTo +Location: PhoronixTestSuite/Downloads/Package/ +Internal Reference: P_DOWNLOADS_PACKAGE_DESTINATION +Required: No +Description: If this tag is set to PTS_SHARED, the package will be download to the pts-shared/ folder instead of the test's environment folder. diff --git a/documentation/txt/specification-test-profile.txt b/documentation/txt/specification-test-profile.txt new file mode 100644 index 0000000..50640c1 --- /dev/null +++ b/documentation/txt/specification-test-profile.txt @@ -0,0 +1,226 @@ +### +### This document describes the XML tags for writing a test profile. +### For additional information, explore the other included documentation, the mailing list, and the test profiles shipping with the Phoronix Test Suite. +### Phoronix Test Suite 1.0 Test Specification +### + +### +### PhoronixTestSuite/TestProfile/ +### + +Tag: Version +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_TEST_PTSVERSION +Required: Yes +Description: The version of the test profile itself, not dependent upon the main Phoronix Test Suite version or the version of the software package itself. +Supported Values: ( Formatted: x.x.x ) + +Tag: TestType +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_TEST_HARDWARE_TYPE +Required: Recommended +Description: The hardware area of the system that this test is designed to stress. +Supported Values: System, Processor, Graphics, Disk, Memory, Motherboard + +Tag: SoftwareType +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_TEST_SOFTWARE_TYPE +Required: Recommended +Description: The type of software that this test consists of. +Supported Values: Game, Utility, Simulator, Other + +Tag: Maintainer +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_TEST_MAINTAINER +Required: Yes +Description: The name of this profile's maintainer. + +Tag: License +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_TEST_LICENSE +Required: Yes +Description: The license of the software itself. +Supported Values: FREE, NON-FREE, RESTRICTED (Will only work with certain hardware configurations), UNKNOWN + +Tag: Status +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_TEST_STATUS +Required: Yes +Description: The status of the test profile itself. +Supported Values: VERIFIED, UNVERIFIED, BROKEN + +Tag: SupportedArchitectures +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_TEST_SUPPORTEDARCHS +Required: No - Defaults to assume all architectures are supported +Description: If the test software is limited to running on select system architectures, list them in this tag with each architecture delimited by a comma. +Supported Values: ( Examples: x86, x86_64 ) + +Tag: RequiresRoot +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_TEST_ROOTNEEDED +Required: No - Defaults to assume false +Description: If root access is needed by the software encapsulated by this profile, the value of this tag should be 1. +Supported Values: 0, 1 + +Tag: DownloadSize +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_TEST_DOWNLOADSIZE +Required: No +Description: The estimated size (in megabytes) that this test takes up in files downloaded. +Supported Values: ( Values must be in MB ) + +Tag: EnvironmentSize +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_TEST_ENVIRONMENTSIZE +Required: No +Description: The estimated size (in megabytes) that this test takes up in its environment directory when downloaded files have been extracted, etc. +Supported Values: ( Values must be in MB ) + +Tag: EstimatedLength +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_TEST_ESTIMATEDTIME +Required: No +Description: The estimated length (in minutes) that it takes this benchmark to run in total. +Supported Values: ( Values must be in minutes ) + +### +### PhoronixTestSuite/TestInformation/ +### + +Tag: Title +Location: PhoronixTestSuite/TestInformation/ +Internal Reference: P_TEST_TITLE +Required: Yes +Description: The string title of the test, used for display purposes. + +Tag: SubTitle +Location: PhoronixTestSuite/TestInformation/ +Internal Reference: P_TEST_SUBTITLE +Required: No +Description: If a value is supplied, this is a static sub-title when rendering the graph results. Otherwise the test options (if applicable) are displayed. + +Tag: Version +Location: PhoronixTestSuite/TestInformation/ +Internal Reference: P_TEST_VERSION +Required: Recommended +Description: The version of the software game/application/program itself + +Tag: Description +Location: PhoronixTestSuite/TestInformation/ +Internal Reference: P_TEST_DESCRIPTION +Required: Recommended +Description: A few sentence description of the test. + +Tag: ExternalDependencies +Location: PhoronixTestSuite/TestInformation/ +Internal Reference: P_TEST_EXDEP +Required: No +Description: The external dependencies needed for the test. Multiple dependencies need to be delimited by a comma. +Supported Values: ( See pts/distro-xml/generic-packages.xml for a list of currently supported external dependencies. ) + +Tag: ResultScale +Location: PhoronixTestSuite/TestInformation/ +Internal Reference: P_TEST_SCALE +Required: Yes +Description: The scale the results are reported in. +Supported Values: ( Examples: Seconds, Average FPS, Mflops ) + +Tag: ResultQuantifier +Location: PhoronixTestSuite/TestInformation/ +Internal Reference: P_TEST_QUANTIFIER +Required: No - Defaults to AVG +Description: When running a test multiple times, how should the final result be calculated. +Supported Values: AVG (Average), MAX (Maximum), MIN (Minimum) + +Tag: ResultFormat +Location: PhoronixTestSuite/TestInformation/ +Internal Reference: P_TEST_RESULTFORMAT +Required: No - Defaults to BAR_GRAPH +Description: The type of graph/visual representation to be used when viewing the test results. +Supported Values: BAR_GRAPH (Bar Graph), LINE_GRAPH (Line Graph), PASS_FAIL (Pass-Fail Graph) + +Tag: Proportion +Location: PhoronixTestSuite/TestInformation/ +Internal Reference: P_TEST_PROPORTION +Required: No - Defaults to HIB +Description: The scale for the test, whether lower or higher results yield better performance. +Supported Values: LIB (Lower Is Better), HIB (Higher Is Better) + +Tag: Executable +Location: PhoronixTestSuite/TestInformation/ +Internal Reference: P_TEST_EXECUTABLE +Required: No - Defaults to name (identifier) of test +Description: When looking for the test to execute in the path directory or the benchmarking environment directory, this is the string of the file-name. + +Tag: TimesToRun +Location: PhoronixTestSuite/TestInformation/ +Internal Reference: P_TEST_RUNCOUNT +Required: No - Defaults to 1 +Description: The number of times to run the test. +Supported Values: ( Integer Values ) + +Tag: IgnoreFirstRun +Location: PhoronixTestSuite/TestInformation/ +Internal Reference: P_TEST_IGNOREFIRSTRUN +Required: No - Defaults to 0 +Description: If the test is being run multiple times, should the first value be ignored. If the value is set to 1, the first result will be void. +Supported Values: 0, 1 + +Tag: PreRunMessage +Location: PhoronixTestSuite/TestInformation/ +Internal Reference: P_TEST_PRERUNMSG +Required: No +Description: If the user needs to be alerted about something dealing with this test, this tag can contain a string that will be shown to the user before the test begins. + +### +### PhoronixTestSuite/TestSettings/Default/ +### + +Tag: Arguments +Location: PhoronixTestSuite/TestSettings/Default/ +Internal Reference: P_TEST_DEFAULTARGUMENTS +Required: No +Description: Any arguments to supply to the test executable by default each and every time. + +Tag: PossiblePaths +Location: PhoronixTestSuite/TestSettings/Default/ +Internal Reference: P_TEST_POSSIBLEPATHS +Required: No +Description: As an alternative to using the testing environment directory, this tag can containe different paths to check for the test executable. Multiple paths need to be separated by a comma. + +### +### PhoronixTestSuite/TestSettings/Option/ +### NOTE: Multiple instances of these tags are allowed for multiple options in the test. +### + +Tag: DisplayName +Location: PhoronixTestSuite/TestSettings/Option/ +Internal Reference: P_TEST_OPTIONS_DISPLAYNAME +Required: No +Description: If the end-user is presented with options for this test, this tag is the full string shown to the user to describe this option. + +Tag: ArgumentName +Location: PhoronixTestSuite/TestSettings/Option/ +Internal Reference: P_TEST_OPTIONS_ARGUMENTNAME +Required: No +Description: The argument that will be appended to the Arguments tag and is pre-fixed to the Identifier tag selected by the user. + +Tag: Identifier +Location: PhoronixTestSuite/TestSettings/Option/ +Internal Reference: P_TEST_OPTIONS_IDENTIFIER +Required: No +Description: The internal ID to describe this option. + +Tag: Name +Location: PhoronixTestSuite/TestSettings/Option/Menu/ +Internal Reference: P_TEST_OPTIONS_MENU_GROUP_NAME +Required: No +Description: The string shown to the user to describe one of the available options within the option. + +Tag: Value +Location: PhoronixTestSuite/TestSettings/Option/Menu/ +Internal Reference: P_TEST_OPTIONS_MENU_GROUP_VALUE +Required: No +Description: The string post-fixed to the ArgumentName tag and appended to the end of the Arguments tag, which is then supplied to the executable binary as arguments. + diff --git a/documentation/txt/specification-test-suite.txt b/documentation/txt/specification-test-suite.txt new file mode 100644 index 0000000..e14fc3d --- /dev/null +++ b/documentation/txt/specification-test-suite.txt @@ -0,0 +1,65 @@ +### +### This document describes the XML tags for writing a test suite. +### For additional information, explore the other included documentation, the mailing list, and the test profiles shipping with the Phoronix Test Suite. +### Phoronix Test Suite 1.0 Suite Specification +### + +### +### PhoronixTestSuite/SuiteInformation/ +### + +Tag: Title +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_SUITE_TITLE +Required: Yes +Description: The full string title of the suite. + +Tag: Version +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_SUITE_VERSION +Required: Yes +Description: The version of the test suite. +Supported Values: ( Formatted: x.x.x ) + +Tag: Description +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_SUITE_DESCRIPTION +Required: Recommended +Description: A short description of the test suite. + +Tag: TestType +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_SUITE_TYPE +Required: Recommended +Description: The hardware area of the system that this suite is designed to stress. +Supported Values: System, Processor, Graphics, Disk, Memory, Motherboard + +Tag: Maintainer +Location: PhoronixTestSuite/TestProfile/ +Internal Reference: P_SUITE_MAINTAINER +Required: Recommended +Description: The name of the maintainer of this suite. + +### +### PhoronixTestSuite/RunTest/ +### NOTE: Multiple instances of these tags are allowed for multiple tests in suite. +### + +Tag: Test +Location: PhoronixTestSuite/RunTest/ +Internal Reference: P_SUITE_TEST_NAME +Required: Yes +Description: The name (identifier) of the test to run. + +Tag: Arguments +Location: PhoronixTestSuite/RunTest/ +Internal Reference: P_SUITE_TEST_ARGUMENTS +Required: No +Description: Only the default arguments are extracted from the test profile. All other arguments you wish to supply (as the end-user isn't prompted of any options when running a suite) should be supplied as a value in this tag. + +Tag: Description +Location: PhoronixTestSuite/RunTest/ +Internal Reference: P_SUITE_TEST_DESCRIPTION +Required: No +Description: A short description describing this test and its options, which is displayed on the graph in the PTS Results Viewer. + diff --git a/documentation/writing_your_first_test.html b/documentation/writing_your_first_test.html new file mode 100644 index 0000000..d68a9b9 --- /dev/null +++ b/documentation/writing_your_first_test.html @@ -0,0 +1,122 @@ +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<Title>Phoronix Test Suite - A Quick Guide To Writing A Test Profile</Title> +<link href="includes/pts-documentation.css" rel="stylesheet" type="text/css" /> +</head> +<body> +<div id="pts_doc_header"><div class="pts_doc_fixed"><div id="pts_doc_logo"></div></div></div> +<div class="pts_doc_fixed"> +<div class="pts_doc_notice"><div style="float: left"><a href="index.html"><< Documentation Home</a></div><div style="float: right;">Writing A Test Profile</div></div> +<div class="pts_doc_main"> +<!-- PTS AREA --> +<h1>Writing A Test Profile</h1> +<p>Writing a test profile for the Phoronix Test Suite is a relatively quick and easy +process for anyone familiar with common Linux commands and the basics of XML. +To help you understand the design of the Phoronix Test Suite, this guide covers +the steps needed to write a testing profile for a very simple application.</p> +<p>The first step in the profile writing process is to, well, have a piece of +software you'd like to use with the Phoronix Test Suite. This software can be +closed-source or open-source and be virtually anything as long as it is compatible +with the Linux operating system.</p> +<p>For this guide, the piece of software being used for demonstration is just +a simple C++ program that calculates Pi to 8,765,4321 digits using the Leibniz +formula. Below is this sample piece of software intended just for demonstration +purposes.</p> +<blockquote>#include <iostream><br> +#include <math.h></p> +<p>int main()<br> +{<br> +double pi = 0;</p> +<p> for(long int i = 1; i <= 87654321; i++)<br> +pi += (double) pow(-1, i + 1) / (2 * i - 1);</p> +<p> pi *= 4;<br> +std::cout << "Done Calculating Pi..." << endl;<br> +return 0;<br> +}</blockquote> +<p>The first step in the actual profile writing process is to name it. If you're +looking to ultimately push this profile to be included in the Phoronix Test Suite, +its name must be all lower case and consist of just alpha-numeric characters, +but can contain dashes (-). For this sample profile, we're calling it <em>sample-program</em> +and the file-name would be <em>sample-program.xml</em>. Our (very basic) profile is showcased +below.</p> +<blockquote><PhoronixTestSuite><br> + <TestProfile><br> + <Version>1.0</Version><br> + <TestType>Processor</TestType><br> + <SoftwareType>Utility</SoftwareType><br> + <License>FREE</License><br> + <Status>PRIVATE</Status><br> + <Maintainer>Phoronix Media</Maintainer><br> + </TestProfile><br> + <TestInformation><br> + <Title>Sample Pi Program</Title><br> + <TimesToRun>3</TimesToRun><br> + <ResultScale>Seconds</ResultScale><br> + <Proportion>LIB</Proportion><br> + <Description>A simple C++ program that calculates Pi to 8,765,4321 digits +using the Leibniz formula.</Description><br> + <ExternalDependencies>build-utilities</ExternalDependencies><br> + </TestInformation><br> +</PhoronixTestSuite></blockquote> +<p>This XML profile is what interfaces with the Phoronix Test Suite and provides +all the needed information about the test as well as other attributes. For a complete +listing of all the supported profile options, look at the specification files +in the documentation folder. In the case of <em>sample-program</em>, it lets the Phoronix +Test Suite know that it's composed of free software, is designed to test the processor, +is intended for private use only, and this profile is maintained by Phoronix Media. +In addition, it tells the Phoronix Test Suite to execute this program three times +and as no result quantifier is set, the average of the three runs will be taken. +This profile also tells the Phoronix Test Suite that the generic <em>build-utilities</em> +package is needed, which will attempt to ensure that GCC and the standard development +utilities/libraries are installed on your Linux distribution. This is needed as +the C++ source-code will need to be built from source.</p> +<p>The next step is to write the <em>install.sh</em> file, which once called by the Phoronix +Test Suite is intended to install the test locally for benchmarking purposes. +The <em>install.sh</em> file is technically optional, but is generally used by all tests. +Alternatively, the file may be named <em>install.php</em> if you wish to write the install +script in PHP instead of a shell script. Note: The first argument supplied to +the install script is the directory that the test needs to be installed to. The +<em>install.sh</em> file (in our instance) is to be placed inside <em>pts/test-resources/sample-program</em>. +Below is the <em>install.sh</em> for the <em>sample-program</em>.</p> +<blockquote>#!/bin/sh<br /><br /> +tar -xjf sample-pi-program-1.tar.bz2<br /> +g++ sample-pi-program.cpp -o sample-pi-program<br /> +echo "#!/bin/sh<br /> +time -f \"Pi Calculation Time: %e Seconds\" ./sample-pi-program 2>&1 +| grep Seconds" > sample-program<br> +chmod +x sample-program</blockquote> +<p>This install file builds the code with GCC, and then creates a small script +that is run by the Phoronix Test Suite, which times how long it takes to run the +software. Where does the source-code come into play? Well, it needs to be downloaded +now from a web server. The Phoronix Test Suite has built-in support for managing +downloads from multiple servers in a random over, fall-back support if one mirror +is done, and verification of MD5 check-sums. Below is the <em>downloads.xml</em> file for +<em>sample-program</em> that covers all of this.</p> +<blockquote><PhoronixTestSuite><br> + <Downloads><br> + <Package><br> + <URL>http://www.phoronix-test-suite.com/benchmark-files/sample-pi-program.cpp</URL><br> + <MD5>e90fb790df8d1544696a1439c9b5bd8d</MD5><br> + </Package><br> + </Downloads><br> +</PhoronixTestSuite></blockquote> +<p>The final step in the profile writing process is to write a parser to strip +all information but the reported result from the standard output. The standard +output is submitted to <em>parse-results.sh</em> or <em>parse-results.php</em> as the first argument +in quotes. In the case of <em>sample-program</em>, all that's done inside parse-results.php +is:</p> +<blockquote><?php<br> +$BENCHMARK_RESULTS = substr($argv[1], strrpos($argv[1], "Pi Calculation Time:") ++ 20);<br> +echo trim(substr($BENCHMARK_RESULTS, 0, strpos($BENCHMARK_RESULTS, "Seconds")));<br> +?></blockquote> +<p>After that, with all the files in their correct locations, just run: <em>phoronix-test-suite +benchmark sample-program</em>. The Phoronix Test Suite should now handle the rest by +installing the test, running the test, and recording the results (if you so choose). +There is no additional work that needs to be done for the results to be recorded +in the PTS Results Viewer or even reporting the results to PTS Global.</p> +<p>For more information, visit <a href="http://www.phoronix-test-suite.com/">Phoronix-Test-Suite.com</a> and the <a href="index.html">included documentation</a>.</p> +<!-- END OF PTS AREA --> +</div></div><div class="pts_doc_fixed"><div class="pts_doc_bottom"><div style="float: left;"><a href="http://www.phoronix-test-suite.com/">Phoronix-Test-Suite.com</a></div><div style="float: right;">Copyright © 2008 by <a href="http://www.phoronixmedia.com/">Phoronix Media</a>.</div></div></div> +</body> +</html> diff --git a/phoronix-test-suite b/phoronix-test-suite index a740248..899b325 100755 --- a/phoronix-test-suite +++ b/phoronix-test-suite @@ -172,16 +172,16 @@ Testing Options: list-suites: List all suites and relevant information Batch Testing Options: + batch-setup: Setup the batch mode options batch-run <suite OR test>: Run the specified test(s) in batch mode batch-benchmark <suite OR test OR saved file>: Install and run the test(s) in batch mode - batch-setup: Setup the batch mode options Result Viewing Options: - merge-results <saved Name 1 / Global ID> <saved Name 2 / Global ID> <save name>: Merge two sets of results list-results: List all saved results show-result <saved name>: Show this result file in your web browser remove-result <saved name>: Remove this saved result file remove-all-results: Removes all saved results + merge-results <saved Name 1 / Global ID> <saved Name 2 / Global ID> <save name>: Merge two sets of results upload <saved name>: Upload a saved set of results to PTS Global login: Enter your PTS Global log-in information for uploading results diff --git a/pts-core/pts-run-cmd.php b/pts-core/pts-run-cmd.php index 3fede8b..d890063 100644 --- a/pts-core/pts-run-cmd.php +++ b/pts-core/pts-run-cmd.php @@ -472,7 +472,7 @@ switch($COMMAND) pts_monitor_update(); break; case "SENSOR_OPTIONS": - echo "\nThe Phoronix Test Suite supports monitoring various system hardware sensors through the LM_Sensors and ACPI interfaces. The Phoronix Test Suite will automatically monitor the selected sensors while each test is running and at the end will then provide the low and high thresholds for each sensor as well as the average. In addition, the sensor results are then plotted on line graphs and can be viewed through the PTS Results Viewer.\n"; + //echo "\nThe Phoronix Test Suite supports monitoring various system hardware sensors through the LM_Sensors and ACPI interfaces. The Phoronix Test Suite will automatically monitor the selected sensors while each test is running and at the end will then provide the low and high thresholds for each sensor as well as the average. In addition, the sensor results are then plotted on line graphs and can be viewed through the PTS Results Viewer.\n"; echo "\nMonitoring these sensors are as easy as running your normal Phoronix Test Suite commands but at the beginning of the command add: MONITOR=<selected sensors> (example: MONITOR=cpu.temp,cpu.voltage phoronix-test-suite benchmark universe). Below are all of the sensors supported by this version of the Phoronix Test Suite.\n\n"; echo "Supported Options:\n"; foreach(pts_monitor_arguments() as $arg) |
