Edgewall Software

Changes between Version 10 and Version 11 of Recipe Commands


Ignore:
Timestamp:
Aug 23, 2007, 7:03:35 PM (17 years ago)
Author:
cmlenz
Comment:

Redirect to real documentation

Legend:

Unmodified
Added
Removed
Modified

  • Recipe Commands

    v10 v11  
    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`.
     1See [wiki:Documentation/commands.html Build Recipe Commands]