[Buildbot-commits] buildbot/docs buildbot.texinfo,1.67,1.68

[Brian Warner]

Update of /cvsroot/buildbot/buildbot/docs
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv14956/docs

Modified Files:
	buildbot.texinfo 
Log Message:
[project @ add BuildStep URLs]

Original author: warner at lothar.com
Date: 2006-08-20 22:24:14

Index: buildbot.texinfo
===================================================================
RCS file: /cvsroot/buildbot/buildbot/docs/buildbot.texinfo,v
retrieving revision 1.67
retrieving revision 1.68
diff -u -d -r1.67 -r1.68
--- buildbot.texinfo	14 Aug 2006 03:46:27 -0000	1.67
+++ buildbot.texinfo	20 Aug 2006 22:25:35 -0000	1.68
@@ -188,6 +188,7 @@
 
 * BuildStep LogFiles::          
 * Adding LogObservers::         
+* BuildStep URLs::              
 
 Build Factories
 
@@ -3685,6 +3686,7 @@
 @menu
 * BuildStep LogFiles::          
 * Adding LogObservers::         
+* BuildStep URLs::              
 @end menu
 
 @node BuildStep LogFiles, Adding LogObservers, Writing New BuildSteps, Writing New BuildSteps
@@ -3778,7 +3780,7 @@
 source of a LogObserver just like the normal ``stdio'' LogFile.
 
 
- at node Adding LogObservers,  , BuildStep LogFiles, Writing New BuildSteps
+ at node Adding LogObservers, BuildStep URLs, BuildStep LogFiles, Writing New BuildSteps
 @subsubsection Adding LogObservers
 
 @cindex LogObserver
@@ -3876,6 +3878,83 @@
 automatically given a reference to the step in its @code{.step}
 attribute.
 
+ at node BuildStep URLs,  , Adding LogObservers, Writing New BuildSteps
+ at subsubsection BuildStep URLs
+
+ at cindex links
+ at cindex BuildStep URLs
+ at cindex addURL
+
+Each BuildStep has a collection of ``links''. Like its collection of
+LogFiles, each link has a name and a target URL. The web status page
+creates HREFs for each link in the same box as it does for LogFiles,
+except that the target of the link is the external URL instead of an
+internal link to a page that shows the contents of the LogFile.
+
+These external links can be used to point at build information hosted
+on other servers. For example, the test process might produce an
+intricate description of which tests passed and failed, or some sort
+of code coverage data in HTML form, or a PNG or GIF image with a graph
+of memory usage over time. The external link can provide an easy way
+for users to navigate from the buildbot's status page to these
+external web sites or file servers. Note that the step itself is
+responsible for insuring that there will be a document available at
+the given URL (perhaps by using @command{scp} to copy the HTML output
+to a @file{~/public_html/} directory on a remote web server). Calling
+ at code{addURL} does not magically populate a web server.
+
+To set one of these links, the BuildStep should call the @code{addURL}
+method with the name of the link and the target URL. Multiple URLs can
+be set.
+
+In this example, we assume that the @command{make test} command causes
+a collection of HTML files to be created and put somewhere on the
+coverage.example.org web server, in a filename that incorporates the
+build number.
+
+ at example
+class TestWithCodeCoverage(BuildStep):
+    command = ["make", "test",
+               WithProperties("buildnum=%s" % "buildnumber")]
+
+    def createSummary(self, log):
+        buildnumber = self.getProperty("buildnumber")
+        url = "http://coverage.example.org/builds/%s.html" % buildnumber
+        self.addURL("coverage", url)
+ at end example
+
+You might also want to extract the URL from some special message
+output by the build process itself:
+
+ at example
+class TestWithCodeCoverage(BuildStep):
+    command = ["make", "test",
+               WithProperties("buildnum=%s" % "buildnumber")]
+
+    def createSummary(self, log):
+        output = StringIO(log.getText())
+        for line in output.readlines():
+            if line.startswith("coverage-url:"):
+                url = line[len("coverage-url:"):].strip()
+                self.addURL("coverage", url)
+                return
+ at end example
+
+Note that a build process which emits both stdout and stderr might
+cause this line to be split or interleaved between other lines. It
+might be necessary to restrict the getText() call to only stdout with
+something like this:
+
+ at example
+        output = StringIO("".join([c[1]
+                                   for c in log.getChunks()
+                                   if c[0] == LOG_CHANNEL_STDOUT]))
+ at end example
+
+Of course if the build is run under a PTY, then stdout and stderr will
+be merged before the buildbot ever sees them, so such interleaving
+will be unavoidable.
+
 
 @node Interlocks, Build Factories, Build Steps, Build Process
 @section Interlocks