<?xml version="1.0"?>

<!--
	description:

		"Target"

	library: "Gobo Eiffel Ant"
	copyright: "Copyright (c) 2004-2019, Sven Ehrke and others"
	license: "MIT License"
	date: "$Date$"
	revision: "$Revision$"
-->

<chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="target">
<chapterinfo>
	<copyright>
		<year>2002-2019</year>
		<holder>Sven Ehrke</holder>
	</copyright>
	<author>
		<firstname>Sven</firstname><surname>Ehrke</surname>
	</author>
	<email>ericb@gobosoft.com</email>
	<date>15 March 2019</date>
</chapterinfo>

	<title>Target</title>

	<section id="target_description">
		<title>Description</title>
		<para>
			A build file's target is comparable to a method of class in an object oriented
			programming language. Targets can be invoked from the command line or from within
			the build script itself. If a build script 'build.eant' contains a target 't1' for
			example you can invoke this target from the commondline like this:
		</para>
		<programlisting><![CDATA[
  geant t1
]]>
		</programlisting>
	</section>

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

		<variablelist>
			<varlistentry>
				<term>name</term>
				<listitem>
					<para><emphasis>Description: </emphasis>
					The target's name. The name must be unique within the build file. If the build file
					inherits from other build file(s) the inheritance rules must be followed as well.
					The mechanisms to resolve naming conflicts are basically the same as in the Eiffel
					programming language. Since probably all users of geant are Eiffel developers and thus
					are familiar with Eiffel's inheritance mechanisms these rules are not documented.
					Geant will display error messages in case these rules are violated.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>String</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>if</term>
				<listitem>
					<para><emphasis>Description: </emphasis>
					execute target only if the variable used in the attribute value is defined. If the
					value is '$some_var' for example and the variable name 'some_var' is defined the target
					will be executed (but only if evaluation of attribute 'unless' does not prevent this).
					Note that the variable can also reference an environment variable like '$WINDIR' for example.
					In addition to simply checking if a variable is defined or not it is also possible to check if its
					value is equal to a certain string. This is done like this: '${some_var}=some_value'. At the
					moment only equality comparison is supported. For convenience (when automatically generating
					geant build files), it is also accepted to pass "true" or "false" as attribute value. In
					that case the target is executed only if the attribute value is "true".
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>variable definition or variable-value comparison</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>unless</term>
				<listitem>
					<para><emphasis>Description: </emphasis>
					The description of attribute 'if' is valid for this attribute as well with the difference
					that the evaluation of the attribute value is negated. Thus this means the target is
					executed only if the variable referenced in the attribute value is not defined etc.
					(but only if evaluation of attribute 'if' does not prevent this)
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>variable definition or variable-value comparison</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>once</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Should target be executed only once?
						If set to 'true' this target will be executed only on it's first invocation.
						Note: Use this attribute instead of the obsolete attribute 'depend'
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>true|false</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>false</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>depend</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Obsolete. Use attribute 'once' instead.
						Comma separated list of names of targets which should be invoked before this target is executed.
						Execution of targets is done from left to rights. Thus if the value of this attribute is 'a,b,c'
						The first target 'a', then target 'b' and finally target 'c' are called. Note that these targets
						are only executed if they have not been executed before.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Comma separated list of target names</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</section>

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

		<variablelist>
			<varlistentry>
				<term>obsolete</term>
				<listitem>
					<para><emphasis>Description: </emphasis>If provided marks this target as obsolete.
					The nested text is displayed if this target gets executed. The target list (shown by
					invoking 'geant -t' will include this text as well next
					to the target's description.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Text</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>description</term>
				<listitem>
					<para><emphasis>Description: </emphasis>A description of what this target does.
					The target list (shown by invoking 'geant -t' will include this text next
					to the target's name.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Text</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>argument</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Element representing a formal argument
					of this target. The name of the argument is specified by it's attribute 'name'.
					There can be any number of this element to specify an arbitrary number of arguments.
					It is not allowed to have two or more argument elements with the same name. The
					sequence of the argument definition is important since it defines the actual to
					formal argument value assignments when it is called in the so called terse way (see
					documentation of tasks 'geant' and 'precursor' for more information). If the target is
					redefined the number of arguments must match the precursor's.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>-</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</section>

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

		<programlisting><![CDATA[
  <define name="target">
    <element name="target">
    <optional>
      <element name="obsolete">
        <text/>
      </element>
    </optional>
    <zeroOrMore>
      <element name="argument">
        <attribute name="name"/>
      </element>
    </zeroOrMore>
    <ref name="description"/>
    <attribute name="name"/>
    <optional>
      <attribute name="once"/>
    </optional>
    <optional>
      <attribute name="depend"/>
    </optional>
    <ref name="dir_if_unless"/>
    <ref name="tasks"/>
    </element>
  </define>

  <define name="tasks">
    <zeroOrMore>
      <choice>
        <ref name="available"/>
        <ref name="copy"/>
        <ref name="echo"/>
        <ref name="delete"/>
        <ref name="exec"/>
        <ref name="exit"/>
        <ref name="geant"/>
        <ref name="gelex"/>
        <ref name="geyacc"/>
        <ref name="gepp"/>
        <ref name="getest"/>
        <ref name="gexmlsplit"/>
        <ref name="input"/>
        <ref name="ise"/>
        <ref name="mkdir"/>
        <ref name="move"/>
        <ref name="outofdate"/>
        <ref name="precursor"/>
        <ref name="replace"/>
        <ref name="set"/>
        <ref name="setenv"/>
        <ref name="unset"/>
        <ref name="xslt"/>
      </choice>
    </zeroOrMore>
  </define>
]]>
		</programlisting>
	</section>

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

		<programlisting><![CDATA[
  <target name="t1">
    <echo message="This is target 't1'"/>
  </target>
]]>
		</programlisting>
	</section>
</chapter>
