<?xml version="1.0"?>

<!--
	description:

		"Geant Tasks"

	library: "Gobo Eiffel Ant"
	copyright: "Copyright (c) 2002-2025, Sven Ehrke and others"
	license: "MIT License"
-->

<chapter xmlns="https://www.gobosoft.com/eiffel/gobo/documentation" id="geant_task">
<chapterinfo>
	<copyright>
		<year>2002-2005</year>
		<holder>Sven Ehrke</holder>
	</copyright>
	<author>
		<firstname>Sven</firstname><surname>Ehrke</surname>
	</author>
	<email>ericb@gobosoft.com</email>
	<date>7 July 2005</date>
</chapterinfo>

	<title>geant</title>

	<section id="geant_description">
		<title>Description</title>
		<para>
			Sometimes when projects get large it is useful to make build scripts more
			modular. It would be useful for example to call subtargets in a procedural manner
			and it would be useful to use more than one build script since the build script usually
			grows with the size of the project. With the geant task you can accomplish this.
		</para>
	</section>

	<section id="geant_parameters">
		<title>Parameters</title>

		<variablelist>
			<varlistentry>
				<term>arguments</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Comma separated list of values to be passed
					as arguments to the target to be called. The number of values must match the number of
					formal arguments of that target. The sequence is important: the first value
					will be used for the first actual parameter, the second as the second and so on. This is
					the so called terse way of argument passing.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Comma separated list of values</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>fork</term>
				<listitem>
					<para>
						<emphasis>Description: </emphasis>Should a new operation system process be spawned for call?
						<para>
						When not specified the following default behavior applies:
						If parameter 'file' has been specified the default value for 'fork' is 'true'. 
						If no parameter 'file' has been specified the default value for 'fork' is 'false',
						</para>
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>true|false</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>see description</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>file</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Name of build file to invoke</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Name of existing file</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>target</term>
				<listitem>
					<para>
						<emphasis>Description: </emphasis>Name of target to invoke in current build file
						respectively in buildfile specified through attribute <emphasis>file</emphasis>
						if provided.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>existing target</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

            <varlistentry>
                <term>exit_code_variable</term>
                <listitem>
                    <para><emphasis>Description: </emphasis>Name of variable holding the execution's return code
<!-- TODO: check if filesets are supported at all:
                        Note: This attribute can only be used when no fileset is used as nested argument
-->
                    </para>
                </listitem>
                <listitem>
                    <para><emphasis>Domain: </emphasis>Integer (usually 0 for OK, and any other number for not OK)</para>
                </listitem>
                <listitem>
                    <para><emphasis>Default: </emphasis>`Void' (no variable is set if attribute is not specified)</para>
                </listitem>
            </varlistentry>

			<varlistentry>
				<term>reuse_variables</term>
				<listitem>
					<para>
						<emphasis>Description: </emphasis>Should variables defined in current build file
						be available in invoked build file?
						Note: This attribute is only evaluated if attribute <emphasis>file</emphasis>
						if provided.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>true|false</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>false</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</section>

	<section id="geant_nested_parameters">
		<title>Parameters specified as nested elements</title>

		<variablelist>
			<varlistentry>
				<term>argument</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Element representing a actual argument
					for the target to be called. The name of the matching formal argument is specified
					by the attribute 'name'. The value to be used is specified through the attribute 'value'.
					The names of the arguments and the number of arguments must match the formal ones of
					the target to be called.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>-</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</section>


	<section id="geant_specification">
		<title>RNG Specification</title>

		<programlisting><![CDATA[
<define name="geant">
  <element name="geant">
    <ref name="dir_if_unless"/>
    <optional>
      <choice>
        <attribute name="arguments"/>
        <zeroOrMore>
          <element name="argument">
            <attribute name="name"/>
            <attribute name="value"/>
          </element>
	    </zeroOrMore>
      </choice>
    </optional>
    <optional>
      <attribute name="fork">
        <!-- runtime evaluation
        <choice>
          <value>true</value>
          <value>false</value>
        </choice>
        -->
      </attribute>
    </optional>
    <optional>
      <attribute name="exit_code_variable"/>
    </optional>
    <choice>
      <attribute name="target"/>
      <group>
        <attribute name="file"/>
          <optional>
            <attribute name="reuse_variables">
              <!-- runtime evaluation
              <choice>
                <value>true</value>
                <value>false</value>
              </choice>
              -->
            </attribute>
          </optional>
          <optional>
            <ref name="fileset"/>
          </optional>
        </group>
        <group>
          <attribute name="file"/>
          <attribute name="target"/>
          <optional>
            <attribute name="reuse_variables">
              <!-- runtime evaluation
              <choice>
                <value>true</value>
                <value>false</value>
              </choice>
              -->
            </attribute>
          </optional>
          <optional>
            <ref name="fileset"/>
          </optional>
        </group>
      <ref name="fileset"/>
      </choice>
  </element>
</define>
]]>
		</programlisting>
	</section>

	<section id="geant_examples">
		<title>Examples</title>

		<programlisting><![CDATA[
  <geant file="build2.eant"/>

  <geant file="build2.eant" target="compile"/>

  <geant file="build2.eant" target="compile" reuse_variables="true"/>

  <geant target="compile"/>
]]>
		</programlisting>
	</section>


</chapter>
