youys
/
ant

<html>
<head>
<title> .NET classes for Ant
</title>
<body bgcolor="#ffffff">
<h1>dotnet classes for Ant</h1>

<h3>Steve Loughran; steve_l@iseran.com</h3>
<h2>Vision</h2>
Make ant the definative build tool for .NET projects, just
as it is becoming for java projects
<p>

<h2>Detail. </h2>

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>

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>

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

<h2>Key .net Tasks</h2>

<ol>
<li>csc - csharp compiler - *.csc -&gt; output
<li>ilasm - IL assembler - *.il -&gt;.exe or .dll
<li>ResX - ResXToResources.exe .resx -&gt; .resources
<li>al - assembly linker (.dll) -&gt;
<li>Signcode - .exe + keys -&gt; .exe
<li>Resgen - .properties -&gt; .resources
<li>Type Library Exporter (TlbExp.exe) .dll -&gt; .tlb
<li>TlbImp.exe Type Library Importer 
<li>RegAsm.exe Assembly Registration Tool .dll -&gt; .reg | registration
<li>WebServiceUtil -SOAP proxy import, SDL generation tool
</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. 

<h2>Plan</h2>

<ol>

<li>code up C sharp task and distribute for feedback &amp; identify possible
aid
<li>Use for a real end to end development task
<li>Add the next task I need (whatever that is)
<li>Refactor to produce a base class for .net tasks
<li>Leave it other people write all the other tasks
</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>Portable tasks turn out to be harder than envisaged 
 (=reworking if/when non Win32 .net build tools appear)

</ul>

<hr>
<h2>Using Ant in .net projects</h2>

To use the net tasks one needs
<ul>

<li> A Win2K box (or any other platform which supports the .net build tools)

<li> JavaVM - Java1.1 or later; Java1.3 recommended.

<li> Ant downloaded and the environment and path variables set up so 
that typing 'ant' invokes ant via a batch file.

<li> An XML parser for ant. The usual distributions include an appropriate 
version parser.jar and jaxp.jar.

<li> the .net tasks archive (dotnettasks.jar) included in the
 ant\lib directory

<li> The .net sdk installed with the binaries on the path. (Test: type CSC)

<li> A build.xml file to describe the build process
</ul>

<hr>
<h2> Change Log </h2>

<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
<ul>
<li>Recursive inclusion of .cs and .il files

<li>Documentation enhanced, includes examples and details of all parameters

<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> References can also be referred to using the ReferenceFiles parameter, which
is an ant path specification. The old 'references' string is still retained.
<
li> An 'extraoptions' attribute enables the build file to include any CSC options
which are not explicitly supported in the CSC task. 
</ul>

Internal changes
<ul>
<li>Some minor refactoring (move common code a method)
<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>Removed throws clause from methods which can't throw exceptions 
</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: &lt;csc/&gt; 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>

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 valign="top">Semicolon separated list of modules to refer to
    </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"
	</tr>
<tr>
    <td valign="top">definitions
    <td valign="top">defined constants
    <td valign="top"> "RELEASE;BETA1"
    </tr>
<tr>
    <td valign="top">debug
    <td valign="top">include debug information
    <td valign="top">"true"(default) or "false"
    </tr>

<tr>
    <td valign="top">docFile
    <td valign="top">name of file for documentation
    <td valign="top">"doc.xml"
    </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"
  </tr>

  
<tr>
    <td valign="top">failOnError
    <td valign="top">Should a failed compile halt the build?
    <td valign="top">"true"(default) or "false"
    </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"
  </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 valign="top">Incremental build flag. Avoid till it works
    <td valign="top">"true" or "false"(default)
    </tr>
<tr>
    <td valign="top">mainClass
    <td valign="top">name of main class for executables
    <td valign="top">"com.example.project.entrypoint"
    </tr>
<tr>
    <td valign="top">optimize
    <td valign="top">optimisation flag
    <td valign="top">"true" or "false"(default)
    </tr>
