Writing a module for the Phoronix Test Suite allows new functionality to be added without having to extensively learn how pts-core functions. The module framework for the Phoronix Test Suite allows modules to be written either as a shell script or as a PHP object. Example PTS modules could include a module to shutdown the screensaver when the Phoronix Test Suite starts up and re-enabling it when the test is over, using sendmail to forward the results to an e-mail address when testing is completed, or writing the current test status to a LCDproc-enabled VFD display.
Both PHP and SH modules are stored in pts-core/modules/. Loading a module is done by either setting the PTS_MODULES environmental variable with the name of the module (excluding the .sh or .php file extension) or by associating a module with a separate environmental variable. The list of these environmental variables for auto-loading modules is stored in pts-core/static/module-variables.txt. The name of the environmental variable starts the line followed by an equal sign (=) and then what module to load if the variable is set. For example, if module-variables.txt contained a line that read EMAIL_RESULTS_TO=email_results, and the following command was run EMAIL_RESULTS_TO=my-email-address@my-domain.com phoronix-test-suite benchmark universe, it would automatically load the email_results module and the EMAIL_RESULTS_TO variable could be read by this module using a conventional method for reading the variable.
If you plan to permanently use a module, the string that normally would be defined in PTS_MODULES can be set within the LoadModules tag found in ~/.phoronix-test-suite/user-config.xml. Multiple modules can be loaded simultaneously using the PTS_MODULES variable or LoadModules tag by delimiting each command with a comma (,).
Note: To run through all of the function calls for a module without needing to run a test, run phoronix-test-suite test-module MODULE_NAME. Additionally, running phoronix-test-suite debug-module MODULE_NAME will yield additional debugging details while executing the same process.
To see all of the functions supported for modules written in PHP, look at pts-core/modules/dummy_module.php and additionally the other .php modules that ship with the Phoronix Test Suite. Additionally, there are several functions written specifically for Phoronix Test Suite modules that make it easier to save files, read files, and provided multi-threading support for modules. The pts_timed_function() makes it possible (and very easy) to thread functions within a module so that at a set interval the defined functions will be called. For example, this support is used heavily within the system_monitor module to poll sensors every X seconds even while there are tests running. These functions can be found within pts-core/objects/pts_module.php.
Below is a sample module that times how long it takes to run the Phoronix Test Suite. It would be saved as pts-core/modules/time_me.php.
<?php
class time_me extends pts_module_interface
{
const module_name = "Time Me!";
const module_version = "1.0.0";
const module_description = "This is a module that times how long the Phoronix Test Suite runs.";
const module_author = "Phoronix Media";
static $start_time = NULL;
static $end_time = NULL;
public static function __startup()
{
self::$start_time = time();
}
public static function __shutdown()
{
self::$end_time = time();
$time_elapsed = self::$end_time - self::$start_time;
echo "\nThe Phoronix Test Suite Ran For " . $time_elapsed . " Seconds.\n";
}
}
?>
Then by running PTS_MODULES=time_me phoronix-test-suite benchmark video-extensions, at the end of the test it would print a string similar to: "The Phoronix Test Suite Ran For 52 Seconds."
Running phoronix-test-suite module-info time_me would produce the following text.
====================================
Module: Time Me!
====================================Version: 1.0.0
Author: Phoronix Media
Description: This is a module that times how long the Phoronix Test Suite runs.
Writing Phoronix Test Suite modules in PHP is the preferred method, but the programming model for a shell script is similar. Look at dummy_script_module.sh to see available options. Below is a .sh version of the time_me.php module showcased in the previous section. This time_me.sh module provides the same exact functionality as the PHP version.
#!/bin/sh
case $1 in
"module_name")
echo "Time Me!"
;;
"module_version")
echo "1.0.0"
;;
"module_description")
echo "This is a module that times how long the Phoronix Test Suite runs."
;;
"module_author")
echo "Phoronix Media"
;;
"__startup")
date +%s > /tmp/pts-start-timer
;;
"__shutdown")
date +%s > /tmp/pts-end-timer
START_TIME=`cat /tmp/pts-start-timer`
END_TIME=`cat /tmp/pts-end-timer`
TIME_ELAPSED=`expr $END_TIME - $START_TIME`
echo "\nThe Phoronix Test Suite Ran For $TIME_ELAPSED Seconds.\n";
rm -f /tmp/pts-start-timer
rm -f /tmp/pts-end-timer
;;
esac