ANT Tasks for .NET code generation

Introduction

Codemesh provides you with a set of custom ANT tasks for .NET proxy class generation. The custom tasks require a Java2 runtime and ANT 1.6.5. Later versions of ANT might work as well, but we are using some deprecated elements that might eventually be removed from later ANT versions.

The custom ANT tasks and related elements are bundled in a jar file called ant-codemesh.jar. You can find this file in the JuggerNET distribution's lib directory.

The code generator that you downloaded includes a copy of ANT 1.6.5 that is configured with ant-codemesh.jar  as part of its ANT classpath, so you won't have to do anything special to make the custom tasks work for you. If you're planning to use your own copy of ANT, you will have to add the supplied jar file to ANT's classpath and you will have to declare the custom tasks in your build script. The examples folder contains a file called taskdefs.xml, which declares the custom tasks for your build. Simply include that file in your build script.

The code generator task

The code generator is called <juggernet>. It extends the <java> task and therefore accepts all Java-related configuration attributes and nested elements. To illustrate this, the following (incomplete) snippet runs the code generator with more heap memory by using the inherited maxmemory attribute:

           <juggernet modelfile="test"
                      maxmemory="756m">
           </juggernet>

It's very common to have to give the code generator more heap if you're dealing with large class sets.

<juggernet> task attributes

