Added manual/docs, fixed reference in releasenotes

master/buildbot/steps/slave.py

@@ -19,7 +19,6 @@
 from buildbot.process import buildstep
 from buildbot.status.results import FAILURE
 from buildbot.status.results import SUCCESS
-from twisted.internet import defer
 
 
 class SlaveBuildStep(buildstep.BuildStep):

master/docs/manual/customization.rst

@@ -908,6 +908,88 @@ 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.
 
+Discovering files
+~~~~~~~~~~~~~~~~~
+
+When implementing a :class:`BuildStep` it may be necessary to know about files
+that are created during the build.  There are a few slave commands that can be
+used to find files on the slave and test for the existence (and type) of files
+and directories.
+
+The slave provides the following file-discovery related commands:
+
+* `stat` calls :func:`os.stat` for a file in the slave's build directory. This
+  can be used to check if a known file exists and whether it is a regular file,
+  directory or symbolic link.
+
+* `listdir` calls :func:`os.listdir` for a directory on the slave. It can be
+  used to obtain a list of files that are present in a directory on the slave.
+
+* `glob` calls :func:`glob.glob` on the slave, with a given shell-style pattern
+  containing wildcards.
+
+For example, we could use stat to check if a given path exists and contains
+``*.pyc`` files. If the path does not exist (or anything fails) we mark the step
+as failed; if the path exists but is not a directory, we mark the step as having
+"warnings". ::
+
+    from buildbot.process import buildstep
+    from buildbot.interfaces import BuildSlaveToOldError
+    from buildbot.status.results import SUCCESS, WARNINGS, FAILURE
+    import stat
+    
+    class MyBuildStep(buildstep.BuildStep):
+    
+        def __init__(self, dirname, **kwargs):
+            buildstep.BuildStep.__init__(self, **kwargs)
+            self.dirname = dirname
+    
+        def start(self):
+            # make sure the slave knows about stat
+            slavever = (self.slaveVersion('stat'),
+                        self.slaveVersion('glob'))
+            if not all(slavever):
+                raise BuildSlaveToOldError('need stat and glob')
+    
+            cmd = buildstep.RemoteCommand('stat', {'file': self.dirname})
+    
+            d = self.runCommand(cmd)
+            d.addCallback(lambda res: evaluateStat(cmd))
+            d.addErrback(self.failed)
+            return d
+    
+        def evaluateStat(self, cmd):
+            if cmd.didFail():
+                self.step_status.setText(["File not found."])
+                self.finished(FAILURE)
+                return
+            s = cmd.updates["stat"][-1]
+            if not stat.S_ISDIR(s[stat.ST_MODE]):
+                self.step_status.setText(["'tis not a directory"])
+                self.finished(WARNINGS)
+                return
+    
+            cmd = buildstep.RemoteCommand('glob', {'glob': self.dirname + '/*.pyc'}))
+    
+            d = self.runCommand(cwd)
+            d.addCallback(lambda res: evaluateGlob(cmd))
+            d.addErrback(self.failed)
+            return d
+    
+        def evaluateGlob(self, cmd):
+            if cmd.didFail():
+                self.step_status.setText(["Glob failed."])
+                self.finished(FAILURE)
+                return
+            files = cmd.updates["files"][-1]
+            if len(files):
+                self.step_status.setText(["Found pycs"]+files)
+            else:
+                self.step_status.setText(["No pycs found"])
+            self.finished(SUCCESS)
+
+For more information on the available commands, see :doc:`../developer/master-slave`.
+
 .. todo::
 
     Step Progress

master/docs/relnotes/index.rst

@@ -125,7 +125,7 @@ Features
 
 * The :bb:step:`HTTPStep` step can make arbitrary HTTP requests from the master, allowing communication with external APIs.
   This new feature requires the optional ``txrequests`` and ``requests`` Python packages.
-  
+
 * :bb:step:`CVS` source step now checks for "sticky dates" from a previous checkout before updating an existing source directory.
 
 * The IRC bot of :bb:status:`IRC` will, unless useRevisions is set, shorten
@@ -182,7 +182,7 @@ Deprecations, Removals, and Non-Compatible Changes
 Changes for Developers
 ~~~~~~~~~~~~~~~~~~~~~~
 
-* The :bb:step:`CompositeStepMixin` now provides a ``runGlob`` method to check for files on the slave that match a given shell-style pattern.
+* The :py:class:`CompositeStepMixin` now provides a ``runGlob`` method to check for files on the slave that match a given shell-style pattern.
 
 Slave
 -----