2006-09-11 04:19:00 +00:00
|
|
|
<!--
|
|
|
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
|
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
|
|
|
this work for additional information regarding copyright ownership.
|
|
|
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
|
|
|
(the "License"); you may not use this file except in compliance with
|
|
|
|
|
the License. You may obtain a copy of the License at
|
|
|
|
|
|
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
|
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
|
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
|
See the License for the specific language governing permissions and
|
|
|
|
|
limitations under the License.
|
|
|
|
|
-->
|
2005-02-07 23:42:21 +00:00
|
|
|
<html>
|
2001-02-13 12:32:01 +00:00
|
|
|
|
|
|
|
|
<head>
|
2007-05-02 06:15:35 +00:00
|
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
|
|
|
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
|
|
|
|
<title>Exec Task</title>
|
2001-02-13 12:32:01 +00:00
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
2018-01-22 23:52:21 +01:00
|
|
|
<h2 id="exec">Exec</h2>
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Description</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Executes a system command. When the <var>os</var> attribute is specified, then the command is
|
|
|
|
|
only executed when Apache Ant is run on one of the specified operating systems.</p>
|
2003-02-01 14:21:27 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<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. Also note that <em>since Ant 1.6</em>, any attempt to read
|
|
|
|
|
input in the forked program will receive an EOF (<q>-1</q>). This is a change from Ant 1.5, where
|
|
|
|
|
such an attempt would block.</p>
|
2003-10-13 13:08:52 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>If you want to execute an executable using a path relative to the project's <var>basedir</var>,
|
|
|
|
|
you may need to use <var>vmlauncher</var>=<q>false</q> on some operating systems—but even this
|
|
|
|
|
may fail (Solaris 8/9 has been reported as problematic). The <var>resolveexecutable</var> attribute
|
|
|
|
|
should be more reliable, as would be something like</p>
|
2008-07-16 15:56:12 +00:00
|
|
|
<pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
<property name="executable-full-path"
|
|
|
|
|
location="../relative/path/to/executable"/>
|
|
|
|
|
<exec executable="${executable-full-path}" ...</pre>
|
2004-11-05 08:58:09 +00:00
|
|
|
|
|
|
|
|
<h4>Windows Users</h4>
|
2004-11-19 09:07:12 +00:00
|
|
|
<p>The <code><exec></code> task delegates to <code>Runtime.exec</code> which in turn
|
2018-02-28 07:58:59 +01:00
|
|
|
apparently
|
2018-03-08 07:43:53 +01:00
|
|
|
calls <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms682425(v=vs.85).aspx"
|
|
|
|
|
target="_top"><code>::CreateProcess</code></a>. It is the latter Win32 function that defines the
|
|
|
|
|
exact semantics of the call. In particular, if you do not put a file extension on the executable,
|
|
|
|
|
only <samp>.EXE</samp> files are looked for, not <samp>.COM</samp>, <samp>.CMD</samp> or other file
|
|
|
|
|
types listed in the environment variable <code>PATHEXT</code>. That is only used by the shell.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Note that <samp>.bat</samp> files cannot in general by executed directly. One normally needs to
|
2018-03-10 20:17:33 +01:00
|
|
|
execute the command shell executable <kbd>cmd</kbd> using the <kbd>/c</kbd> switch.</p>
|
2006-10-22 21:31:41 +00:00
|
|
|
<pre>
|
|
|
|
|
<target name="help">
|
|
|
|
|
<exec executable="cmd">
|
|
|
|
|
<arg value="/c"/>
|
|
|
|
|
<arg value="ant.bat"/>
|
|
|
|
|
<arg value="-p"/>
|
|
|
|
|
</exec>
|
2018-02-28 07:58:59 +01:00
|
|
|
</target></pre>
|
2004-11-05 08:58:09 +00:00
|
|
|
|
2018-03-10 20:42:33 +01:00
|
|
|
<p>A common problem is not having the executable on the <code>PATH</code>. In case you get an error
|
|
|
|
|
message <code class="output">Cannot run program "...":CreateProcess error=2. The system cannot find
|
|
|
|
|
the path specified.</code> have a look at your <code>PATH</code> variable. Just type the command
|
|
|
|
|
directly on the command line and if Windows finds it, Ant should do it too. (Otherwise ask on the
|
|
|
|
|
user mailinglist for help.) If Windows can not execute the program, add the directory of the program
|
|
|
|
|
to the <code>PATH</code> (<code>set PATH=%PATH%;dirOfProgram</code>) or specify the absolute path in
|
|
|
|
|
the <var>executable</var> attribute in your buildfile.</p>
|
2009-08-31 05:27:02 +00:00
|
|
|
|
2003-02-01 14:21:27 +00:00
|
|
|
<h4>Cygwin Users</h4>
|
2018-03-10 20:17:33 +01:00
|
|
|
<p>The <code><exec></code> task will not understand paths such as <q>/bin/sh</q> for
|
|
|
|
|
the <var>executable</var> parameter. This is because JVM in which Ant is running is a standard
|
|
|
|
|
Windows executable and is not aware of the Cygwin environment (i.e., doesn't
|
|
|
|
|
load <samp>cygwin1.dll</samp>). The only work-around for this is to compile a JVM under Cygwin (at
|
|
|
|
|
your own risk). See for
|
2018-03-08 07:43:53 +01:00
|
|
|
instance <a href="https://cdn.rawgit.com/AdoptOpenJDK/openjdk-jdk9/dev/common/doc/building.html#cygwin"
|
|
|
|
|
target="_top">OpenJDK build instructions for cygwin</a>.</p>
|
2003-12-08 02:27:14 +00:00
|
|
|
|
2003-07-25 10:06:32 +00:00
|
|
|
<h4>OpenVMS Users</h4>
|
2018-03-10 20:17:33 +01:00
|
|
|
<p>The command specified using <var>executable</var> and <code><arg></code> elements is
|
2018-02-28 07:58:59 +01:00
|
|
|
executed exactly as specified inside a temporary DCL script. This has some implications:</p>
|
2003-09-25 12:36:19 +00:00
|
|
|
<ul>
|
2018-02-28 07:58:59 +01:00
|
|
|
<li>paths have to be written in VMS style</li>
|
|
|
|
|
<li>if your <var>executable</var> points to a DCL script remember to prefix it with
|
|
|
|
|
an <q>@</q>-sign (e.g. <var>executable</var>=<q>@[FOO]BAR.COM</q>), just as you would in a DCL
|
|
|
|
|
script</li>
|
2003-09-25 12:36:19 +00:00
|
|
|
</ul>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>For <code><exec></code> to work in an environment with a JVM older than version 1.4.1-2 it
|
|
|
|
|
is also <em>required</em> that the logical <code>JAVA$FORK_SUPPORT_CHDIR</code> is set
|
|
|
|
|
to <code>TRUE</code> in the job table (see the <em>JDK Release Notes</em>).</p>
|
2003-09-25 12:36:19 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Please note that JVM provided by HP doesn't follow OpenVMS' conventions of exit codes. If you
|
|
|
|
|
run a JVM with this task, the task may falsely claim that an error occurred (or silently ignore an
|
2018-03-10 20:17:33 +01:00
|
|
|
error). Don't use this task to run <kbd>JAVA.EXE</kbd>, use a <code><java></code> task with
|
2018-02-28 07:58:59 +01:00
|
|
|
the <var>fork</var> attribute set to <q>true</q> instead as this task will follow the JVM's
|
2003-08-01 10:08:12 +00:00
|
|
|
interpretation of exit codes.</p>
|
|
|
|
|
|
2004-04-13 10:36:42 +00:00
|
|
|
<h4>RedHat S/390 Users</h4>
|
2018-03-08 07:43:53 +01:00
|
|
|
<p>It has been <a href="https://www.mail-archive.com/linux-390@vm.marist.edu/msg22223.html"
|
|
|
|
|
target="_top">reported on linux-390</a> that shell scripts invoked via the Ant Exec task must have
|
|
|
|
|
their interpreter specified, i.e., the scripts must start with something like:</p>
|
2004-04-13 10:36:42 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre>#!/bin/bash</pre>
|
2018-01-22 23:52:21 +01:00
|
|
|
<p>or the task will fail as follows:</p>
|
2018-03-10 20:17:33 +01:00
|
|
|
<pre class="output">
|
2004-04-13 10:36:42 +00:00
|
|
|
[exec] Warning: UNIXProcess.forkAndExec native error: Exec format error
|
2018-02-28 07:58:59 +01:00
|
|
|
[exec] Result: 255</pre>
|
2004-04-13 10:36:42 +00:00
|
|
|
|
2018-01-22 23:52:21 +01:00
|
|
|
<h4 id="background">Running Ant as a background process on Unix(-like) systems</h4>
|
2008-07-18 13:09:30 +00:00
|
|
|
|
2018-03-10 20:42:33 +01:00
|
|
|
<p>If you run Ant as a background process (like <kbd>ant &</kbd>) and use
|
2018-02-28 07:58:59 +01:00
|
|
|
the <code><exec></code> task with <var>spawn</var> set to <q>false</q>, you must provide
|
|
|
|
|
explicit input to the forked process or Ant will be suspended because it tries to read from the
|
|
|
|
|
standard input.</p>
|
2008-07-18 13:09:30 +00:00
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Parameters</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>command</td>
|
|
|
|
|
<td>the command to execute with all command line arguments. <em><u>Deprecated</u>,
|
|
|
|
|
use <var>executable</var> and nested <code><arg></code> elements instead</em>.</td>
|
|
|
|
|
<td rowspan="2">Exactly one of the two</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>executable</td>
|
|
|
|
|
<td class="left">the command to execute without any command line arguments.</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>dir</td>
|
|
|
|
|
<td>the directory in which the command should be executed.</td>
|
|
|
|
|
<td>No; if <var>vmlauncher</var> is <q>true</q>, defaults to the current working directory,
|
|
|
|
|
otherwise the project's <var>basedir</var></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>os</td>
|
|
|
|
|
<td>list of Operating Systems on which the command may be executed. If the current OS's name is
|
|
|
|
|
contained in this list, the command will be executed. The OS's name is determined by JVM and
|
|
|
|
|
is set in the <code>os.name</code> system property.
|
2005-04-19 22:28:22 +00:00
|
|
|
</td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No</td>
|
2005-04-19 22:28:22 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>osfamily</td>
|
|
|
|
|
<td>OS family as used in the <code><os></code> condition. <em>since Ant 1.7</em></td>
|
|
|
|
|
<td>No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2003-07-28 10:39:31 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>spawn</td>
|
|
|
|
|
<td>whether or not you want the command to be spawned<br/>If you spawn a command, its output
|
|
|
|
|
will not be logged by Ant.<br/>The <var>input</var>, <var>output</var>, <var>error</var>,
|
|
|
|
|
and <var>result</var> property settings are not active when spawning a process.<br/><em>since
|
|
|
|
|
Ant 1.6</em>
|
2003-07-28 10:39:31 +00:00
|
|
|
</td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No; default is <q>false</q></td>
|
2003-07-28 10:39:31 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>output</td>
|
|
|
|
|
<td>Name of a file to which to write the output. If the error stream is not also redirected to a
|
|
|
|
|
file or property, it will appear in this output.</td>
|
|
|
|
|
<td>No</td>
|
2003-02-06 12:53:49 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>error</td>
|
|
|
|
|
<td>The file to which the standard error of the command should be redirected. <em>since Ant
|
|
|
|
|
1.6</em></td>
|
|
|
|
|
<td>No</td>
|
2003-02-06 13:10:21 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>logError</td>
|
|
|
|
|
<td>This attribute is used when you wish to see error output in Ant's log and you are
|
|
|
|
|
redirecting output to a file/property. The error output will not be included in the output
|
|
|
|
|
file/property. If you redirect error with the <var>error</var> or <var>errorProperty</var>
|
|
|
|
|
attributes, this will have no effect. <em>since Ant 1.6</em></td>
|
|
|
|
|
<td>No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2002-04-05 09:28:54 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>append</td>
|
|
|
|
|
<td>Whether output and error files should be appended to or overwritten.</td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2002-04-05 09:28:54 +00:00
|
|
|
</tr>
|
2001-07-27 09:55:46 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>outputproperty</td>
|
|
|
|
|
<td>The name of a property in which the output of the command should be stored. Unless the error
|
|
|
|
|
stream is redirected to a separate file or stream, this property will include the error
|
|
|
|
|
output.</td>
|
|
|
|
|
<td>No</td>
|
2003-02-06 12:53:49 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>errorproperty</td>
|
|
|
|
|
<td>The name of a property in which the standard error of the command should be
|
|
|
|
|
stored. <em>since Ant 1.6</em></td>
|
|
|
|
|
<td>No</td>
|
2001-07-27 09:55:46 +00:00
|
|
|
</tr>
|
2003-02-09 12:17:16 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>input</td>
|
|
|
|
|
<td>A file from which the executed command's standard input is taken. This attribute is mutually
|
|
|
|
|
exclusive with the <var>inputstring</var> attribute. <em>since Ant 1.6</em></td>
|
|
|
|
|
<td>No</td>
|
2003-02-09 12:17:16 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>inputstring</td>
|
|
|
|
|
<td>A string which serves as the input stream for the executed command. This attribute is
|
|
|
|
|
mutually exclusive with the <var>input</var> attribute. <em>since Ant 1.6</em></td>
|
|
|
|
|
<td>No</td>
|
2003-02-09 12:17:16 +00:00
|
|
|
</tr>
|
2001-11-27 19:44:46 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>resultproperty</td>
|
|
|
|
|
<td>the name of a property in which the return code of the command should be stored. Only of
|
|
|
|
|
interest if <var>failonerror</var>=<q>false</q>.</td>
|
|
|
|
|
<td>No</td>
|
2001-11-27 19:44:46 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>timeout</td>
|
|
|
|
|
<td>Stop the command if it doesn't finish within the specified time (given in
|
|
|
|
|
milliseconds).</td>
|
|
|
|
|
<td>No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>failonerror</td>
|
|
|
|
|
<td>Stop the build process if the command exits with a return code signaling failure.</td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>failifexecutionfails</td>
|
|
|
|
|
<td>Stop the build if we can't start the program.</td>
|
|
|
|
|
<td>No; defaults to <q>true</q></td>
|
2018-01-22 23:52:21 +01:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>newenvironment</td>
|
|
|
|
|
<td>Do not propagate old environment when new environment variables are specified.</td>
|
|
|
|
|
<td>No; default is <q>false</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2001-07-06 11:23:18 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>vmlauncher</td>
|
|
|
|
|
<td>Run command using the JVM's execution facilities where available. If set to <q>false</q> the
|
2018-03-10 20:17:33 +01:00
|
|
|
underlying OS's shell, either directly or through the <kbd>antRun</kbd> scripts, will be
|
2018-02-28 07:58:59 +01:00
|
|
|
used. Under some operating systems, this gives access to facilities not normally available
|
|
|
|
|
through JVM including, under Windows, being able to execute scripts, rather than their
|
|
|
|
|
associated interpreter. If you want to specify the name of the executable as a relative path
|
|
|
|
|
to the directory given by the <var>dir</var> attribute, it may become necessary to
|
|
|
|
|
set <var>vmlauncher</var> to <q>false</q> as well.</td>
|
|
|
|
|
<td>No; default is <q>true</q></td>
|
2001-07-06 11:23:18 +00:00
|
|
|
</tr>
|
2003-01-29 11:57:25 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>resolveexecutable</td>
|
|
|
|
|
<td>When this attribute is <q>true</q>, the name of the executable is resolved firstly against
|
|
|
|
|
the project <var>basedir</var> and if that does not exist, against the execution directory if
|
|
|
|
|
specified. On Unix systems, if you only want to allow execution of commands in the user's
|
|
|
|
|
path, set this to <q>false</q>. <em>since Ant 1.6</em></td>
|
|
|
|
|
<td>No; default is <q>false</q></td>
|
2003-12-08 02:27:14 +00:00
|
|
|
</tr>
|
2004-09-10 15:16:11 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>searchpath</td>
|
|
|
|
|
<td>When this attribute is <q>true</q>, then system path environment variables will be searched
|
|
|
|
|
when resolving the location of the executable. <em>since Ant 1.6.3</em></td>
|
|
|
|
|
<td>No; default is <q>false</q></td>
|
2004-09-10 15:16:11 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
</table>
|
|
|
|
|
<h3>Examples</h3>
|
|
|
|
|
<pre>
|
|
|
|
|
<exec dir="${src}" executable="cmd.exe" os="Windows 2000" output="dir.txt">
|
|
|
|
|
<arg line="/c dir"/>
|
|
|
|
|
</exec></pre>
|
2018-02-09 06:54:03 +01:00
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Parameters specified as nested elements</h3>
|
|
|
|
|
<h4>arg</h4>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Command line arguments should be specified as nested <code><arg></code>
|
|
|
|
|
elements. See <a href="../using.html#arg">Command line arguments</a>.</p>
|
2018-01-22 23:52:21 +01:00
|
|
|
<h4 id="env">env</h4>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>It is possible to specify environment variables to pass to the system command via
|
|
|
|
|
nested <code><env></code> elements.</p>
|
|
|
|
|
<table class="attr">
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>key</td>
|
|
|
|
|
<td>The name of the environment variable.<br/><strong>Note</strong>: <em>since Ant 1.7</em>, for
|
|
|
|
|
Windows, the name is case-insensitive.</td>
|
|
|
|
|
<td>Yes</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>value</td>
|
|
|
|
|
<td>The literal value for the environment variable.</td>
|
|
|
|
|
<td rowspan="3">Exactly one of these</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>path</td>
|
|
|
|
|
<td class="left">The value for a <code>PATH</code>-like environment variable. You can
|
|
|
|
|
use <q>;</q> or <q>:</q> as path separators and Ant will convert it to the platform's local
|
|
|
|
|
conventions.</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>file</td>
|
|
|
|
|
<td class="left">The value for the environment variable. Will be replaced by the absolute
|
|
|
|
|
filename of the file by Ant.</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
</table>
|
2018-01-22 23:52:21 +01:00
|
|
|
<h4 id="redirector">redirector</h4>
|
2018-01-24 21:40:28 +01:00
|
|
|
<em>Since Ant 1.6.2</em>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>A nested <a href="../Types/redirector.html">I/O Redirector</a> can be specified. In general, the
|
|
|
|
|
attributes of the redirector behave as the corresponding attributes available at the task level.
|
|
|
|
|
The most notable peculiarity stems from the retention of the <code><exec></code> attributes
|
|
|
|
|
for backwards compatibility. Any file mapping is done using a <code>null</code> sourcefile;
|
|
|
|
|
therefore not all<a href="../Types/mapper.html">Mapper</a> types will return results. When no
|
|
|
|
|
results are returned, redirection specifications will fall back to the task level attributes. In
|
|
|
|
|
practice this means that defaults can be specified for input, output, and error output files.</p>
|
2002-04-11 06:37:59 +00:00
|
|
|
<h3>Errors and return codes</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>By default the return code of a <code><exec></code> is ignored; when you
|
|
|
|
|
set <var>failonerror</var> to <q>true</q> then any return code signaling failure (OS specific)
|
|
|
|
|
causes the build to fail. Alternatively, you can set <var>resultproperty</var> to the name of a
|
|
|
|
|
property and have it assigned to the result code (barring immutability, of course).</p>
|
|
|
|
|
<p>If the attempt to start the program fails with an OS dependent error code,
|
|
|
|
|
then <code><exec></code> halts the build unless <var>failifexecutionfails</var> is set
|
|
|
|
|
to <q>false</q>. You can use that to run a program if it exists, but otherwise do nothing.</p>
|
|
|
|
|
<p>What do those error codes mean? Well, they are OS dependent. On Windows boxes you have to look
|
2018-03-08 07:43:53 +01:00
|
|
|
at <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms681382(v=vs.85).aspx"
|
|
|
|
|
target="_top">the documentation</a>; <code>error=2</code> means 'no such program', which usually
|
|
|
|
|
means it is not on the path. Any time you see such an error from any Ant task, it is usually not an
|
|
|
|
|
Ant bug, but some configuration problem on your machine.</p>
|
2002-04-11 06:37:59 +00:00
|
|
|
|
|
|
|
|
<h3>Examples</h3>
|
2018-05-15 09:51:58 +02:00
|
|
|
|
|
|
|
|
<p>Start <kbd>emacs</kbd> on display 1 of the X Window System.</p>
|
2018-02-09 06:54:03 +01:00
|
|
|
<pre>
|
2002-09-04 11:05:19 +00:00
|
|
|
<exec executable="emacs">
|
2001-02-13 12:32:01 +00:00
|
|
|
<env key="DISPLAY" value=":1.0"/>
|
|
|
|
|
</exec>
|
2018-02-09 06:54:03 +01:00
|
|
|
</pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>Add <samp>${basedir}/bin</samp> to the <code>PATH</code> of the system command.</p>
|
2018-02-09 06:54:03 +01:00
|
|
|
<pre>
|
2004-12-21 14:58:33 +00:00
|
|
|
<property environment="env"/>
|
2001-02-13 12:32:01 +00:00
|
|
|
<exec ... >
|
2004-12-21 14:58:33 +00:00
|
|
|
<env key="PATH" path="${env.PATH}:${basedir}/bin"/>
|
2001-02-13 12:32:01 +00:00
|
|
|
</exec>
|
2018-02-09 06:54:03 +01:00
|
|
|
</pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>Start the <samp>${browser}</samp> with the specified <samp>${file}</samp> and end the Ant
|
|
|
|
|
process. The browser will remain.</p>
|
2018-02-09 06:54:03 +01:00
|
|
|
<pre>
|
2005-02-07 23:42:21 +00:00
|
|
|
<property name="browser" location="C:/Program Files/Internet Explorer/iexplore.exe"/>
|
2003-09-06 15:48:01 +00:00
|
|
|
<property name="file" location="ant/docs/manual/index.html"/>
|
|
|
|
|
|
|
|
|
|
<exec executable="${browser}" spawn="true">
|
|
|
|
|
<arg value="${file}"/>
|
|
|
|
|
</exec>
|
2018-02-09 06:54:03 +01:00
|
|
|
</pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>Send the string <q>blah before blah</q> to the <kbd>cat</kbd> executable, using
|
|
|
|
|
an <a href="../Types/filterchain.html"><inputfilterchain></a> to replace <q>before</q>
|
|
|
|
|
with <q>after</q> on the way in. Output is sent to the file <samp>redirector.out</samp> and stored
|
|
|
|
|
in a property of the same name. Similarly, error output is sent to a file and a property, both
|
|
|
|
|
named <samp>redirector.err</samp>.</p>
|
2018-02-09 06:54:03 +01:00
|
|
|
<pre>
|
2004-03-27 21:22:59 +00:00
|
|
|
<exec executable="cat">
|
|
|
|
|
<redirector outputproperty="redirector.out"
|
|
|
|
|
errorproperty="redirector.err"
|
|
|
|
|
inputstring="blah before blah">
|
|
|
|
|
<inputfilterchain>
|
2004-11-19 09:07:12 +00:00
|
|
|
<replacestring from="before" to="after"/>
|
2004-03-27 21:22:59 +00:00
|
|
|
</inputfilterchain>
|
2004-11-19 09:07:12 +00:00
|
|
|
<outputmapper type="merge" to="redirector.out"/>
|
|
|
|
|
<errormapper type="merge" to="redirector.err"/>
|
2004-03-27 21:22:59 +00:00
|
|
|
</redirector>
|
|
|
|
|
</exec>
|
2018-02-09 06:54:03 +01:00
|
|
|
</pre>
|
2004-03-27 21:22:59 +00:00
|
|
|
|
2018-03-10 20:17:33 +01:00
|
|
|
<p><strong>Note</strong>: do not try to specify arguments using a simple <code>arg</code>-element
|
|
|
|
|
and separate them by spaces. This results in only a single argument containing the entire
|
|
|
|
|
string.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><strong>Timeouts</strong>: If a timeout is specified, when it is reached the sub process is
|
|
|
|
|
killed and a message printed to the log. The return value of the execution will be <q>-1</q>, which
|
|
|
|
|
will halt the build if <var>failonerror</var>=<q>true</q>, but be ignored otherwise.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
</body>
|
|
|
|
|
</html>
|