<tr>
    <td valign="top">outputFile
    <td valign="top">filename of output
    <td valign="top">"example.exe"
    </tr>
<tr>
    <td valign="top">references
    <td valign="top">Semicolon separated list of dlls to refer to
	<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 valign="top"></td>
    </tr>
	
<tr>
    <td valign="top">srcDir
    <td valign="top">source directory (default = project directory)
    <td valign="top">"."</td>
    </tr>
<tr>
    <td valign="top">targetType
    <td valign="top">Type of target
    <td valign="top">"exe","module","winexe" or "library"
    </tr>
<tr>
    <td valign="top">unsafe
    <td valign="top">enable unsafe code
    <td valign="top">"true" or "false"(default)
    </tr>
<tr>
    <td valign="top">warnLevel
    <td valign="top">level of warning currently between 1 and 4 with 4
	being the strictest. 
    <td valign="top">"1"-"4"
    </tr>
<tr>
    <td valign="top">win32Icon
    <td valign="top">filename of icon to include
 	<td valign="top">"res/myicon.ico"</td>
   </tr>

</table>
<p>
Example
<pre>&lt;csc
        optimize=&quot;true&quot;
        debug=&quot;false&quot;
        docFile=&quot;documentation.xml&quot;
        warnLevel=&quot;4&quot;
        unsafe=&quot;false&quot;
        targetType=&quot;exe&quot;
        incremental=&quot;false&quot;
        definitions=&quot;RELEASE&quot;
        excludes=&quot;src/unicode_class.cs&quot;
        mainClass = &quot;MainApp&quot;
        outputFile=&quot;NetApp.exe&quot;
        /&gt;   
</pre>
<hr>
<h2> Task: ilasm </h2>
Task to assemble .net 'Intermediate Language' files.
The task will only work on win2K until other platforms support csc.exe or 
an equivalent. ilasm.exe must be on the execute path too.
<p>

<p>
All parameters are optional: &lt;il/&gt; 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>

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>
  <tr>
    <td valign="top">defaultexcludes</td>
    <td valign="top">indicates whether default excludes should be used or not
      (&quot;yes&quot;/&quot;no&quot;). Default excludes are used when omitted.</td>
  </tr>

<tr>
    <td valign="top">debug
    <td valign="top">include debug information
    <td valign="top">true (default)
    </tr>
<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 </td>
	<td>
  </tr>
  
<tr>
    <td valign="top">failOnError
    <td valign="top">Should a failed compile halt the build?
    <td valign="top">"true"(default)
    </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">listing
    <td valign="top">Produce a listing (off by default). Listings go to the
	current output stream
    <td valign="top">"on", "off" (default)
    </tr>
<tr>
    <td valign="top">outputFile
    <td valign="top">filename of output
    <td valign="top">"example.exe"
    </tr>
<tr>
    <td valign="top">owner
    <td valign="top">restrict disassembly by setting the 'owner' string
    <td valign="top">"secret"
    </tr>
<tr>
    <td valign="top">resourceFile
    <td valign="top">name of resource file to include
    <td valign="top">"resources.res"
    </tr>
<tr>
    <td valign="top">srcDir
    <td valign="top">source directory (default = project directory)
    <td valign="top">
    </tr>
<tr>
    <td valign="top">targetType
    <td valign="top">Type of target. library means DLL is output. 
    <td valign="top">"exe"(default),"library"
    </tr>
<tr>
    <td valign="top">verbose
    <td valign="top">output progress messages
    <td valign="top">"on", "off" (default)
    </tr>

</table>
<p>
Example
<pre>&lt;ilasm
        outputFile=&quot;app.exe&quot;
        verbose=&quot;on&quot;
        listing=&quot;on&quot;
        owner=&quot;secret&quot;
        /&gt;
</pre>
<hr>
<p align="center">Copyright &copy; 2000 Apache Software Foundation. All rights
Reserved.</p>

</body>
</html>