[Buildbot-commits] buildbot/docs buildbot.texinfo,1.75,1.76

[Brian Warner]

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

Modified Files:
	buildbot.texinfo 
Log Message:
[project @ filetransfer: add a unit test, docs, do some cleanup]

Original author: warner at lothar.com
Date: 2006-09-09 06:11:59

Index: buildbot.texinfo
===================================================================
RCS file: /cvsroot/buildbot/buildbot/docs/buildbot.texinfo,v
retrieving revision 1.75
retrieving revision 1.76
diff -u -d -r1.75 -r1.76
--- buildbot.texinfo	15 Sep 2006 14:47:42 -0000	1.75
+++ buildbot.texinfo	15 Sep 2006 14:49:33 -0000	1.76
@@ -165,6 +165,7 @@
 * Source Checkout::             
 * ShellCommand::                
 * Simple ShellCommand Subclasses::  
+* Transferring Files::          
 * Writing New BuildSteps::      
 
 Source Checkout
@@ -2859,6 +2860,7 @@
 * Source Checkout::             
 * ShellCommand::                
 * Simple ShellCommand Subclasses::  
+* Transferring Files::          
 * Writing New BuildSteps::      
 @end menu
 
@@ -3498,7 +3500,7 @@
 
 @end table
 
- at node Simple ShellCommand Subclasses, Writing New BuildSteps, ShellCommand, Build Steps
+ at node Simple ShellCommand Subclasses, Transferring Files, ShellCommand, Build Steps
 @subsection Simple ShellCommand Subclasses
 
 Several subclasses of ShellCommand are provided as starting points for
@@ -3692,8 +3694,64 @@
 
 @end table
 
+ at node Transferring Files, Writing New BuildSteps, Simple ShellCommand Subclasses, Build Steps
+ at subsection Transferring Files
 
- at node Writing New BuildSteps,  , Simple ShellCommand Subclasses, Build Steps
+ at cindex File Transfer
+ at bsindex buildbot.steps.transfer.FileUpload
+ at bsindex buildbot.steps.transfer.FileDownload
+
+Most of the work involved in a build will take place on the
+buildslave. But occasionally it is useful to do some work on the
+buildmaster side. The most basic way to involve the buildmaster is
+simply to move a file from the slave to the master, or vice versa.
+There are a pair of BuildSteps named @code{FileUpload} and
+ at code{FileDownload} to provide this functionality.
+
+As an example, let's assume that there is a step which produces an
+HTML file within the source tree that contains some sort of generated
+project documentation. We want to move this file to the buildmaster,
+into a @file{~/public_html} directory, so it can be visible to
+developers. This file will wind up in the slave-side working directory
+under the name @file{docs/reference.html}. We want to put it into the
+master-side @file{~/public_html/ref.html}.
+
+ at example
+from buildbot.steps.shell import ShellCommand
+from buildbot.steps.transfer import FileUpload
+
+f.addStep(ShellCommand, command=["make", "docs"])
+f.addStep(FileUpload,
+          slavesrc="docs/reference.html",
+          masterdest="~/public_html/ref.html")
+ at end example
+
+The @code{masterdest=} argument will be passed to os.path.expanduser,
+so things like ``~'' will be expanded properly. Non-absolute paths
+will be interpreted relative to the buildmaster's base directory.
+Likewise, the @code{slavesrc=} argument will be expanded and
+interpreted relative to the builder's working directory.
+
+
+To move a file from the master to the slave, use the
+ at code{FileDownload} command. For example, let's assume that some step
+requires a configuration file that, for whatever reason, could not be
+recorded in the source code repository or generated on the buildslave
+side:
+
+ at example
+from buildbot.steps.shell import ShellCommand
+from buildbot.steps.transfer import FileUpload
+
+f.addStep(FileDownload
+          mastersrc="~/todays_build_config.txt",
+          slavedest="build_config.txt")
+f.addStep(ShellCommand, command=["make", "config"])
+ at end example
+
+
+
+ at node Writing New BuildSteps,  , Transferring Files, Build Steps
 @subsection Writing New BuildSteps
 
 While it is a good idea to keep your build process self-contained in