1 | | = Build Recipe Commands Reference = |
2 | | [[PageOutline(2-3)]] |
3 | | |
4 | | As described on the [wiki:BuildRecipes page about build recipes], a recipe is stored as an XML document. This page describes what commands are available in recipes. |
5 | | |
6 | | ''Note: the recipe format has changed since [milestone:0.4]. You can find documentation about the previous format by looking at version 3 of this page (see the “page history” link above).'' |
7 | | |
8 | | ---- |
9 | | |
10 | | == Generic Commands == |
11 | | |
12 | | These are commands that are used without a namespace prefix. |
13 | | |
14 | | === `<report>` === |
15 | | |
16 | | Parse an XML file and send it to the master as a report with a given category. Use this command in conjunction with the `<sh:pipe>` or `<x:transform>` commands to send custom reports to the build master. |
17 | | |
18 | | ==== Parameters ==== |
19 | | |
20 | | || Name || Description || |
21 | | || `category` || Category of the report (for example “test” or “coverage”). || |
22 | | || `file` || Path to the XML file containing the report data, relative to the project directory. || |
23 | | |
24 | | Both parameters must be specified. |
25 | | |
26 | | ---- |
27 | | |
28 | | == Shell Tools == |
29 | | |
30 | | A bundle of generic tools that are not specific to any programming language or tool-chain. |
31 | | |
32 | | ''Namespace'':: `http://bitten.cmlenz.net/tools/sh` |
33 | | ''Common prefix'':: `sh` |
34 | | |
35 | | === `<sh:exec>` === |
36 | | |
37 | | Executes a program or script. |
38 | | |
39 | | ==== Parameters ==== |
40 | | |
41 | | || Name || Description || |
42 | | || `executable` || The name of the executable program. || |
43 | | || `file` || Path to the script to execute, relative to the project directory || |
44 | | || `output` || Path to the output file || |
45 | | || `args` || Any arguments to pass to the executable or script || |
46 | | |
47 | | Either `execute` or `file` must be specified. |
48 | | |
49 | | ==== Examples ==== |
50 | | |
51 | | '''TODO''' |
52 | | |
53 | | === `<sh:pipe>` === |
54 | | |
55 | | Pipes the content of a file through a program or script. |
56 | | |
57 | | ==== Parameters ==== |
58 | | |
59 | | || Name || Default || |
60 | | || `executable` || The name of the executable program. || |
61 | | || `file` || Path to the script to execute, relative to the project directory || |
62 | | || `input` || Path to the input file || |
63 | | || `output` || Path to the output file || |
64 | | || `args` || Any arguments to pass to the executable or script || |
65 | | |
66 | | Either `executable` or `file` must be specified. |
67 | | |
68 | | ==== Examples ==== |
69 | | |
70 | | '''TODO''' |
71 | | |
72 | | |
73 | | ---- |
74 | | |
75 | | == C/Unix Tools == |
76 | | |
77 | | These commands provide support for tools commonly used for development of C/C++ applications on Unix platforms, such as '''make'''. |
78 | | |
79 | | ''Namespace'':: `http://bitten.cmlenz.net/tools/c` |
80 | | ''Common prefix'':: `c` |
81 | | |
82 | | === `<c:configure>` === |
83 | | |
84 | | Executes a configure script as generated by Autoconf. |
85 | | |
86 | | ==== Parameters ==== |
87 | | |
88 | | || Name || Description || |
89 | | || `file` || Name of the configure script (defaults to “configure”) || |
90 | | || `enable` || List of features to enable, separated by spaces. || |
91 | | || `disable` || List of features to disable, separated by spaces. || |
92 | | || `with` || List of packages to include, separated by spaces. || |
93 | | || `without` || List of packages to exclude, separated by spaces. || |
94 | | || `cflags` || Value of the `CFLAGS` variable to pass to the script. || |
95 | | || `cxxflags` || Value of the `CXXFLAGS` variable to pass to the script. || |
96 | | |
97 | | ==== Examples ==== |
98 | | |
99 | | {{{ |
100 | | <c:configure enable="threadsafe" cflags="O"/> |
101 | | }}} |
102 | | |
103 | | Runs the `configure` script in the base directory, enable the `threadsafe` feature, and passing `-O` as `CFLAGS`. This is equivalent to: |
104 | | {{{ |
105 | | ./configure --enable-threadsafe CFLAGS="-O" |
106 | | }}} |
107 | | |
108 | | === `<c:make>` === |
109 | | |
110 | | Executes a Makefile. |
111 | | |
112 | | ==== Parameters ==== |
113 | | |
114 | | || Name || Description || |
115 | | || `target` || Name of the target to execute (defaults to “all”) || |
116 | | || `file` || Path to the Makefile that should be used. || |
117 | | || `keep-going` || Whether `make` should try to continue even after encountering errors. || |
118 | | |
119 | | ==== Examples ==== |
120 | | |
121 | | {{{ |
122 | | <c:make target="compile" file="build/Makefile" /> |
123 | | }}} |
124 | | |
125 | | Runs the target “compile” of the `Makefile` located in the sub-directory `build`. |
126 | | |
127 | | |
128 | | === `<c:cppunit>` === |
129 | | |
130 | | Report the test output generated by the [http://cppunit.sourceforge.net cppunit] unit testing framework. The output from cppunit must be in XML format and in already, specified by the `file` argument of this recipe. |
131 | | |
132 | | ==== Parameters ==== |
133 | | |
134 | | || Name || Description || |
135 | | || `file` || Path to the cppunit XML output file. || |
136 | | |
137 | | ==== Examples ==== |
138 | | |
139 | | {{{ |
140 | | <sh:exec executable="run_unit_tests" output="test_results.xml" /> |
141 | | <c:cppunit file="test_results.xml" /> |
142 | | }}} |
143 | | |
144 | | Runs the program `run_unit_tests` to gather the data output by cppunit in the `test_results.xml` file and then reports it. |
145 | | |
146 | | ---- |
147 | | |
148 | | == Java Tools == |
149 | | |
150 | | A bundle of recipe commands that support tools commonly used by Java projects. |
151 | | |
152 | | ''Namespace'':: `http://bitten.cmlenz.net/tools/java` |
153 | | ''Common prefix'':: `java` |
154 | | |
155 | | === `<java:ant>` === |
156 | | |
157 | | Runs an Ant build. |
158 | | |
159 | | ==== Parameters ==== |
160 | | |
161 | | || Name || Description || |
162 | | || `file` || Path of the build file, relative to the project source directory (default is `build.xml`). || |
163 | | || `target` || Name of the build target(s) to execute. || |
164 | | || `args` || Additional arguments to pass to Ant, separated by whitespace. || |
165 | | || `keep_going` || Tell Ant to continue even when errors are in encountered in the build. || |
166 | | |
167 | | ==== Examples ==== |
168 | | |
169 | | {{{ |
170 | | <java:ant target="compile" /> |
171 | | }}} |
172 | | |
173 | | Executes the target `compile` of the `build.xml` buildfile at the top of the project source directory. |
174 | | |
175 | | === `<java:junit>` === |
176 | | |
177 | | Extracts information about unit test results from a file in [http://junit.org/index.htm JUnit] XML format. |
178 | | |
179 | | ==== Parameters ==== |
180 | | |
181 | | || Name || Description || |
182 | | || `file` || Path to the JUnit XML test results file. This can include wildcards, in which case all the file matching the pattern will be included. || |
183 | | || `srcdir` || Path of the directory unit test sources. Used to link the test cases to files. || |
184 | | |
185 | | The `file` attribute is required. |
186 | | |
187 | | ==== Examples ==== |
188 | | |
189 | | {{{ |
190 | | <java:junit file="build/tests/results/TEST-*.xml" srcdir="src/tests" /> |
191 | | }}} |
192 | | |
193 | | Collects the test results from all files in the `build/tests/results` directory that match the pattern `TEST-*.xml`. Also, maps the class names in the results files to Java source files in the directory `src/tests`. |
194 | | |
195 | | ---- |
196 | | |
197 | | == Python Tools == |
198 | | |
199 | | A bundle of recipe commands that support tools commonly used by [http://www.python.org/ Python] projects. |
200 | | |
201 | | ''Namespace'':: `http://bitten.cmlenz.net/tools/python` |
202 | | ''Common prefix'':: `python` |
203 | | |
204 | | === `<python:exec>` === |
205 | | |
206 | | Executes a Python script. |
207 | | |
208 | | ==== Parameters ==== |
209 | | |
210 | | || Name || Description || |
211 | | || `file` || Path of the script to execute, relative to the project source directory. || |
212 | | || `module` || Name of the Python module to execute. || |
213 | | || `function` || Name of the function in the Python module to run. Only works when also specifying the `module` attribute. || |
214 | | || `args` || Any arguments that should be passed to the script. || |
215 | | || `output` || Path to a file where any output by the script should be recorded. || |
216 | | |
217 | | Either `file` or `module` must be specified. |
218 | | |
219 | | ==== Examples ==== |
220 | | |
221 | | {{{ |
222 | | <python:exec module="pylint.lint" output="pylint-report.txt" args="myproj" /> |
223 | | }}} |
224 | | |
225 | | Executes [http://www.logilab.org/projects/pylint Pylint] on the module/package “myproj” and stores the output into a file named `pylint-report.txt`. |
226 | | |
227 | | === `<python:distutils>` === |
228 | | |
229 | | Executes a [http://docs.python.org/lib/module-distutils.html distutils] script. |
230 | | |
231 | | ==== Parameters ==== |
232 | | |
233 | | || Name || Description || |
234 | | || `command` || The name of the `distutils` command that should be run || |
235 | | |
236 | | ==== Examples ==== |
237 | | |
238 | | {{{ |
239 | | <python:distutils command="sdist" /> |
240 | | }}} |
241 | | |
242 | | Instructs `distutils` to produce a source distribution. |
243 | | |
244 | | === `<python:unittest>` === |
245 | | |
246 | | Extracts information from [http://docs.python.org/lib/module-unittest.html unittest] results recorded in an XML file. |
247 | | |
248 | | ''Note: This report must be used in conjunction with the `distutils` command [source:trunk/bitten/util/testrunner.py unittest] that comes with Bitten.'' |
249 | | |
250 | | ==== Parameters ==== |
251 | | |
252 | | || Name || Description || |
253 | | || `file` || Path to the XML results file, relative to the project source directory. || |
254 | | |
255 | | ==== Examples ==== |
256 | | |
257 | | {{{ |
258 | | <python:unittest file="build/test-results.xml"/> |
259 | | }}} |
260 | | |
261 | | Extracts the test results from the XML file located at `build/test-results.xml`. |
262 | | |
263 | | === `<python:trace>` === |
264 | | |
265 | | Extracts coverage information recorded by the built-in Python module `trace.py`. |
266 | | |
267 | | ==== Parameters ==== |
268 | | |
269 | | || Name || Description || |
270 | | || `summary` || Path to the summary file written by `trace.py`, relative to the project source directory. || |
271 | | || `coverdir` || Path to the directory containing the coverage files written by `trace.py`, relative to the project source directory. || |
272 | | || `include` || List of glob patterns (separated by space) that specify which Python file should be included in the coverage report. || |
273 | | || `exclude` || List of glob patterns (separated by space) that specify which Python file should be excluded from the coverage report. || |
274 | | |
275 | | ==== Examples ==== |
276 | | |
277 | | {{{ |
278 | | <python:trace summary="build/trace.out" coverdir="build/coverage" /> |
279 | | }}} |
280 | | |
281 | | === `<python:pylint>` === |
282 | | |
283 | | Extracts information from [http://www.logilab.org/projects/pylint Pylint] reports. |
284 | | |
285 | | ==== Parameters ==== |
286 | | |
287 | | || Name || Description || |
288 | | || `file` || Path to the file containing the Pylint output, relative to the project source directory. || |
289 | | |
290 | | ==== Examples ==== |
291 | | |
292 | | {{{ |
293 | | <python:pylint file="build/pylint.out" /> |
294 | | }}} |
295 | | |
296 | | ---- |
297 | | |
298 | | == XML Tools == |
299 | | |
300 | | A collection of recipe commands for XML processing. |
301 | | |
302 | | ''Namespace'':: `http://bitten.cmlenz.net/tools/xml` |
303 | | ''Common prefix'':: `x` |
304 | | |
305 | | === `<x:transform>` === |
306 | | |
307 | | Apply an XSLT stylesheet . |
308 | | |
309 | | ''Note that this command requires either [http://xmlsoft.org/XSLT/ libxslt] (with [http://xmlsoft.org/XSLT/python.html Python bindings]) or, on Windows platforms, MSXML (version 3 or later) to be installed on the slave machine.'' |
310 | | |
311 | | ==== Parameters ==== |
312 | | |
313 | | || Name || Description || |
314 | | || `src` || Path of the source XML file. || |
315 | | || `dest` || Path of the destition XML file. || |
316 | | || `stylesheet` || Path to the XSLT stylesheet file. || |
317 | | |
318 | | All these are interpreted relative to the project source directory. |
319 | | |
320 | | ==== Examples ==== |
321 | | |
322 | | {{{ |
323 | | <x:transform src="src.xml" dest="dest.xml" stylesheet="util/convert.xsl" /> |
324 | | }}} |
325 | | |
326 | | This applies the stylesheet in `util/convert.xsl` to the source file `src.xml`, and writes the resulting XML document to `dest.xml`. |
| 1 | See [wiki:Documentation/commands.html Build Recipe Commands] |