From 53cdbd10e61543d4863b419c3d6bc9ea383ac824 Mon Sep 17 00:00:00 2001
From: Stefan Bodewig <bodewig@apache.org>
Date: Fri, 18 Jul 2008 13:09:30 +0000
Subject: [PATCH] some notes on running Ant as a background process.  PR 34461.

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@677899 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/CoreTasks/apply.html |  9 +++++++++
 docs/manual/CoreTasks/exec.html  |  9 +++++++++
 docs/manual/CoreTasks/java.html  | 10 ++++++++++
 docs/manual/running.html         | 16 ++++++++++++++++
 docs/manual/runninglist.html     |  1 +
 5 files changed, 45 insertions(+)

diff --git a/docs/manual/CoreTasks/apply.html b/docs/manual/CoreTasks/apply.html
index 9954950bf..814d9ab6e 100644
--- a/docs/manual/CoreTasks/apply.html
+++ b/docs/manual/CoreTasks/apply.html
@@ -52,6 +52,15 @@ and you must not specify more than one mapper.</p>
 <p>Note that you cannot interact with the forked program, the only way
 to send input to it is via the input and inputstring attributes.</p>
 
+<h4><a name="background">Running Ant as a background process on
+    Unix(-like) systems</a></h4>
+
+<p>If you run Ant as a background process (like <code>ant &</code>)
+  and use the <code>&lt;apply&gt;</code> task with <code>spawn</code>
+  set to <code>false</code>, you must provide explicit input to the
+  forked process or Ant will be suspended because it tries to read
+  from the standard input.</p>
+
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
   <tr>
diff --git a/docs/manual/CoreTasks/exec.html b/docs/manual/CoreTasks/exec.html
index 91e9c65bb..e0a9b46b9 100644
--- a/docs/manual/CoreTasks/exec.html
+++ b/docs/manual/CoreTasks/exec.html
@@ -131,6 +131,15 @@ or the task will fail as follows:
 </blockquote>
 </p>
 
+<h4><a name="background">Running Ant as a background process on
+    Unix(-like) systems</a></h4>
+
+<p>If you run Ant as a background process (like <code>ant &</code>)
+  and use the <code>&lt;exec&gt;</code> task with <code>spawn</code>
+  set to <code>false</code>, you must provide explicit input to the
+  forked process or Ant will be suspended because it tries to read
+  from the standard input.</p>
+
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
   <tr>
diff --git a/docs/manual/CoreTasks/java.html b/docs/manual/CoreTasks/java.html
index cc46d7418..7389729f7 100644
--- a/docs/manual/CoreTasks/java.html
+++ b/docs/manual/CoreTasks/java.html
@@ -36,6 +36,16 @@ JVM.
 sending input to it via the <code>input</code> and <code>inputstring</code>
 attributes.</p>
 
+<h4><a name="background">Running Ant as a background process on
+    Unix(-like) systems</a></h4>
+
+<p>If you run Ant as a background process (like <code>ant &</code>)
+  and use the <code>&lt;java&gt;</code> task with <code>spawn</code>
+  set to <code>false</code> and <code>fork</code>
+  to <code>true</code>, you must provide explicit input to the forked
+  process or Ant will be suspended because it tries to read from the
+  standard input.</p>
+
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
   <tr>
diff --git a/docs/manual/running.html b/docs/manual/running.html
index 90c24afaf..59d94ae2c 100644
--- a/docs/manual/running.html
+++ b/docs/manual/running.html
@@ -520,6 +520,22 @@ shell (of course unless called automatically from <code>ant.cmd</code>). It is t
 <p>Scripts <code>envset.cmd</code> and <code>runrc.cmd</code> perform auxiliary tasks. All scripts
 have some documentation inside.</p>
 
+<h2><a name="background">Running Ant as a background process on
+    Unix(-like) systems</a></h2>
+
+<p>If you start Ant as a background process (like in <code>ant
+    &</code>) and the build process creates another process, Ant will
+    immediately try to read from standard input, which in turn will
+    most likely suspend the process.  In order to avoid this, you must
+    redirect Ant's standard input or explicitly provide input to each
+    spawned process via the input related attributes of the
+    corresponding tasks.</p>
+
+<p>Tasks that create such new processes
+  include <code>&lt;exec&gt;</code>, <code>&lt;apply&gt;</code>
+  or <code>&lt;java&gt;</code> when the <code>fork</code> attribute is
+  <code>true</code>.</p>
+
 <h2><a name="viajava">Running Ant via Java</a></h2>
 <p>If you have installed Ant in the do-it-yourself way, Ant can be started
 from one of two entry points:</p>
diff --git a/docs/manual/runninglist.html b/docs/manual/runninglist.html
index 062d9453f..ae61f2745 100644
--- a/docs/manual/runninglist.html
+++ b/docs/manual/runninglist.html
@@ -37,6 +37,7 @@
   <a href="running.html#sysprops">Java System Properties</a><br/>
   <a href="running.html#cygwin">Cygwin Users</a><br/>
   <a href="running.html#os2">OS/2 Users</a><br/>
+  <a href="running.html#background">Running "in the background"</a><br/>
 </div>
 <a href="running.html#viajava">Running Ant via Java</a><br/>