H.2 Targets and Extension-Points

H.2 Targets and Extension-Points
Prev	Appendix H. Project Components	Next

H.2.1 Example

<target if="lang" unless="lang.en" depends="foo1,foo2"
       name="main" description="This is an example target" >

  <!-- everything else goes here -->

</target>

The target defined in the example above is only executed, if the property ${lang} is set and the property ${lang.en} is not set. Additionally, it depends on the targets foo1 and foo2. That means, the targets foo1 and foo2 are executed before the target main is executed. The name of the target is main and it also has a description.

H.2.2 Attributes

Table H.2: Parameters

Name	Type	Description	Default	Required
`depends`	`String`	One or more names of targets that have to be executed before this target can be executed.	n/a	No
`description`	`String`	A free text description of the target.	n/a	No
`if`	`String`	The name of the property that is to be set if the target is to be executed.	n/a	No
`name`	`String`	The name of the target	n/a	Yes
`unless`	`String`	The name of the property that is to be set if the target is not to be executed.	n/a	No
`hidden`	`Boolean`	Whether or not to include this target in the list of targets generated by `phing -l`	False	No
`logskipped`	`Boolean`	Whether to log message as INFO instead of VERBOSE if target is skipped	False	No

Caution

The if and unless attributes only enable or disable the target to which they are attached. They do not control whether or not targets that a conditional target depends upon get executed. In fact, they do not even get evaluated until the target is about to be executed, and all its predecessors have already run.

H.2.3 Extension-Points

Extension-Points are similar to targets in that they have a name and a depends list and can be executed from the command line. Just like targets they represent a state during the build process.

Unlike targets they don't contain any tasks, their main purpose is to collect targets that contribute to the desired state in their depends list.

Targets can add themselves to an extension-point's depends list via their extensionOf attribute. The targets that add themselves will be added after the targets of the explicit depends attribute of the extension-point, if multiple targets add themselves, their relative order is not defined.

The main purpose of an extension-point is to act as an extension point for build files designed to be imported. In the imported file, an extension-point defines a state that must be reached and targets from other build files can join the depends list of said extension-point in order to contribute to that state.

For example your imported build file may need to compile code, it might look like:

<target name="create-directory-layout">
    ...
</target>

<extension-point name="ready-to-compile"
                    depends="create-directory-layout"/>

<target name="compile" depends="ready-to-compile">
    ...
</target>

Call-Graph:  create-directory-layout -> 'empty slot' -> compile

And you need to generate some source before compilation, then in your main build file you may use something like

<target name="generate-sources" 
           extensionOf="ready-to-compile">
...
</target>

Call-Graph: create-directory-layout -> generate-sources -> compile

This will ensure that the "generate-sources" target is executed before the "compile" target.

Don't rely on the order of the depends list, if "generate-sources" depends on "create-directory-layout" then it must explicitly depend on it via its own depends attribute.