Attribute Comment Required / Default value
cli Run the command line version (i.e. don't start the GUI). Mutually exclusive with gui attribute. Only makes sense when paired with generatecpp attribute. No / true
generatedotnet Generate C# proxy types and then exit. Only makes sense when paired with cli attribute. No / true
gui Run the GUI version of the code generator. No / false
homedir The directory in which the code generator is installed. Yes, unless property com.codemesh.xmog.home is specified and refers to correct directory.
logfile The name of a file into which the code generator logs messages. No
modelfile The full path of the modelfile that is used for code generation. For programmatic code generation you need to specify either this attribute or use a <modelfile> nested element.
targetdir The target directory into which the code will be generated. Yes, unless the modelfile contains a targetdir setting.
warningstoerrors Should code generator warnings be converted to errors? No / false

 

Predominantly , you will use the <juggernet> element in two ways:

  1. to programmatically generate proxy types for an existing modelfile as part of your ANT build.
  2. to programmatically generate proxy types completely based on a <modelfile> nested element, i.e. the ANT build does not rely on a previously created modelfile.

The first alternative is only useful if you use ANT on the development machine where you initially created the modelfile or if you generated the modelfile specifically for the build machine. That is due to the fact that there are absolute paths that are embedded in the modelfile.

The second alternative is much more generically useful because you have the full power of ANT at your command to specify a "modelfile" as part of your ANT build script. Let's take a look at an example of such a code generator invocation:

           <juggernet maxmemory="756m">
               <modelfile>
                   <jdkhome value="${jdk.dir}"/>
                   <targetdir value="${target.dir}"/>
                   <classpath>
                       <pathelement location="${basedir}"/>
                   <classpath>
                   <importclass name="java.lang.String"/>
                   <importclass name="java.lang.System"/>
                   <importclass name="com.codemesh.examples.Arrays"/>
               </modelfile>
           </juggernet>

In the above snippet, you can see the power that you gain from ANT build variables like jdk.dir or project.version. Using such build parameters, you can create one build script that build on all build machines, simply by including different property files or by passing the correct, host-specific -D options as build arguments. The <modelfile> element has several attributes and accepts a wide range of nested elements. Essentially, every configuration setting from the Properties dialog and every action you can take in the code generator has a corresponding <modelfile> nested element. The following tables contains the complete list of <modelfile> attributes and nested elements.

<modelfile> attributes

Attribute Comment Requires / Default value
classpath Allows you to specify the classpath for your model. It is typically recommended that you put all jarfiles that are required to run your Java application on the model classpath and then import the classes that you are particularly interested in. No / null
codemeshhomedir The root directory of the code generator installation. This is needed to find the code generator jarfiles and to know where the runtime classes can be found. Yes, unless property com.codemesh.xmog.home is specified and refers to correct directory.
file The location of an already existing modelfile. Identical to loc attribute. No / null
jrelibdir The directory in which the Java runtime jars are located. Identical to libdir attribute. Yes, one of jrelibdir or libdir.
libdir The directory in which the Java runtime jars are located. Identical to jrelibdir attribute. Yes, one of jrelibdir or libdir.
loc The location of an already existing modelfile. Identical to file attribute. No / null
name The modelfile's name without the .cmm extension. Mutually exclusive with file and loc. Yes, if file or loc are not specified.
sort Specifies whether the nested elements should be sorted into a usually meaningful order (preferences before import commands before generation status modifications). Setting an import option only makes sense if you do it before you import Java classes into the model, otherwise it will effectively be disregarded. Setting this option to true allows you to not worry about the order in which you add nested elements to the modelfile. No / false
targetdir The directory into which the proxy classes are generated. Yes

<modelfile> nested elements

Nested Element Comment Required / Default value
addclasspathroot Adds a classpath root to the model. When using ANT to create a modelfile, you can always specify the complete classpath using the <classpath> element, so there should be no need for you to use this nested element.  
additionalincludedirs Allows you to add an additionally required include directory to generated project or makefiles. This might be necessary if you also add external source files that require this directory to be on their include search path.  
additionallibdirs Allows you to add an additionally required library directory to generated project or makefiles. This might be necessary if you also add external libraries that require this directory to be on their library search path.  
additionallibraries Allows you to add an additionally required library to generated project or makefiles. This might be necessary if you also add external source files that require you to link with this library.  
additionalpreprocdefs Allows you to add a preprocessor directive to generated project or makefiles. This might be necessary if you also add external source files.  
additionalsources Allows you to add an additional source files to generated project or makefiles. You might wish to do this to build a library with a user supplied configuration hook or simply to combine generated code with userwritten code in one library.  
allowdangling Specifies whether or not missing Java classes during the import phase should be regarded as an error or not. You should typically not allow dangling (missing) classes. The only exception is when you don't have access to certain private types that are not referenced by your classes but that are not requried as public types and whose absence consequently does not impact the generated code.  
arrayrank The code generator can declare typedef's for arrays of proxy types. This setting allows you to specify, how many dimensions you're interested in.  
cachingpolicy Deprecated.  
callback Allows you to specify that a certain method is a callback method. You need to do this if your interface type does not follow the traditional naming patterns for callbacks (ends with "Listener" etc.)  
classpath Allows you to specify the classpath for your model. It is typically recommended that you put all jarfiles that are required to run your Java application on the model classpath and then import the classes that you are particularly interested in.  
codemeshhomedir The root directory of the code generator installation. This is needed to find the code generator jarfiles and to know where the runtime classes can be found.  
doccopyright A copyright notice that is put into generated documentation. The default value is the empty string.  
docencoding Currently not supported.  
docproductname A string that appears as the title string in the generated documentation.  
doctype Currently only supports "text/html", which is the default value as well.  
docversion A string that appears as the version number in the generated documentation.  
doxygenoptions Additional commandline options that are passed when the code generator invokes doxygen.  
generateclass Allows you to mark a class of a given name as generating or not generating.  
generatedevstudiofiles    
generatedoc    
generatefield    
generateframeworkdoc    
generateindex    
generateinnerclasses    
generatemakefile    
generatemethod    
generatepackage    
generatepackageincludes    
import    
importclass    
javadocoptions    
javasourceversion    
javatargetversion    
jdkhome    
peertype    
preference    
projectguid    
reservednames    
rmicallback    
runtimeconfiguration    
runtimeversion    
searchforrealnamesinjava    
searchforrealnamesinusercode    
storageclassmacro    
targetdir    
targetname    
usebool    
usenamespaces    

Summary

The best way to understand ANT build scripts is to take a look at some of them. All JuggerNET example builds are based on ANT and you can learn a lot from analyzing and copying them. The following examples just demonstrate some advanced usages that are not covered in any of the bundled examples.

Example: Using filename patterns with loose class files

Often, your classfiles come packaged up in one or more jar files. Sometimes, for complex build scenarios, it may be beneficial to unjar the classfiles. This gives you the ability to use ANT filename patterns to include and exclude types from the set that is to be imported into the model. The following snippet assumes that the classes have been unjared into a directory represented by the build variable root.dir:

<juggernet>
  <modelfile>
     ...

     <import dir="${root.dir}"/>
       <include name="com/myapi/**/*.class"/>
       <exclude name="com/myapi/**/*Impl.class"/>
     </import>

  </modelfile>
</juggernet>

In this snippet, we include all classes in the com.myapi package and its subpackages, except for classes whose name ends with the string Impl. All you have to remember is to limit imports to files ending with the string .class. This selective pattern matching is something that the code generator currently doesn't support as a built-in feature, but that ANT allows you to do easily.

 


Copyright 2006-2011 by Codemesh, Inc., ALL RIGHTS RESERVED

:
ant code generator tasks
home products support customers partners newsroom about us contact us