7.3. Performing Batch Execution What if you want to execute a command on multiple files? If you want to pass a set of files to an external command, use the apply task, a version of exec that takes filesets. The files in the fileset are passed as arguments to the command or external program. This task is a powerful one, letting you batch your executions and work with external programs as if they supported filesets. In Example 7-5, the build file is running the C compiler gcc on a fileset. In this case, the apply task executes the command line gcc -c -o target source for each .c file in ${src}, where source with the name of each matching .c file in turn, and target is replaced with the name of the corresponding .o output file you want created. Example 7-5. Using the apply task (ch07/apply/build.xml) <?xml version="1.0" ?> <project default="main"> <property name="src" location="source" /> <target name="main"> <apply executable="gcc"> <arg value="-c"/> <arg value="-o"/> <targetfile/> <srcfile/> <fileset dir="${src}" includes="*.c" /> <mapper from="*.c" to="*.o" type="glob" /> </apply> </target> </project> You can see this task's attributes Table 7-4. Table 7-4. The apply task's attributes Attribute | Description | Required | Default |
---|
addsourcefile | Specifies if you want source filenames to be added to the command automatically. Since Ant 1.6. | No | TRue | append | Specifies whether you want to append to output and error files. | No | false | dest | Specifies the directory in which files will be stored by the task. | Yes, if you specify a nested mapper. | | dir | Specifies the directory where the command should be executed. | No | | error | Specifies the file where standard error output should be stored. | No | | errorproperty | Specifies the name of a property where you want to store errors. | No | | executable | Specifies the command to execute (without any command-line arguments). | Yes | | failifexecutionfails | Specifies the build should be stopped if the program doesn't start. | No | true | failonerror | Specifies the build should be stopped if the task encounters errors. | No | | forwardslash | Specifies you want filenames to be passed with forward slashes as directory separators. | No | false | input | Specifies the file where the task should take input to run the class with. | No | | inputstring | Specifies a string holding the input stream for the class to run. | No | | logError | Specifies you want to send error output to Ant's log. | No | | maxparallel | Specifies the maximum number of source files to use at once. Set to a value less than or equal to 0 for unlimited parallelism. Available since Ant 1.6. | No | unlimited | newenvironment | Indicates you do not want to pass to the old environment when new environment variables are specified. | No | false | os | Specifies the operating systems in which the executable can be run. | No | | output | Specifies the name of a file in which to store the output. | No | | outputproperty | Specifies the name of a property in which you want the output of the task to be placed. | No | | parallel | Specifies you want to run the command one time only on multiple files. | No | false | relative | Specifies if filenames should be absolute or relative when passed to the command to execute. | No | false | resolveExecutable | Specifies the name of the executable should be resolved using the project's base directory, then using the execution directory if that doesn't work. Since Ant 1.6. | No | false | resultproperty | Specifies the name of the property that you want to hold the return code. Use this one only if failonerror is false and if fork is true. | No | | skipemptyfilesets | Specifies you don't want to run the command if no source files found or are newer than their corresponding target files. | No | false | spawn | Specifies you want to spawn a new process in which to run the command. To use this attribute, set fork to true. | No | false | timeout | Specifies you want the task to quit if it doesn't finish in the given time. Set the time in milliseconds. | No | | type | Specifies whether you're working with files or directories. Set to dir, file, or both. | No | "file" | verbose | Specifies whether you want the task to display its progress. Since Ant 1.6. | No | false | Vmlauncher | Specifies you want to run the executable using the JVM's execution facilities. | No | true |
You can use any number of nested fileset elements to specify the files you want to use with this task. Since Ant 1.6, you can use any number of nested filelist and/or dirset elements as well. At least one fileset or filelist is required. You can use one mapper element to specify the target files relative to the dest attribute for dependency checking, as I'll do below. Command-line arguments can be passed with arg elements, as with the exec task, and you can use nested env elements. How does Ant pass the names of files to the external program? By default, the file-names of the source files are added to the end of the command line. If you want to insert the names of files in a different place, use a nested srcfile element between nested arg elements. Nested targetfile elements are similar to srcfile elements, except they mark the position of the target filename on the command line. You can only use a targetfile element if you define a nested mapper and the dest attribute. |