Changes between Version 6 and Version 7 of Build Recipes

Timestamp:

Sep 22, 2005, 3:57:57 PM (19 years ago)

Author:

cmlenz

Comment:

Updated to reflect recipe changes in trunk

Build Recipes

@@ -1 +1 @@
 = Bitten Build Recipes =
+
+  ''Note: the recipe format has changed since [milestone:0.4]. You can find documentation about the previous format by looking at version 6 of this page (see the “page history” link above).''
 
 A ''build recipe'' tells a build slave how a project is to be built. It consists of multiple ''build steps'', each defining a command to execute, and where artifacts can be found after that command has successfully completed.
@@ -9 +11 @@
 == File Format ==
 
-Build recipes are stored internally in an XML-based format. Recipe files have a single `<build>` root element with one or more `<step>` child elements. The steps are executed in the order they appear in the recipe. A `<step>` element will consist of any number of commands and reports. These elements are declared in XML namespaces, where the namespace URL is a pseudo-protocol that defines which Python module they are implemented in:
+Build recipes are stored internally in an XML-based format. Recipe files have a single `<build>` root element with one or more `<step>` child elements. The steps are executed in the order they appear in the recipe. A `<step>` element will consist of any number of commands and reports. These elements are declared in XML namespaces, where the namespace URI defines a collection of commands:
 
 {{{
 #!xml
 <build description="My project"
-    xmlns:python="bitten:bitten.build.pythontools">
+    xmlns:python="http://bitten.cmlenz.net/tools/python">
 
   <step id="build" description="Compile to byte code">
@@ -22 +24 @@
   <step id="test" description="Run unit tests">
     <python:distutils command="unittest"/>
-    <reports>
-      <python:unittest file="build/test-results.xml"/>
-      <python:trace summary="build/test-coverage.txt" 
-          coverdir="build/coverage" include="trac*" exclude="*.tests.*"/>
+    <python:unittest file="build/test-results.xml"/>
+    <python:trace summary="build/test-coverage.txt" 
+        coverdir="build/coverage" include="trac*" exclude="*.tests.*"/>
     </reports>
   </step>
@@ -34 +35 @@
 == Recipe Command Binding ==
 
-As noted above, recipe commands and report generators are mapped to Python modules using XML namespaces. The URI of recipe namespace that uses the ''bitten'' scheme is mapped to the corresponding module. Commands and report generators are then mapped to functions inside that module.
+Recipe commands and report generators are mapped to Python functions using [http://peak.telecommunity.com/DevCenter/PkgResources#entry-points entry points]. Bitten itself comes with a number of entry points that provide recipe commands, but third-party packages can provide additional commands by declaring their own `bitten.recipe_commands` entry points.
 
-For example, the command `<python:distutils>` (where the namespace prefix `python` resolves to `bitten:bitten.build.pythontools`) is mapped to the function `distutils` in the `bitten.build.pythontools` module. The function is invoked with any provided attributes passed as keyword arguments.
+The values of attributes on recipe command elements are passed to the function as keyword arguments. Special care must be taken with names that are either not valid Python identifiers, or that conflict with Python keywords or built-in functions. Dashes in names are replaced with underscores, and names that conflict with keywords or built-in functions get an underscore appended.
 
-So, the XML snippet:
+So, for example:
 {{{
-  <python:distutils command="build"/>
+  <foo:bar file="tools/tabcheck.py" ignore-errors="yes"/>
 }}}
 
 gets tranlated into:
 {{{
-from bitten.build.pythontools import distutils
-distutils(ctxt, command='build')
+bar(ctxt, file_='tools/tabcheck.py', ignore_errors='yes')
 }}}
-
-Special care must be taken with names that are either not valid Python identifiers, or that conflict with Python keywords or built-in functions. Dashes in names are replaced with underscores, and names that conflict with keywords or built-in functions get an underscore appended.
-
-So, for example:
-{{{
-  <python:exec file="tools/tabcheck.py"/>
-}}}
-
-gets tranlated into:
-{{{
-from bitten.build.pythontools import exec_
-exec_(ctxt, file_='tools/tabcheck.py')
-}}}