From 5df951f9232e9b0742dbdc22cf6df7db95944abe Mon Sep 17 00:00:00 2001 From: kohsuke Date: Sat, 7 Apr 2007 04:19:20 +0000 Subject: [PATCH] doc improvement. git-svn-id: https://hudson.dev.java.net/svn/hudson/trunk/hudson/main@2902 71c3de6d-444a-0410-be80-ed276b4c234a --- core/src/main/java/hudson/scm/SCM.java | 38 ++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/core/src/main/java/hudson/scm/SCM.java b/core/src/main/java/hudson/scm/SCM.java index fe3ed9c3c9..8b6fe114b9 100644 --- a/core/src/main/java/hudson/scm/SCM.java +++ b/core/src/main/java/hudson/scm/SCM.java @@ -3,6 +3,7 @@ package hudson.scm; import hudson.ExtensionPoint; import hudson.FilePath; import hudson.Launcher; +import hudson.tasks.Builder; import hudson.model.AbstractBuild; import hudson.model.AbstractProject; import hudson.model.BuildListener; @@ -122,7 +123,44 @@ public abstract class SCM implements Describable, ExtensionPoint { /** * Gets the top directory of the checked out module. + * + *

+ * Often SCMs have to create a directory inside a workspace, which + * creates directory layout like this: + * + *

+     * workspace  <- workspace root
+     *  +- xyz    <- directory checked out by SCM
+     *      +- CVS
+     *      +- build.xml  <- user file
+     * 
+ * + *

+ * Many builders, like Ant or Maven, works off the specific user file + * at the top of the checked out module (in the above case, that would + * be xyz/build.xml), yet the builder doesn't know the "xyz" + * part; that comes from SCM. + * + *

+ * Collaboration between {@link Builder} and {@link SCM} allows + * Hudson to find build.xml wihout asking the user to enter "xyz" again. + * + *

+ * This method is for this purpose. It takes the workspace + * root as a parameter, and expected to return the directory + * that was checked out from SCM. + * + *

+ * If this SCM is configured to create a directory, try to + * return that directory so that builders can work seamlessly. + * + *

+ * If SCM doesn't need to create any directory inside workspace, + * or in any other tricky cases, it should revert to the default + * implementation, which is to just return the parameter. + * * @param workspace + * The workspace root directory. */ public FilePath getModuleRoot(FilePath workspace) { return workspace;