allowNativeBasedir -> useNativeBasedir. Document it. PR 45711.

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@690969 13f79535-47bb-0310-9956-ffa450edef68

WHATSNEW

@@ -320,6 +320,12 @@ Other changes:
    Previously the absence of the index was not enough to trigger the rebuild;
    some other update was necessary.  Bugzilla report 45098.
 
+ * <ant> has a new attribute "useNativeBasedir" that makes the child
+   build use the same basedir it would have used if invoked from the
+   command line.  No matter what other attributes/properties have been
+   set.
+   Bugzilla Report 45711.
+
 Changes from Ant 1.7.0 TO Ant 1.7.1
 =============================================
 

docs/manual/CoreTasks/ant.html

@@ -80,7 +80,8 @@ inside of targets.</p>
   </tr>
   <tr>
     <td valign="top">dir</td>
-    <td valign="top">the directory to use as a basedir for the new Ant project.
+    <td valign="top">the directory to use as a basedir for the new Ant
+      project (unless useNativeBasedir is set to true).
       Defaults to the current project's basedir, unless
       inheritall has been set to false, in which case it doesn't
       have a default value.  This will override the basedir
@@ -116,6 +117,15 @@ inside of targets.</p>
       new Ant project.  Defaults to <code>false</code>.</td>
     <td align="center" valign="top">No</td>
   </tr>
+  <tr>
+    <td valign="top">useNativeBasedir</td>
+    <td valign="top">If set to true, the child build will use the same
+      basedir as it would have used when run from the command line
+      (i.e. the basedir one would expect when looking at the child
+      build's buildfile).  Defaults to <code>false</code>.  <em>since
+      Ant 1.8.0</em></td>
+    <td valign="top" align="center">No</td>
+  </tr>
 </table>
 
 <h3>Parameters specified as nested elements</h3>
@@ -182,6 +192,17 @@ targets so specified, in the order specified.</p>
 
 <h3>Basedir of the new project</h3>
 
+<p>If you set <code>useNativeBasedir</code> to true, the basedir of
+  the new project will be whatever the basedir attribute of
+  the <code>&lt;project&gt;</code> element of the new project says (or
+  the new project's directory if the there is no basedir attribute) -
+  no matter what any other attribute of this task says and no matter
+  how deeply nested into levels of
+  <code>&lt;ant&gt;</code> invocations this task lives.</p>
+ 
+<p>If you haven't set <code>useNativeBasedir</code> or set it to
+  false, the following rules apply:</p>
+
 <p>The basedir value of the new project is affected by the two
   attributes dir and inheritall as well as
   the <code>&lt;ant&gt;</code> task's history.  The current behaviour

src/main/org/apache/tools/ant/taskdefs/Ant.java

@@ -113,7 +113,7 @@ public class Ant extends Task {
      *
      * @since Ant 1.8.0
      */
-    private boolean allowNativeBasedir = false;
+    private boolean useNativeBasedir = false;
 
     /**
      * simple constructor
@@ -137,8 +137,8 @@ public class Ant extends Task {
      *
      * @since Ant 1.8.0
      */
-    public void setAllowNativeBasedir(boolean b) {
-        allowNativeBasedir = b;
+    public void setUseNativeBasedir(boolean b) {
+        useNativeBasedir = b;
     }
 
     /**
@@ -215,7 +215,7 @@ public class Ant extends Task {
             }
         }
         // set user-defined properties
-        if (allowNativeBasedir) {
+        if (useNativeBasedir) {
             addAlmostAll(getProject().getUserProperties(), PropertyType.USER);
         } else {
             getProject().copyUserProperties(newProject);
@@ -344,7 +344,7 @@ public class Ant extends Task {
             initializeProject();
 
             if (dir != null) {
-                if (!allowNativeBasedir) {
+                if (!useNativeBasedir) {
                     newProject.setBaseDir(dir);
                     if (savedDir != null) {
                         // has been set explicitly
@@ -494,7 +494,7 @@ public class Ant extends Task {
             p.setProject(newProject);
             p.execute();
         }
-        if (allowNativeBasedir) {
+        if (useNativeBasedir) {
             addAlmostAll(getProject().getInheritedProperties(),
                          PropertyType.INHERITED);
         } else {

src/main/org/apache/tools/ant/taskdefs/SubAnt.java

@@ -554,7 +554,7 @@ public class SubAnt extends Task {
         if (directory != null) {
             antTask.setDir(directory);
         } else {
-            antTask.setAllowNativeBasedir(true);
+            antTask.setUseNativeBasedir(true);
         }
 
         antTask.setInheritAll(inheritAll);

src/tests/antunit/taskdefs/subant-test.xml

@@ -62,7 +62,7 @@
   <target name="testSubAntDoesntSetBasedirAfterAntWithDirWhenNativeDir">
     <ant antfile="${ant.file}" dir="${basedir}"
          target="testSubAntDoesntSetBasedir"
-         allowNativeBaseDir="true"/>
+         useNativeBaseDir="true"/>
   </target>
 
 </project>