Executes a system command.
Use of nested NAnt.Core.Tasks.ExternalProgramBase.Arguments
element(s)
is advised over the NAnt.Core.Tasks.ExecTask.CommandLineArguments
parameter, as
it supports automatic quoting and can resolve relative to absolute
paths.
Parameters
Attribute |
Type |
Description |
Required |
program
|
string |
The program to execute without command arguments.
|
True
|
basedir |
directory |
The directory the program is in.
|
False
|
commandline |
string |
The command-line arguments for the program. These will be
passed as is to the external program. When quoting is necessary,
these must be explicitly set as part of the value. Consider using
nested NAnt.Core.Tasks.ExternalProgramBase.Arguments elements instead.
|
False
|
expectedexitcode |
int |
Gets or sets the expected exit code.
|
False
|
managed |
|
Specifies whether the external program is a managed application
which should be executed using a runtime engine, if configured.
The default is false .
|
False
|
output |
file |
The file to which the standard output will be redirected.
|
False
|
append |
bool |
Gets or sets a value indicating whether output should be appended
to the output file. The default is false .
|
False
|
pidproperty |
string |
The name of a property in which the unique identifier of the spawned
application should be stored. Only of interest if NAnt.Core.Tasks.ExecTask.Spawn
is true .
|
False
|
resultproperty |
string |
The name of a property in which the exit code of the program should
be stored. Only of interest if NAnt.Core.Task.FailOnError is
false .
If the exit code of the program is "-1000" then the program could
not be started, or did not exit (in time).
|
False
|
spawn |
bool |
Gets or sets a value indicating whether the application should be
spawned. If you spawn an application, its output will not be logged
by NAnt. The default is false .
|
False
|
useruntimeengine
|
bool |
Specifies whether the external program should be executed using a
runtime engine, if configured. The default is false .
Obsolete. Use the managed attribute and Managed property instead.
|
False
|
workingdir |
directory |
The directory in which the command will be executed.
|
False
|
failonerror
|
bool |
Determines if task failure stops the build, or is just reported.
The default is true .
|
False
|
if
|
bool |
If true then the task will be executed; otherwise,
skipped. The default is true .
|
False
|
timeout
|
int |
The maximum amount of time the application is allowed to execute,
expressed in milliseconds. Defaults to no time-out.
|
False
|
unless
|
bool |
Opposite of NAnt.Core.Task.IfDefined . If false
then the task will be executed; otherwise, skipped. The default is
false .
|
False
|
verbose
|
bool |
Determines whether the task should report detailed build log messages.
The default is false .
|
False
|
Framework-configurable parameters
Attribute |
Type |
Description |
Required |
exename |
string |
The name of the executable that should be used to launch the
external program.
|
False
|
Nested elements
<arg>
The command-line arguments for the external program.
When passed to an external application, the argument will be quoted
when appropriate. This does not apply to the NAnt.Core.Types.Argument.Line
parameter, which is always passed as is.
Parameters
Attribute |
Type |
Description |
Required |
dir |
directory |
The value for a directory-based command-line argument; will be
replaced with the absolute path of the directory.
|
False
|
file |
file |
The name of a file as a single command-line argument; will be
replaced with the absolute filename of the file.
|
False
|
if |
bool |
Indicates if the argument should be passed to the external program.
If true then the argument will be passed;
otherwise, skipped. The default is true .
|
False
|
line |
string |
List of command-line arguments; will be passed to the executable
as is.
|
False
|
path |
|
The value for a PATH-like command-line argument; you can use
: or ; as path separators and NAnt will convert it
to the platform's local conventions, while resolving references to
environment variables.
|
False
|
unless |
bool |
Indicates if the argument should not be passed to the external
program. If false then the argument will be
passed; otherwise, skipped. The default is false .
|
False
|
value |
string |
A single command-line argument; can contain space characters.
|
False
|
Nested elements
Sets a single command-line argument and treats it like a PATH - ensures
the right separator for the local platform is used.
Examples
A single command-line argument containing a space character.
<arg value="-l -a" />
Two separate command-line arguments.
<arg line="-l -a" />
A single command-line argument with the value \dir;\dir2;\dir3
on DOS-based systems and /dir:/dir2:/dir3
on Unix-like systems.
<arg path="/dir;/dir2:\dir3" />
<arg>
Environment variables to pass to the program.
Examples
Ping "nant.sourceforge.net".
<exec program="ping">
<arg value="nant.sourceforge.net" />
</exec>
Execute a java application using IKVM.NET
that requires the
Apache FOP jars, and a set of custom jars.
<path id="fop-classpath">
<pathelement file="${fop.dist.dir}/build/fop.jar" />
<pathelement file="${fop.dist.dir}/lib/xercesImpl-2.2.1.jar" />
<pathelement file="${fop.dist.dir}/lib/avalon-framework-cvs-20020806.jar" />
<pathelement file="${fop.dist.dir}/lib/batik.jar" />
</path>
<exec program="ikvm.exe" useruntimeengine="true">
<arg value="-cp" />
<arg>
<path>
<pathelement dir="conf" />
<path refid="fop-classpath" />
<pathelement file="lib/mylib.jar" />
<pathelement file="lib/otherlib.zip" />
</path>
</arg>
<arg value="org.me.MyProg" />
</exec>
Assuming the base directory of the build file is "c:\ikvm-test" and
the value of the "fop.dist.dir" property is "c:\fop", then the value
of the -cp
argument that is passed toikvm.exe
is
"c:\ikvm-test\conf;c:\fop\build\fop.jar;conf;c:\fop\lib\xercesImpl-2.2.1.jar;c:\fop\lib\avalon-framework-cvs-20020806.jar;c:\fop\lib\batik.jar;c:\ikvm-test\lib\mylib.jar;c:\ikvm-test\lib\otherlib.zip"
on a DOS-based system.
Requirements