Mercurial > bitten > bitten-test
annotate doc/commands.txt @ 461:f487963dd886
When the slave is run in `--dry-run` mode, it now also sends a build cancellation message to the master in case of failed builds. Closes #187.
author | cmlenz |
---|---|
date | Mon, 24 Sep 2007 12:56:41 +0000 |
parents | 74c51f648466 |
children | 6718f9a5c1f1 |
rev | line source |
---|---|
412 | 1 .. -*- mode: rst; encoding: utf-8 -*- |
2 | |
3 ===================== | |
4 Build Recipe Commands | |
5 ===================== | |
6 | |
415 | 7 `Build recipes`_ are represented by XML documents. This page describes what |
412 | 8 commands are generally available in recipes. Please note, though, that |
9 third-party packages can add additional commands, which would then be | |
10 documented by that third party. | |
11 | |
415 | 12 .. _`build recipes`: recipes.html |
13 | |
412 | 14 .. contents:: Contents |
15 :depth: 2 | |
16 .. sectnum:: | |
17 | |
18 | |
19 Generic Commands | |
20 ================ | |
21 | |
22 These are commands that are used without a namespace prefix. | |
23 | |
24 | |
25 ------------ | |
26 ``<report>`` | |
27 ------------ | |
28 | |
29 Parse an XML file and send it to the master as a report with a given category. | |
30 Use this command in conjunction with the ``<sh:pipe>`` or ``<x:transform>`` | |
31 commands to send custom reports to the build master. | |
32 | |
33 Parameters | |
34 ---------- | |
35 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
36 +--------------+-------------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
37 | Name | Description | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
38 +==============+=============================================================+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
39 | ``category`` | Category of the report (for example "test" or "coverage"). | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
40 +--------------+-------------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
41 | ``file`` | Path to the XML file containing the report data, relative | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
42 | | to the project directory. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
43 +--------------+-------------------------------------------------------------+ |
412 | 44 |
45 Both parameters must be specified. | |
46 | |
47 | |
48 Shell Tools | |
49 =========== | |
50 | |
51 A bundle of generic tools that are not specific to any programming language or | |
52 tool-chain. | |
53 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
54 :Namespace: ``http://bitten.cmlenz.net/tools/sh`` |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
55 :Common prefix: ``sh`` |
412 | 56 |
57 | |
58 ------------- | |
59 ``<sh:exec>`` | |
60 ------------- | |
61 | |
62 Executes a program or script. | |
63 | |
64 Parameters | |
65 ---------- | |
66 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
67 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
68 | Name | Description | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
69 +================+===========================================================+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
70 | ``executable`` | The name of the executable program. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
71 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
72 | ``file`` | Path to the script to execute, relative to the project | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
73 | | directory | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
74 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
75 | ``output`` | Path to the output file | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
76 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
77 | ``args`` | Any arguments to pass to the executable or script | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
78 +----------------+-----------------------------------------------------------+ |
412 | 79 |
80 Either ``executable`` or ``file`` must be specified. | |
81 | |
82 Examples | |
83 -------- | |
84 | |
85 TODO | |
86 | |
87 | |
88 ------------- | |
89 ``<sh:pipe>`` | |
90 ------------- | |
91 | |
92 Pipes the content of a file through a program or script. | |
93 | |
94 Parameters | |
95 ---------- | |
96 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
97 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
98 | Name | Description | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
99 +================+===========================================================+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
100 | ``executable`` | The name of the executable program. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
101 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
102 | ``file`` | Path to the script to execute, relative to the project | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
103 | | directory | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
104 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
105 | ``input`` | Path to the input file | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
106 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
107 | ``output`` | Path to the output file | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
108 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
109 | ``args`` | Any arguments to pass to the executable or script | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
110 +----------------+-----------------------------------------------------------+ |
412 | 111 |
112 Either ``executable`` or ``file`` must be specified. | |
113 | |
114 Examples | |
115 -------- | |
116 | |
117 TODO | |
118 | |
119 | |
120 C/Unix Tools | |
121 ============ | |
122 | |
123 These commands provide support for tools commonly used for development of C/C++ | |
124 applications on Unix platforms, such as ``make``. | |
125 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
126 :Namespace: ``http://bitten.cmlenz.net/tools/c`` |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
127 :Common prefix: ``c`` |
412 | 128 |
129 | |
130 ----------------- | |
131 ``<c:configure>`` | |
132 ----------------- | |
133 | |
134 Executes a configure script as generated by Autoconf. | |
135 | |
136 Parameters | |
137 ---------- | |
138 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
139 +--------------+-------------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
140 | Name | Description | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
141 +==============+=============================================================+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
142 | ``file`` | Name of the configure script (defaults to "configure") | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
143 +--------------+-------------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
144 | ``enable`` | List of features to enable, separated by spaces. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
145 +--------------+-------------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
146 | ``disable`` | List of features to disable, separated by spaces. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
147 +--------------+-------------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
148 | ``with`` | List of packages to include, separated by spaces. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
149 +--------------+-------------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
150 | ``without`` | List of packages to exclude, separated by spaces. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
151 +--------------+-------------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
152 | ``cflags`` | Value of the `CFLAGS` variable to pass to the script. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
153 +--------------+-------------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
154 | ``cxxflags`` | Value of the `CXXFLAGS` variable to pass to the script. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
155 +--------------+-------------------------------------------------------------+ |
412 | 156 |
157 Examples | |
158 -------- | |
159 | |
160 .. code-block:: xml | |
161 | |
432 | 162 <c:configure enable="threadsafe" cflags="-O"/> |
412 | 163 |
432 | 164 Runs the ``configure`` script in the base directory, enable the ``threadsafe`` |
165 feature, and passing ``-O`` as ``CFLAGS``. This is equivalent to:: | |
412 | 166 |
167 ./configure --enable-threadsafe CFLAGS="-O" | |
168 | |
169 | |
170 ------------ | |
415 | 171 ``<c:gcov>`` |
172 ------------ | |
173 | |
174 Run gcov_ to extract coverage data where available. | |
175 | |
176 .. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov-Intro.html | |
177 | |
178 Parameters | |
179 ---------- | |
180 | |
181 +--------------+------------------------------------------------------------+ | |
182 | Name | Description | | |
183 +==============+============================================================+ | |
184 | ``include`` | List of glob patterns (separated by space) that specify | | |
185 | | which source files should be included in the coverage | | |
186 | | report | | |
187 +--------------+------------------------------------------------------------+ | |
188 | ``exclude`` | List of glob patterns (separated by space) that specify | | |
189 | | which source files should be excluded from the coverage | | |
190 | | report | | |
191 +--------------+------------------------------------------------------------+ | |
192 | ``prefix`` | Optional prefix name that is added to object files by the | | |
193 | | build system | | |
194 +--------------+------------------------------------------------------------+ | |
195 | |
196 | |
197 ------------ | |
412 | 198 ``<c:make>`` |
199 ------------ | |
200 | |
201 Executes a Makefile. | |
202 | |
203 Parameters | |
204 ---------- | |
205 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
206 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
207 | Name | Description | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
208 +================+===========================================================+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
209 | ``target`` | Name of the target to execute (defaults to "all") | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
210 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
211 | ``file`` | Path to the Makefile that should be used. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
212 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
213 | ``keep-going`` | Whether `make` should try to continue even after | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
214 | | encountering errors. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
215 +----------------+-----------------------------------------------------------+ |
412 | 216 |
217 Examples | |
218 -------- | |
219 | |
220 .. code-block:: xml | |
221 | |
222 <c:make target="compile" file="build/Makefile" /> | |
223 | |
224 Runs the target "compile" of the ``Makefile`` located in the sub-directory | |
225 ``build``. | |
226 | |
227 | |
228 --------------- | |
229 ``<c:cppunit>`` | |
230 --------------- | |
231 | |
232 Report the test output generated by the CppUnit_ unit testing framework. The | |
233 output from CppUnit must be in XML format and in already, specified by the | |
234 ``file`` argument of this recipe. | |
235 | |
236 .. _cppunit: http://cppunit.sourceforge.net | |
237 | |
238 Parameters | |
239 ---------- | |
240 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
241 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
242 | Name | Description | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
243 +================+===========================================================+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
244 | ``file`` | Path to the cppunit XML output file. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
245 +----------------+-----------------------------------------------------------+ |
412 | 246 |
247 Examples | |
248 -------- | |
249 | |
250 .. code-block:: xml | |
251 | |
252 <sh:exec executable="run_unit_tests" output="test_results.xml" /> | |
253 <c:cppunit file="test_results.xml" /> | |
254 | |
255 Runs the program ``run_unit_tests`` to gather the data output by CppUnit in the | |
256 ``test_results.xml`` file and then reports it. | |
257 | |
258 | |
259 Java Tools | |
260 ========== | |
261 | |
262 A bundle of recipe commands that support tools commonly used by Java projects. | |
263 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
264 :Namespace: ``http://bitten.cmlenz.net/tools/java`` |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
265 :Common prefix: ``java`` |
412 | 266 |
267 | |
268 -------------- | |
269 ``<java:ant>`` | |
270 -------------- | |
271 | |
272 Runs an Ant_ build. | |
273 | |
274 .. _ant: http://ant.apache.org/ | |
275 | |
276 Parameters | |
277 ---------- | |
278 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
279 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
280 | Name | Description | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
281 +================+===========================================================+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
282 | ``file`` | Path of the build file, relative to the project source | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
283 | |Â directory (default is ``build.xml``). | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
284 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
285 | ``target`` | Name of the build target(s) to execute. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
286 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
287 | ``args`` | Additional arguments to pass to Ant, separated by | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
288 | | whitespace. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
289 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
290 | ``keep_going`` | Tell Ant to continue even when errors are in encountered | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
291 | | in the build. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
292 +----------------+-----------------------------------------------------------+ |
412 | 293 |
294 Examples | |
295 -------- | |
296 | |
297 .. code-block:: xml | |
298 | |
299 <java:ant target="compile" /> | |
300 | |
432 | 301 Executes the target ``compile`` of the ``build.xml`` buildfile at the top of the |
412 | 302 project source directory. |
303 | |
304 | |
415 | 305 -------------------- |
306 ``<java:cobertura>`` | |
307 -------------------- | |
308 | |
309 Extract code coverage data from a Cobertura_ XML file. | |
310 | |
311 .. _cobertura: http://cobertura.sourceforge.net/ | |
312 | |
313 Parameters | |
314 ---------- | |
315 | |
316 +----------------+-----------------------------------------------------------+ | |
317 | Name | Description | | |
318 +================+===========================================================+ | |
319 | ``file`` | Path to the XML file generated by Cobertura | | |
320 +----------------+-----------------------------------------------------------+ | |
321 | |
322 Examples | |
323 -------- | |
324 | |
325 .. code-block:: xml | |
326 | |
327 <java:cobertura file="build/cobertura.xml" /> | |
328 | |
329 Reads the specifid XML file, extracts the coverage data, and builds a coverage | |
330 report to be sent to the build master. | |
331 | |
332 | |
412 | 333 ---------------- |
334 ``<java:junit>`` | |
335 ---------------- | |
336 | |
337 Extracts information about unit test results from a file in JUnit_ XML format. | |
338 | |
339 .. _junit: http://junit.org/index.htm | |
340 | |
341 Parameters | |
342 ---------- | |
343 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
344 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
345 | Name | Description | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
346 +================+===========================================================+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
347 | ``file`` | Path to the JUnit XML test results file. This can include | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
348 | | wildcards, in which case all the file matching the | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
349 | | pattern will be included. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
350 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
351 | ``srcdir`` | Path of the directory unit test sources. Used to link the | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
352 | | test cases to files. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
353 +----------------+-----------------------------------------------------------+ |
412 | 354 |
355 The ``file`` attribute is required. | |
356 | |
357 Examples | |
358 -------- | |
359 | |
360 .. code-block:: xml | |
361 | |
362 <java:junit file="build/tests/results/TEST-*.xml" srcdir="src/tests" /> | |
363 | |
364 Collects the test results from all files in the `build/tests/results` directory | |
365 that match the pattern `TEST-*.xml`. Also, maps the class names in the results | |
366 files to Java source files in the directory `src/tests`. | |
367 | |
368 | |
416 | 369 PHP Tools |
370 ========= | |
371 | |
372 A bundle of recipe commands for PHP_ projects. | |
373 | |
374 :Namespace: ``http://bitten.cmlenz.net/tools/php`` | |
375 :Common prefix: ``php`` | |
376 | |
377 .. _php: http://php.net/ | |
378 | |
422 | 379 --------------- |
380 ``<php:phing>`` | |
381 --------------- | |
416 | 382 |
383 Runs a Phing_ build. | |
384 | |
385 .. _phing: http://phing.info/ | |
386 | |
387 Parameters | |
388 ---------- | |
389 | |
390 +-------------------+-------------------------------------------------------+ | |
391 | Name | Description | | |
392 +===================+=======================================================+ | |
393 | ``file`` | Path of the build file, relative to the project | | |
394 | | source directory (default is ``build.xml``). | | |
395 +-------------------+-------------------------------------------------------+ | |
396 | ``target`` | Name of the build target(s) to execute. | | |
397 +-------------------+-------------------------------------------------------+ | |
398 | ``args`` | Additional arguments to pass to Phing, separated by | | |
399 | | whitespace. | | |
400 +-------------------+-------------------------------------------------------+ | |
401 | ``executable`` | Phing executable program (default is ``phing``). | | |
402 +-------------------+-------------------------------------------------------+ | |
403 | |
404 | |
405 Examples | |
406 -------- | |
407 | |
408 .. code-block:: xml | |
409 | |
410 <php:phing target="compile" /> | |
411 | |
412 Executes the target ``compile`` of the ``build.xml`` buildfile at the top of the | |
413 project source directory. | |
414 | |
415 | |
416 ----------------- | |
417 ``<php:phpunit>`` | |
418 ----------------- | |
419 | |
420 Extracts information from PHPUnit_ test results recorded in an XML file. | |
421 | |
422 .. _phpunit: http://www.phpunit.de/ | |
423 | |
424 Parameters | |
425 ---------- | |
426 | |
427 +----------------+-----------------------------------------------------------+ | |
428 | Name | Description | | |
429 +================+===========================================================+ | |
430 | ``file`` | Path to the XML results file, relative to the project | | |
431 | | source directory. | | |
432 +----------------+-----------------------------------------------------------+ | |
433 | |
434 Examples | |
435 -------- | |
436 | |
437 .. code-block:: xml | |
438 | |
439 <php:phpunit file="build/test-results.xml"/> | |
440 | |
441 Extracts the test results from the XML file located at | |
442 ``build/test-results.xml``. | |
443 | |
444 | |
445 ------------------ | |
446 ``<php:coverage>`` | |
447 ------------------ | |
448 | |
449 Extracts coverage information Phing_'s code coverage task recorded in an XML | |
450 file. | |
451 | |
452 Parameters | |
453 ---------- | |
454 | |
455 +---------------+-----------------------------------------------------------+ | |
456 | Name | Description | | |
457 +===============+===========================================================+ | |
458 | ``file`` | Path to the XML coverage file, relative to the project | | |
459 | | source directory. | | |
460 +---------------+-----------------------------------------------------------+ | |
461 | |
462 Examples | |
463 -------- | |
464 | |
465 .. code-block:: xml | |
466 | |
467 <php:coverage file="build/coverage.xml" /> | |
468 | |
469 | |
412 | 470 Python Tools |
471 ============ | |
472 | |
473 A bundle of recipe commands that support tools commonly used by Python_ | |
474 projects. | |
475 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
476 :Namespace: ``http://bitten.cmlenz.net/tools/python`` |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
477 :Common prefix: ``python`` |
412 | 478 |
479 .. _python: http://www.python.org/ | |
480 | |
481 | |
482 ----------------- | |
483 ``<python:exec>`` | |
484 ----------------- | |
485 | |
486 Executes a Python script. | |
487 | |
488 Parameters | |
489 ---------- | |
490 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
491 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
492 | Name | Description | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
493 +================+===========================================================+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
494 | ``file`` | Path of the script to execute, relative to the project | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
495 | | source directory. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
496 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
497 | ``module`` | Name of the Python module to execute. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
498 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
499 | ``function`` | Name of the function in the Python module to run. Only | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
500 | | works when also specifying the `module` attribute. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
501 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
502 | ``args`` | Any arguments that should be passed to the script. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
503 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
504 | ``output`` | Path to a file where any output by the script should be | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
505 | | recorded. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
506 +----------------+-----------------------------------------------------------+ |
412 | 507 |
508 Either `file` or `module` must be specified. | |
509 | |
510 Examples | |
511 -------- | |
512 | |
513 .. code-block:: xml | |
514 | |
515 <python:exec module="pylint.lint" output="pylint-report.txt" args="myproj" /> | |
516 | |
517 Executes Pylint_ on the module/package ``myproj`` and stores the output into a | |
518 file named ``pylint-report.txt``. | |
519 | |
520 | |
521 ---------------------- | |
522 ``<python:distutils>`` | |
523 ---------------------- | |
524 | |
525 Executes a distutils_ script. | |
526 | |
527 .. _distutils: http://docs.python.org/lib/module-distutils.html | |
528 | |
529 Parameters | |
530 ---------- | |
531 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
532 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
533 | Name | Description | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
534 +================+===========================================================+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
535 | `command` | The name of the `distutils` command that should be run | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
536 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
537 | `options` | Additional options to pass to the command, separated by | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
538 | | spaces | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
539 +----------------+-----------------------------------------------------------+ |
412 | 540 |
541 Examples | |
542 -------- | |
543 | |
544 .. code-block:: xml | |
545 | |
546 <python:distutils command="sdist" /> | |
547 | |
548 Instructs `distutils` to produce a source distribution. | |
549 | |
415 | 550 .. code-block:: xml |
551 | |
552 <python:distutils command="unittest" options=" | |
553 --xml-output build/test-results.xml | |
554 --coverage-summary build/test-coverage.txt | |
555 --coverage-dir build/coverage"/> | |
556 | |
557 Instructs `distutils` to run the ``unittest`` command (which is provided by | |
558 Bitten), and passes the options needed to determine the output paths for test | |
559 results and code coverage reports. | |
560 | |
412 | 561 |
562 --------------------- | |
563 ``<python:unittest>`` | |
564 --------------------- | |
565 | |
566 Extracts information from unittest_ results recorded in an XML file. | |
567 | |
568 .. _unittest: http://docs.python.org/lib/module-unittest.html | |
569 .. note:: This report must be used in conjunction with the ``distutils`` command | |
570 "unittest" that comes with Bitten. | |
571 | |
572 Parameters | |
573 ---------- | |
574 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
575 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
576 | Name | Description | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
577 +================+===========================================================+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
578 | ``file`` | Path to the XML results file, relative to the project | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
579 | | source directory. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
580 +----------------+-----------------------------------------------------------+ |
412 | 581 |
582 Examples | |
583 -------- | |
584 | |
585 .. code-block:: xml | |
586 | |
587 <python:unittest file="build/test-results.xml"/> | |
588 | |
589 Extracts the test results from the XML file located at | |
590 ``build/test-results.xml``. | |
591 | |
592 | |
593 ------------------ | |
594 ``<python:trace>`` | |
595 ------------------ | |
596 | |
597 Extracts coverage information recorded by the built-in Python module | |
598 ``trace.py``. | |
599 | |
600 Parameters | |
601 ---------- | |
602 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
603 +--------------+-------------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
604 | Name | Description | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
605 +==============+=============================================================+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
606 | ``summary`` | Path to the summary file written by ``trace.py``, | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
607 | |Â relative to the project source directory. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
608 +--------------+-------------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
609 | ``coverdir`` | Path to the directory containing the coverage files written | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
610 | | by ``trace.py``, relative to the project source directory. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
611 +--------------+-------------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
612 | ``include`` | List of glob patterns (separated by space) that specify | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
613 | | which Python file should be included in the coverage report | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
614 +--------------+-------------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
615 | ``exclude`` | List of glob patterns (separated by space) that specify | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
616 | | which Python file should be excluded from the coverage | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
617 | | report | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
618 +--------------+-------------------------------------------------------------+ |
412 | 619 |
620 Examples | |
621 -------- | |
622 | |
623 .. code-block:: xml | |
624 | |
625 <python:trace summary="build/trace.out" coverdir="build/coverage" /> | |
626 | |
627 ------------------- | |
628 ``<python:pylint>`` | |
629 ------------------- | |
630 | |
631 Extracts information from Pylint_ reports. | |
632 | |
633 .. _pylint: http://www.logilab.org/projects/pylint | |
634 | |
635 Parameters | |
636 ---------- | |
637 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
638 +--------------+-------------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
639 | Name | Description | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
640 +==============+=============================================================+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
641 | ``file`` | Path to the file containing the Pylint output, relative to | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
642 | | the project source directory. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
643 +--------------+-------------------------------------------------------------+ |
412 | 644 |
645 Examples | |
646 -------- | |
647 | |
648 .. code-block:: xml | |
649 | |
650 <python:pylint file="build/pylint.out" /> | |
651 | |
652 | |
415 | 653 Subversion Tools |
654 ================ | |
655 | |
656 A collection of recipe commands for working with the Subversion_ version | |
657 control system. This commands are commonly used as the first step of a build | |
658 recipe to actually pull the code that should be built from the repository. | |
659 | |
660 .. _subversion: http://subversion.tigris.org/ | |
661 | |
662 :Namespace: ``http://bitten.cmlenz.net/tools/svn`` | |
663 :Common prefix: ``svn`` | |
664 | |
665 | |
666 ------------------ | |
667 ``<svn:checkout>`` | |
668 ------------------ | |
669 | |
670 Check out a working copy from a Subversion repository. | |
671 | |
672 Parameters | |
673 ---------- | |
674 | |
675 +--------------+-------------------------------------------------------------+ | |
676 | Name | Description | | |
677 +==============+=============================================================+ | |
678 | ``url`` | URL of the repository. | | |
679 +--------------+-------------------------------------------------------------+ | |
680 | ``path`` | The path inside the repository that should be checked out. | | |
681 | | You should normally set this to ``${path}`` so that the | | |
682 | | path of the build configuration is used. | | |
683 +--------------+-------------------------------------------------------------+ | |
684 | ``revision`` | The revision that should be checked out. You should | | |
685 | | normally set this to ``${revision}`` so that the revision | | |
686 | | of the build is used. | | |
687 +--------------+-------------------------------------------------------------+ | |
688 | |
689 Examples | |
690 -------- | |
691 | |
692 .. code-block:: xml | |
693 | |
694 <svn:checkout url="http://svn.example.org/repos/myproject/" | |
695 path="${path}" revision="${revision}"/> | |
696 | |
697 This checks out the a working copy into the current directory. | |
698 | |
699 | |
700 ---------------- | |
701 ``<svn:export>`` | |
702 ---------------- | |
703 | |
704 Download a file or directory from a Subversion repository. This is similar to | |
705 performing a checkout, but will not include the meta-data Subversion uses to | |
706 connect the local working copy to the repository (i.e. it does not include the | |
707 ``.svn`` directories.) | |
708 | |
709 Parameters | |
710 ---------- | |
711 | |
712 +--------------+-------------------------------------------------------------+ | |
713 | Name | Description | | |
714 +==============+=============================================================+ | |
715 | ``url`` | URL of the repository. | | |
716 +--------------+-------------------------------------------------------------+ | |
717 | ``path`` | The path inside the repository that should be checked out. | | |
718 | | You should normally set this to ``${path}`` so that the | | |
719 | | path of the build configuration is used. | | |
720 +--------------+-------------------------------------------------------------+ | |
721 | ``revision`` | The revision that should be checked out. You should | | |
722 | | normally set this to ``${revision}`` so that the revision | | |
723 | | of the build is used. | | |
724 +--------------+-------------------------------------------------------------+ | |
725 | |
726 Examples | |
727 -------- | |
728 | |
729 .. code-block:: xml | |
730 | |
731 <svn:export url="http://svn.example.org/repos/myproject/" | |
732 path="${path}" revision="${revision}"/> | |
733 | |
734 This downloads the file or directory at ``${path}`` from the Subversion | |
735 repository at ``http://svn.example.org/repos/myproject/``. Variables are used | |
736 for the ``path`` and ``revision`` attributes so they are populated from the | |
737 properties of the build and build configuration. | |
738 | |
739 | |
740 ---------------- | |
741 ``<svn:update>`` | |
742 ---------------- | |
743 | |
744 Update an existing working copy from a Subversion repository to a specific | |
745 revision. | |
746 | |
747 Parameters | |
748 ---------- | |
749 | |
750 +--------------+-------------------------------------------------------------+ | |
751 | Name | Description | | |
752 +==============+=============================================================+ | |
753 | ``revision`` | The revision that should be checked out. You should | | |
754 | | normally set this to ``${revision}`` so that the revision | | |
755 | | of the build is used. | | |
756 +--------------+-------------------------------------------------------------+ | |
757 | |
758 Examples | |
759 -------- | |
760 | |
761 .. code-block:: xml | |
762 | |
763 <svn:update revision="${revision}"/> | |
764 | |
765 This updates the working copy in the current directory. The revision is | |
766 specified as a variable so that it is populated from the properties of the | |
767 build. | |
768 | |
769 | |
412 | 770 XML Tools |
771 ========= | |
772 | |
773 A collection of recipe commands for XML processing. | |
774 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
775 :Namespace: ``http://bitten.cmlenz.net/tools/xml`` |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
776 :Common prefix: ``x`` |
412 | 777 |
778 | |
779 ----------------- | |
780 ``<x:transform>`` | |
781 ----------------- | |
782 | |
783 Apply an XSLT stylesheet . | |
784 | |
785 .. note:: that this command requires either libxslt_ (with `Python bindings`_) | |
786 or, on Windows platforms, MSXML (version 3 or later) to be installed | |
787 on the slave machine. | |
788 | |
789 .. _libxslt: http://xmlsoft.org/XSLT/ | |
790 .. _`python bindings`: http://xmlsoft.org/XSLT/python.html | |
791 | |
792 Parameters | |
793 ---------- | |
794 | |
413
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
795 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
796 | Name | Description | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
797 +================+===========================================================+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
798 | ``src`` | Path of the source XML file. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
799 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
800 | ``dest`` | Path of the destition XML file. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
801 +----------------+-----------------------------------------------------------+ |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
802 | ``stylesheet`` | Path to the XSLT stylesheet file. | |
fa72698e7477
Don't put tables in blockquotes in command reference.
cmlenz
parents:
412
diff
changeset
|
803 +----------------+-----------------------------------------------------------+ |
412 | 804 |
805 All these are interpreted relative to the project source directory. | |
806 | |
807 Examples | |
808 -------- | |
809 | |
810 .. code-block:: xml | |
811 | |
812 <x:transform src="src.xml" dest="dest.xml" stylesheet="util/convert.xsl" /> | |
813 | |
814 This applies the stylesheet in ``util/convert.xsl`` to the source file | |
815 ``src.xml``, and writes the resulting XML document to ``dest.xml``. |