/[eiffelstudio]/vendor/gobosoft.com/gobo/current/doc/geant/exec_task.xml
ViewVC logotype

Contents of /vendor/gobosoft.com/gobo/current/doc/geant/exec_task.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 90767 - (show annotations)
Tue Jan 22 00:56:30 2013 UTC (6 years, 8 months ago) by manus
File MIME type: text/xml
File size: 7487 byte(s)
Updated svn:eol-style to be native and svn:mime-style to be text/xml

1 <?xml version="1.0"?>
2
3 <!--
4 description:
5
6 "Exec Tasks"
7
8 library: "Gobo Eiffel Ant"
9 copyright: "Copyright (c) 2002, Sven Ehrke and others"
10 license: "MIT License"
11 date: "$Date$"
12 revision: "$Revision$"
13 -->
14
15 <chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="exec_task">
16 <chapterinfo>
17 <copyright>
18 <year>2002-2005</year>
19 <holder>Sven Ehrke</holder>
20 </copyright>
21 <author>
22 <firstname>Sven</firstname><surname>Ehrke</surname>
23 </author>
24 <email>ericb@gobosoft.com</email>
25 <date>7 July 2005</date>
26 </chapterinfo>
27
28 <title>exec</title>
29
30 <section id="exec_description">
31 <title>Description</title>
32 <para>
33 Execute system command.
34 </para>
35 </section>
36
37 <section id="exec_parameters">
38 <title>Parameters</title>
39
40 <variablelist>
41 <varlistentry>
42 <term>executable</term>
43 <listitem>
44 <para><emphasis>Description: </emphasis>Commandline to be executed</para>
45 </listitem>
46 <listitem>
47 <para><emphasis>Domain: </emphasis>Valid commandline</para>
48 </listitem>
49 <listitem>
50 <para><emphasis>Default: </emphasis>-</para>
51 </listitem>
52 </varlistentry>
53 <varlistentry>
54 <term>exit_code_variable</term>
55 <listitem>
56 <para><emphasis>Description: </emphasis>Name of variable holding the process's return code after it's run
57 Note: This attribute can only be used when no fileset is used as nested argument
58 </para>
59 </listitem>
60 <listitem>
61 <para><emphasis>Domain: </emphasis>Integer (usually 0 for OK, and any other number for not OK)</para>
62 </listitem>
63 <listitem>
64 <para><emphasis>Default: </emphasis>`Void' (no variable is set if attribute is not specified)</para>
65 </listitem>
66 </varlistentry>
67 <varlistentry>
68 <term>accept_errors</term>
69 <listitem>
70 <para><emphasis>Description: </emphasis>Should executable return codes different from zero be accepted?
71 Note: Use this attribute only if a nested fileset is specified. Usage without one is still supported
72 but obsolete. Use attribute 'exit_code_variable' instead and set it to a dummy value if you are not
73 interested in the return code.
74 </para>
75 </listitem>
76 <listitem>
77 <para><emphasis>Domain: </emphasis>true|false</para>
78 </listitem>
79 <listitem>
80 <para><emphasis>Default: </emphasis>false</para>
81 </listitem>
82 </varlistentry>
83 </variablelist>
84 </section>
85
86 <section id="exec_specification">
87 <title>RNG Specification</title>
88
89 <programlisting><![CDATA[
90 <define name="exec">
91 <element name="exec">
92 <ref name="dir_if_unless"/>
93 <attribute name="executable"/>
94 <optional>
95 <attribute name="accept_errors">
96 <!-- runtime evaluation
97 <choice>
98 <value>true</value>
99 <value>false</value>
100 </choice>
101 -->
102 </attribute>
103 </optional>
104 <optional>
105 <ref name="fileset"/>
106 </optional>
107 </element>
108 </define>
109 ]]>
110 </programlisting>
111 </section>
112
113 <section id="exec_examples">
114 <title>Examples</title>
115
116 <programlisting><![CDATA[
117 <exec executable="compile system.ace"/>
118
119 <exec executable="ls -l"/>
120
121 <exec executable="dir"/>
122
123 <exec executable="copy ${fs.filename} ${fs.mapped_filename}" dir="${GOBO}/library/kernel">
124 <fileset dir="." include="@(*.ge)">
125 <map type="glob" from="*.ge" to="${GOBO}/example/geant/tmp/*.e"/>
126 </fileset>
127 </exec>
128 ]]>
129 </programlisting>
130 </section>
131
132 <section id="exec_with_fileset">
133 <title>Using exec with a fileset</title>
134 <para>
135 It is possible to provide a nested <link linkend="fileset_element">fileset</link>
136 element. For each element the fileset contains the commandline specified in
137 attribute <emphasis>commandline</emphasis> is executed and thus works like an iteration of loop
138 in a programming language. To use the current item of the iteration the this task provides the
139 built-in variables <emphasis>${fs.filename}</emphasis> and
140 <emphasis>${fs.mapped_filename}</emphasis>.
141 </para>
142 <programlisting><![CDATA[
143 <exec executable="copy ${fs.filename} ${fs.mapped_filename}" dir="${GOBO}/library/kernel">
144 <fileset dir="." include="@(*.ge)">
145 <map type="glob" from="*.ge" to="${GOBO}/example/geant/tmp/*.e"/>
146 </fileset>
147 </exec>
148 ]]>
149 </programlisting>
150
151 <para>
152 Due to its general purpose 'exec', unlike <link linkend="copy_task">copy</link>
153 cannot determine whether the sourcefile is newer than the target file.
154 If we want to behave 'exec' a bit more intelligent we have to prepare the input in advance.
155 The element <link linkend="fileset_element">fileset</link> has an attribute <emphasis>force</emphasis>.
156 By default it is set to 'true' so that all selected files are included. The reason for this default value
157 that tasks like <link linkend="copy_task">copy</link> using a
158 <link linkend="fileset_element">fileset</link> usually provide their own <emphasis>force</emphasis>
159 attribute. (Note that it is necessary for some tasks, like <link linkend="copy_task">copy</link>
160 for example, to define their own <emphasis>force</emphasis> attribute since they usually append paths
161 to the filenames delivered by filesets. <link linkend="copy_task">copy</link> for example is doing this
162 with the attribute <emphasis>to_directory</emphasis>).
163 </para>
164
165 <para>
166 By setting <emphasis>force</emphasis> to <emphasis>false</emphasis> the fileset itself determines
167 whether files are 'out of date' or not. This means of course that the fileset must have the complete
168 paths to the files and not only parts of them. In the following example we use the path
169 <emphasis>${GOBO}/example/geant/tmp</emphasis> in the attribute <emphasis>to</emphasis>
170 of the <link linkend="fileset_element">fileset</link>'s <link linkend="fileset_element">map</link>
171 element so that the fileset itself can determine which files to include and which not.
172 </para>
173
174 <programlisting><![CDATA[
175 <exec executable="copy ${fs.filename} ${fs.mapped_filename}" dir="${GOBO}/library/kernel">
176 <fileset dir="." include="@(*.ge)" force="false">
177 <map type="glob" from="*.ge" to="${GOBO}/example/geant/tmp/*.e"/>
178 </fileset>
179 </exec>
180 ]]>
181 </programlisting>
182
183 <para>
184 Here is another example which uses SmartEiffel's 'short' command on a fileset.
185 The 'exec' command is executed for each entry in the fileset. By default only files which
186 are newer than their corresponding target files are included in the list.
187 </para>
188
189 <programlisting><![CDATA[
190 <exec executable="short -html2 se.ace ${fs.filename} &gt; ${fs.mapped_filename}">
191 <fileset
192 dir="$GOBO/library/structure/set"
193 include="@(**/*.e)"
194 force="false"
195 >
196 <map type="glob" from="*.e" to="${short_dir}/*.html">
197 <map type="flat"/>
198 </map>
199 </fileset>
200 </exec>
201 ]]>
202 </programlisting>
203
204 </section>
205
206 <section id="exec_with_fileset">
207 <title>Using exec with return codes</title>
208 <para>
209 It is possible to catch the return code of a called process and continue
210 the build process. This way it is possible to check the value of the return code
211 and decide for each specific situation if the build process should be terminated or
212 not:
213 </para>
214 <programlisting><![CDATA[
215 <exec executable="..." exit_code_variable="return_code"/>
216 <echo message="return_code: ${return_code}"/>
217 <echo message="run OK" if="${return_code}=0"/>
218 <echo message="run not OK" unless="${return_code}=0"/>
219 <exit code="1" unless="${return_code}=0"/>
220
221 ]]>
222 </programlisting>
223
224 <para>
225 </para>
226
227 </section>
228
229 </chapter>

Properties

Name Value
svn:mime-type text/xml

  ViewVC Help
Powered by ViewVC 1.1.23