Provide support for links to tool and its version in HTML tables

The tool-info module can now provide URLs that table-generator
will use to linkify the tool name and the version number
in the benchmark-setup table.

Fixes sosy-lab#937.

benchexec/tablegenerator/__init__.py

@@ -404,12 +404,19 @@ def collect_data(self, correct_only):
         """
         self.results = []
 
+        tool = load_tool(self)
+        if tool:
+            self.attributes["project_url"] = [tool.project_url()]
+
+            versions = self.attributes["version"]
+            if len(versions) == 1 and versions[0]:
+                self.attributes["version_url"] = [tool.url_for_version(versions[0])]
+
         def get_value_from_logfile(lines, identifier):
             """
             This method searches for values in lines of the content.
             It uses a tool-specific method to so.
             """
-            tool = load_tool(self)
             if not tool:
                 return None
             output = tooladapter.CURRENT_BASETOOL.RunOutput(lines)

benchexec/tablegenerator/htmltable.py

@@ -143,7 +143,7 @@ def format_string_cell(attributes, format_string, onlyIf=None, default="Unknown"
         return formatStr.format_map(collections.defaultdict(str, attributes))
 
     def tool_data_cell(attributes):
-        keys = ["tool", "version"]
+        keys = ["tool", "version", "project_url", "version_url"]
         return {k: str(attributes[k]) for k in keys if attributes.get(k)}
 
     def get_row(

benchexec/tablegenerator/react-table/src/components/Summary.js

@@ -33,10 +33,27 @@ const Summary = (props) => {
     ));
   };
 
-  const renderToolNameAndVersion = ({ tool, version }) => {
+  const externalLink = (url, text) => {
+    if (url) {
+      return (
+        <a href={url} target="_blank" rel="noopener noreferrer">
+          {text}
+        </a>
+      );
+    } else {
+      return text;
+    }
+  };
+
+  const renderToolNameAndVersion = ({
+    tool,
+    version,
+    project_url,
+    version_url,
+  }) => {
     return (
       <>
-        {tool} {version}
+        {externalLink(project_url, tool)} {externalLink(version_url, version)}
       </>
     );
   };

benchexec/test_tool_info.py

@@ -50,6 +50,11 @@ def print_value(description, value, extra_line=False):
     )
 
 
+def print_optional_value(description, value, *args, **kwargs):
+    if value:
+        print_value(description, value, *args, **kwargs)
+
+
 def print_list(description, value):
     print_value(description, list(value), extra_line=True)
 
@@ -103,6 +108,7 @@ def print_tool_info(tool, tool_locator):
     print_multiline_text("Documentation of tool module", inspect.getdoc(tool))
 
     print_value("Name of tool", tool.name())
+    print_optional_value("Webpage", tool.project_url())
 
     executable = tool.executable(tool_locator)
     print_value("Executable", executable)
@@ -126,9 +132,12 @@ def print_tool_info(tool, tool_locator):
             logging.warning("Executable is not within specified tool directory.")
 
     try:
-        print_value("Version", tool.version(executable))
+        version = tool.version(executable)
     except BaseException:
         logging.warning("Determining version failed:", exc_info=1)
+    if version:
+        print_value("Version", tool.version(executable))
+        print_optional_value("URL for version", tool.url_for_version(version))
 
     working_directory = tool.working_directory(executable)
     print_value("Working directory", working_directory)

benchexec/tooladapter.py

@@ -86,6 +86,12 @@ def determine_result(self, run):
     def get_value_from_output(self, output, identifier):
         return self._wrapped.get_value_from_output(output._lines, identifier)
 
+    def project_url(self):
+        return None
+
+    def url_for_version(self, version):
+        return None
+
     def close(self):
         pass
 

benchexec/tools/template.py

@@ -98,6 +98,14 @@ def name(self):
         """
         raise NotImplementedError()
 
+    def project_url(self):
+        """
+        OPTIONAL, return the URL of the tool's webpage, if available.
+
+        @return None or a string with a URL in valid syntax for links on webpages
+        """
+        return None  # noqa: R501
+
     @abstractmethod
     def executable(self, tool_locator):
         """
@@ -179,6 +187,27 @@ def _version_from_tool(
             output = next(matches, "")
         return output
 
+    def url_for_version(self, version):
+        """
+        OPTIONAL, return a link to the specific version of the tool.
+        This could be for example a link to a specific release page or even a revision
+        in the project's repository if the version is fine-granular enough.
+        BenchExec will use this link to make version numbers of the tool clickable.
+
+        Note that this method may be called without any of the other methods
+        being called before.
+        The string that is passed as a parameter is guaranteed to have been returned
+        by the version() method at some point, but not necessarily in the current
+        execution of BenchExec and possibly by a previous implementation of this
+        tool-info module.
+
+        If no URL can be produced, the method may simply return None.
+
+        @param version: a version string as returned by the version() method in the past
+        @return None or a string with a URL in valid syntax for links on webpages
+        """
+        return None  # noqa: R501
+
     def environment(self, executable):
         """
         OPTIONAL, this method is only necessary for tools

doc/tool-integration.md

@@ -62,10 +62,12 @@ the method `determine_result` needs to be overwritten.
 It is recommended to also overwrite the function `version` if the tool has a version
 that can be automatically extracted.
 A Python doc string ([example](https://github.com/sosy-lab/benchexec/blob/92f10942b884e3ea85ffb66027d98672894796c6/benchexec/tools/template.py#L27-L36))
-should be added to the `Tool` class with the full name and URL of the tool.
+should be added to the `Tool` class with some short description of the tool.
 In this doc string there should also be any additional information about the tool-info module,
 such as its supported features
 or whether it adds or requires certain command-line parameter of the tool.
+It is also recommended to overwrite the function `project_url`
+if the tool has a webpage.
 
 Overwrite the functions `cmdline` and `working_directory`, and `environment`
 to adjust the respective values, e.g., to add the name of a given property file