exec |

## Description

Execute system command.

## Parameters

executable
  Description: Commandline to be executed

  Domain: Valid commandline

  Default: -

exit_code_variable
  Description: Name of variable holding the process's return code after it's run Note: This attribute can only be used when no fileset is used as nested argument

  Domain: Integer (usually 0 for OK, and any other number for not OK)

  Default: `Void' (no variable is set if attribute is not specified)

accept_errors
  Description: Should executable return codes different from zero be accepted? Note: Use this attribute only if a nested fileset is specified. Usage without one is still supported but obsolete. Use attribute 'exit_code_variable' instead and set it to a dummy value if you are not interested in the return code.

  Domain: true|false

  Default: false

timeout
  Description: Maximum number of milliseconds to wait for the command to terminate.

  Domain: positive number

  Default: no timeout

## RNG Specification

      <define name="exec">
        <element name="exec">
          <ref name="dir_if_unless"/>
          <attribute name="executable"/>
          <optional>
            <attribute name="accept_errors">
              <!-- runtime evaluation
              <choice>
                <value>true</value>
                <value>false</value>
              </choice>
              -->
            </attribute>
          </optional>
          <optional>
            <attribute name="timeout"/>
          </optional>
          <optional>
            <ref name="fileset"/>
          </optional>
        </element>
      </define>

## Examples

      <exec executable="compile system.ace"/>

      <exec executable="ls -l"/>

      <exec executable="dir"/>

      <exec executable="copy ${fs.filename} ${fs.mapped_filename}" dir="${GOBO}/library/kernel">
        <fileset dir="." include="@(*.ge)">
          <map type="glob" from="*.ge" to="${GOBO}/example/geant/tmp/*.e"/>
        </fileset>
      </exec>

## Using exec with a fileset

It is possible to provide a nested fileset element. For each element the fileset contains the commandline specified in attribute commandline is executed and thus works like an iteration of loop in a programming language. To use the current item of the iteration the this task provides the built-in variables ${fs.filename} and ${fs.mapped_filename}.

      <exec executable="copy ${fs.filename} ${fs.mapped_filename}" dir="${GOBO}/library/kernel">
        <fileset dir="." include="@(*.ge)">
          <map type="glob" from="*.ge" to="${GOBO}/example/geant/tmp/*.e"/>
        </fileset>
      </exec>

Due to its general purpose 'exec', unlike copy cannot determine whether the sourcefile is newer than the target file. If we want to behave 'exec' a bit more intelligent we have to prepare the input in advance. The element fileset has an attribute force. By default it is set to 'true' so that all selected files are included. The reason for this default value that tasks like copy using a fileset usually provide their own force attribute. (Note that it is necessary for some tasks, like copy for example, to define their own force attribute since they usually append paths to the filenames delivered by filesets. copy for example is doing this with the attribute to_directory).

By setting force to false the fileset itself determines whether files are 'out of date' or not. This means of course that the fileset must have the complete paths to the files and not only parts of them. In the following example we use the path ${GOBO}/example/geant/tmp in the attribute to of the fileset's map element so that the fileset itself can determine which files to include and which not.

      <exec executable="copy ${fs.filename} ${fs.mapped_filename}" dir="${GOBO}/library/kernel">
    	<fileset dir="." include="@(*.ge)" force="false">
    	  <map type="glob" from="*.ge" to="${GOBO}/example/geant/tmp/*.e"/>
    	</fileset>
      </exec>

Here is another example which uses SmartEiffel's 'short' command on a fileset. The 'exec' command is executed for each entry in the fileset. By default only files which are newer than their corresponding target files are included in the list.

      <exec executable="short -html2 se.ace ${fs.filename} &gt; ${fs.mapped_filename}">
    	<fileset
    	  dir="$GOBO/library/structure/set"
    	  include="@(**/*.e)"
    	  force="false"
    	>
    	  <map type="glob" from="*.e" to="${short_dir}/*.html">
    		<map type="flat"/>
    	  </map>
    	</fileset>
      </exec>

## Using exec with return codes

It is possible to catch the return code of a called process and continue the build process. This way it is possible to check the value of the return code and decide for each specific situation if the build process should be terminated or not:

      <exec executable="..." exit_code_variable="return_code"/>
      <echo message="return_code: ${return_code}"/>
      <echo message="run OK" if="${return_code}=0"/>
      <echo message="run not OK" unless="${return_code}=0"/>
      <exit code="1" unless="${return_code}=0"/>

## Using exec with timeout

Wait for the command to terminate for at most 3 minutes:

      <exec executable="..." timeout="180000"/>