| <html> |
| <head> |
| <title> .NET classes for Ant |
| </title> |
| </head> |
| |
| <body bgcolor="#ffffff"> |
| <h1>.NET classes for Ant</h1> |
| |
| <h2>Vision</h2> |
| <p> |
| Make ant the definitive build tool for .NET projects, just |
| as it is becoming for java projects |
| </p> |
| |
| <h2>Detail</h2> |
| |
| <p> |
| The emergent policy in big java projects is 'IDE for code and debug'; |
| Ant for builds, test and deployment. While IDEs are great for an |
| individual development task, Ant not only rebuilds everything insanely |
| fast, it has great support for modern deployment tasks -ftp upload, |
| EJB servers, SQL commands, all can be done from a relatively simple |
| XML declaration of what you want done. Also in a large project |
| (especially open source) there is no means of dictating which IDE to use. |
| Ant gives IDE independence, cross platform portability and ease of |
| extensibility. </p> |
| |
| <p> |
| |
| Projects using .net should be able to use the same tool. This will |
| avoid everyone being dependent on Visual Studio.net (if they have it) |
| supplemented with makefiles and batch files. Anyone doing mixed java/dotnet |
| development will be particulary grateful, as they can have a unified build |
| process. </p> |
| |
| <p> |
| |
| If at sometime in the future bits of .net do appear on different platforms |
| then ant based build files will migrate -once the ant tasks have been |
| migrated and any hard codings of DOS-descendant file system conventions |
| removed from the build.xml files.</p> |
| |
| <h2>Key .net Tasks</h2> |
| |
| <ol> |
| <li>csc - csharp compiler - *.csc -> output</li> |
| <li>ilasm - IL assembler - *.il ->.exe or .dll</li> |
| <li>ResX - ResXToResources.exe .resx -> .resources</li> |
| <li>al - assembly linker (.dll) -></li> |
| <li>Signcode - .exe + keys -> .exe</li> |
| <li>Resgen - .properties -> .resources</li> |
| <li>Type Library Exporter (TlbExp.exe) .dll -> .tlb</li> |
| <li>TlbImp.exe Type Library Importer </li> |
| <li>RegAsm.exe Assembly Registration Tool .dll -> .reg | registration</li> |
| </ol> |
| |
| <h2>Ant Wrapper for net tasks</h2> |
| |
| Rarely used .net command line tools can be invoked manually. The key tasks |
| to address are the common steps in a build process and those which benefit |
| from the file pattern matching function. |
| |
| <p> |
| |
| The esoteric tasks can then supported on demand by those who need them. |
| The initial .net tasks should provide a foundation for that demand creation |
| to be simple. </p> |
| |
| <h2>Plan</h2> |
| |
| <ol> |
| |
| <li>code up C sharp task and distribute for feedback & identify possible |
| aid</li> |
| <li>Use for a real end to end development task</li> |
| <li>Add the next task I need (whatever that is)</li> |
| <li>Refactor to produce a base class for .net tasks</li> |
| <li>Leave it other people write all the other tasks</li> |
| </ol> |
| |
| <h2>Risks</h2> |
| <ul> |
| <li> |
| The .net SDK is unstable; the next builds will change the commands, arguments |
| and behaviours. Probability: 100%. Impact: 2 days.</li> |
| <li>Portable tasks turn out to be harder than envisaged |
| (=reworking if/when non Win32 .net build tools appear)</li> |
| |
| </ul> |
| |
| <hr> |
| <h2>Using Ant in .net projects</h2> |
| |
| To use the net tasks one needs |
| <ul> |
| |
| <li> A Windows box (or any other platform which supports the .net build tools)</li> |
| |
| <li> JavaVM - Java1.1 or later; Java1.3 recommended.</li> |
| |
| <li> Ant downloaded and the environment and path variables set up so |
| that typing 'ant' invokes ant via a batch file.</li> |
| |
| <li> An XML parser for ant. The usual distributions include an appropriate |
| version crimson.jar and jaxp.jar.</li> |
| |
| <li> the .net tasks archive (dotnettasks.jar) included in the |
| ant\lib directory</li> |
| |
| <li> The .net sdk installed with the binaries on the path. (Test: type CSC)</li> |
| |
| <li> A build.xml file to describe the build process</li> |
| </ul> |
| |
| <hr> |
| <h2> Change Log </h2> |
| |
| <h4>Version 0.4</h4> |
| This is the beta-2 revision of the tasks. |
| <ol> |
| <li>ILASM: pulled the owner attribute, added keyfile for giving binaries a strong name |
| (MD5 hash of the checksum) |
| <li>CSC: added win32res , noConfig, utf8output, fullpaths |
| <li>CSC: |
| </ol> |
| |
| <h4>Version 0.3</h4> |
| |
| The changes here reflect Beta-1 of the dotnet SDK and experience of use in |
| more complex projects. This build does not work with the older SDK, |
| primarily because the automatic reference feature references libraries |
| only found in the new SDK version. |
| <p> |
| External changes</p> |
| <ul> |
| <li>Recursive inclusion of .cs and .il files</li> |
| |
| <li>Documentation enhanced, includes examples and details of all parameters</li> |
| |
| <li>The csc task automatically includes the common dotnet assemblies, so |
| there is no need to remember to refer to 'System.dll', 'System.Web.Services', |
| etc. This feature can be disabled by setting the 'includeDefaultReferences' |
| flag to false. </li> |
| |
| <li> References can also be referred to using the ReferenceFiles parameter, which |
| is an ant path specification. The old 'references' string is still retained.</li> |
| <li> An 'extraoptions' attribute enables the build file to include any CSC options |
| which are not explicitly supported in the CSC task. </li> |
| </ul> |
| |
| Internal changes |
| <ul> |
| <li>Some minor refactoring (move common code a method)</li> |
| <li>Application of Jedits JavaStyle task resulted in a major reshaping of |
| the codebase and the insertion of a blank line every second line. Significant |
| effort was required to revert some (but not all) changes.</li> |
| <li>Removed throws clause from methods which can't throw exceptions </li> |
| </ul> |
| |
| The test harness has been expanded to include unicode source file |
| (the build works but the rest of the system has 'issues' with high unicode |
| package and method names) |
| |
| <h4>Version 0.2</h4> |
| First public edition, added to the ant cvs tree. Tested on the PDC build of |
| the dotnet SDK only, and still immature. The command execution code was |
| refactored out into a 'NetCommand' class for re-use. The Ilasm task was added |
| at this time. |
| |
| <h4>Version 0.1</h4> |
| Initial proof of concept; very rudimentary support for CSC only. |
| |
| <hr> |
| <h2>Task: CSC</h2> |
| |
| This task compiles CSharp source into executables or modules. |
| |
| This task compiles CSharp source into executables or modules. |
| The task will only work on win2K until other platforms support csc.exe or |
| an equivalent. CSC.exe must be on the execute path too. |
| |
| <p> |
| All parameters are optional: <csc/> should suffice to produce a debug |
| build of all *.cs files. References to external files do require explicit |
| enumeration, so are one of the first attributes to consider adding. </p> |
| |
| <p> |
| |
| The task is a directory based task, so attributes like <b>includes="**/*.cs"</b> and |
| <b>excludes="broken.cs"</b> can be used to control the files pulled in. By default, |
| all *.cs files from the project folder down are included in the command. |
| When this happens the output file -if not specified- |
| is taken as the first file in the list, which may be somewhat hard to control. |
| Specifying the output file with <b>'outfile'</b> seems prudent. </p> |
| |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Example Values</b></td> |
| </tr> |
| |
| <tr> |
| <td valign="top">additionalModules</td> |
| <td valign="top">Semicolon separated list of modules to refer to</td> |
| </tr> |
| <tr> |
| <td valign="top">defaultexcludes</td> |
| <td valign="top">indicates whether default excludes should be used or not |
| </td> |
| <td valign="top">"true"(default) or "false"</td> |
| </tr> |
| <tr> |
| <td valign="top">definitions</td> |
| <td valign="top">defined constants</td> |
| <td valign="top"> "RELEASE;BETA1"</td> |
| </tr> |
| <tr> |
| <td valign="top">debug</td> |
| <td valign="top">include debug information</td> |
| <td valign="top">"true"(default) or "false"</td> |
| </tr> |
| |
| <tr> |
| <td valign="top">docFile</td> |
| <td valign="top">name of file for documentation</td> |
| <td valign="top">"doc.xml"</td> |
| </tr> |
| <tr> |
| <td valign="top">excludes</td> |
| <td valign="top">comma separated list of patterns of files that must be |
| excluded. No files (except default excludes) are excluded when omitted.</td> |
| </tr> |
| <tr> |
| <td valign="top">excludesfile</td> |
| <td valign="top">the name of a file. Each line of this file is |
| taken to be an exclude pattern</td> |
| </tr> |
| <tr> |
| <td valign="top">extraOptions</td> |
| <td valign="top">Any extra options which aren't explicitly |
| supported by the CSharp task </td> |
| <td>"/warnaserror+ /baseaddress:0x12840000"</td> |
| </tr> |
| |
| |
| <tr> |
| <td valign="top">failOnError</td> |
| <td valign="top">Should a failed compile halt the build?</td> |
| <td valign="top">"true"(default) or "false"</td> |
| </tr> |
| <tr> |
| <td valign="top">fullpaths</td> |
| <td valign="top">print the full path of files on on errors</td> |
| </tr> |
| |
| <tr> |
| <td valign="top">includes</td> |
| <td valign="top">comma separated list of patterns of files that must be |
| included. All files are included when omitted.</td> |
| </tr> |
| <tr> |
| <td valign="top">includeDefaultReferences</td> |
| <td valign="top">Flag which when true automatically includes |
| the common assemblies in dotnet beta1, and tells the compiler to link in |
| mscore.dll |
| </td> |
| <td valign="top">"true"(default) or "false"</td> |
| </tr> |
| |
| <tr> |
| <td valign="top">includesfile</td> |
| <td valign="top">the name of a file. Each line of this file is |
| taken to be an include pattern</td> |
| </tr> |
| |
| <tr> |
| <td valign="top">incremental</td> |
| <td valign="top">Incremental build flag. Avoid till it works</td> |
| <td valign="top">"true" or "false"(default)</td> |
| </tr> |
| <tr> |
| <td valign="top">mainClass</td> |
| <td valign="top">name of main class for executables</td> |
| <td valign="top">"com.example.project.entrypoint"</td> |
| </tr> |
| <tr> |
| <td valign="top">noConfig</td> |
| <td valign="top">a flag which tells the compiler not |
| to read in the compiler settings files 'csc.rsp' in its |
| bin directory and then the local directory</td> |
| <td valign="top">"true" or "false"(default)</td> |
| </tr> |
| <tr> |
| <td valign="top">optimize</td> |
| <td valign="top">optimisation flag</td> |
| <td valign="top">"true" or "false"(default)</td> |
| </tr> |
| <tr> |
| <td valign="top">outputFile</td> |
| <td valign="top">filename of output</td> |
| <td valign="top">"example.exe"</td> |
| </tr> |
| <tr> |
| <td valign="top">references</td> |
| <td valign="top">Semicolon separated list of dlls to refer to</td> |
| <td valign="top">"mylib.dll;nunit.dll"</td> |
| </tr> |
| <tr> |
| <td valign="top">referenceFiles </td> |
| <td valign="top">Ant Path descriptioon of references to include. |
| Wildcards should work. </td> |
| <td valign="top"></td> |
| </tr> |
| |
| <tr> |
| <td valign="top">srcDir</td> |
| <td valign="top">source directory (default = project directory)</td> |
| <td valign="top">"."</td> |
| </tr> |
| <tr> |
| <td valign="top">targetType</td> |
| <td valign="top">Type of target</td> |
| <td valign="top">"exe", "module", "winexe" or "library"</td> |
| </tr> |
| <tr> |
| <td valign="top">unsafe</td> |
| <td valign="top">enable the <b>unsafe</b> keyword</td> |
| <td valign="top">"true" or "false"(default)</td> |
| </tr> |
| <tr> |
| <td valign="top">utf8output</td> |
| <td valign="top">require all compiler output to be in utf-8 format</td> |
| <td valign="top">"true" or "false"(default)</td> |
| </tr> |
| <tr> |
| <td valign="top">warnLevel</td> |
| <td valign="top">level of warning currently between 1 and 4 with 4 |
| being the strictest. </td> |
| <td valign="top">"1"-"4"</td> |
| </tr> |
| <tr> |
| <td valign="top">win32Icon</td> |
| <td valign="top">filename of icon to include</td> |
| <td valign="top">"res/myicon.ico"</td> |
| </tr> |
| <tr> |
| <td valign="top">win32res</td> |
| <td valign="top">filename of a win32 resource (.RES)file to include |
| This is not a .NET resource, but it what windows is used to.</td> |
| <td valign="top">"res/myapp.res"</td> |
| </tr> |
| |
| </table> |
| <p> |
| Example |
| </p> |
| <pre><csc |
| optimize="true" |
| debug="false" |
| docFile="documentation.xml" |
| warnLevel="4" |
| unsafe="false" |
| targetType="exe" |
| incremental="false" |
| definitions="RELEASE" |
| excludes="src/unicode_class.cs" |
| mainClass = "MainApp" |
| outputFile="NetApp.exe" |
| /> |
| </pre> |
| <hr> |
| <h2> Task: ilasm </h2> |
| <p>Task to assemble .net 'Intermediate Language' files. |
| The task will only work on windows until other platforms support csc.exe or |
| an equivalent. ilasm.exe must be on the execute path too. |
| </p> |
| <p> |
| All parameters are optional: <il/> should suffice to produce a debug |
| build of all *.il files. |
| The option set is roughly compatible with the CSharp class; |
| even though the command line options are only vaguely |
| equivalent. [The low level commands take things like /OUT=file, |
| csc wants /out:file ... /verbose is used some places; /quiet here in |
| ildasm... etc.] It would be nice if someone made all the command line |
| tools consistent (and not as brittle as the java cmdline tools) |
| </p> |
| |
| <p> |
| |
| The task is a directory based task, so attributes like <b>includes="*.il"</b> and |
| <b>excludes="broken.il"</b> can be used to control the files pulled in. |
| Each file is built on its own, producing an appropriately named output file unless |
| manually specified with <b>outfile</b> |
| </p> |
| |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Example</b></td> |
| </tr> |
| |
| <tr> |
| <td valign="top">defaultexcludes</td> |
| <td valign="top">indicates whether default excludes should be used or not |
| ("yes"/"no"). Default excludes are used when omitted.</td> |
| </tr> |
| |
| <tr> |
| <td valign="top">debug</td> |
| <td valign="top">include debug information</td> |
| <td valign="top">true (default)</td> |
| </tr> |
| |
| <tr> |
| <td valign="top">excludes</td> |
| <td valign="top">comma separated list of patterns of files that must be |
| excluded. No files (except default excludes) are excluded when omitted.</td> |
| </tr> |
| <tr> |
| <td valign="top">excludesfile</td> |
| <td valign="top">the name of a file. Each line of this file is |
| taken to be an exclude pattern</td> |
| </tr> |
| <tr> |
| <td valign="top">extraOptions</td> |
| <td valign="top">Any extra options which aren't explicitly |
| supported by the ilasm task, primarily because they |
| arent really documented: use ilasm /? to see them</td> |
| <td></td> |
| </tr> |
| |
| <tr> |
| <td valign="top">failOnError</td> |
| <td valign="top">Should a failed compile halt the build?</td> |
| <td valign="top">"true"(default)</td> |
| </tr> |
| <tr> |
| <td valign="top">fullpaths</td> |
| <td valign="top">Should error text provide the full path to files</td> |
| <td valign="top">"true"(default)</td> |
| </tr> |
| <tr> |
| <td valign="top">includes</td> |
| <td valign="top">comma separated list of patterns of files that must be |
| included. All files are included when omitted.</td> |
| </tr> |
| <tr> |
| <td valign="top">includesfile</td> |
| <td valign="top">the name of a file. Each line of this file is |
| taken to be an include pattern</td> |
| </tr> |
| <tr> |
| <td valign="top">keyfile</td> |
| <td valign="top">the name of a file containing a private key, with which |
| the assembly output is checksumed and then MD5 signed |
| to have a <i>strong name</i></td> |
| </tr> |
| <tr> |
| <td valign="top">listing</td> |
| <td valign="top">Produce a listing (off by default). Listings go to the |
| current output stream</td> |
| <td valign="top">"on", "off" (default)</td> |
| </tr> |
| <tr> |
| <td valign="top">outputFile</td> |
| <td valign="top">filename of output</td> |
| <td valign="top">"example.exe"</td> |
| </tr> |
| <tr> |
| <td valign="top">resourceFile</td> |
| <td valign="top">name of resource file to include</td> |
| <td valign="top">"resources.res"</td> |
| </tr> |
| <tr> |
| <td valign="top">srcDir</td> |
| <td valign="top">source directory (default = project directory)</td> |
| <td valign="top"></td> |
| </tr> |
| <tr> |
| <td valign="top">targetType</td> |
| <td valign="top">Type of target. library means DLL is output. </td> |
| <td valign="top">"exe"(default), "library"</td> |
| </tr> |
| <tr> |
| <td valign="top">verbose</td> |
| <td valign="top">output progress messages</td> |
| <td valign="top">"on", "off" (default)</td> |
| </tr> |
| |
| </table> |
| <p> |
| Example</p> |
| <pre><ilasm |
| outputFile="app.exe" |
| verbose="on" |
| listing="on" |
| owner="secret" |
| /> |
| </pre> |
| <hr> |
| <p align="center">Copyright © 2000 Apache Software Foundation. All rights |
| Reserved.</p> |
| |
| </body> |
| </html> |
