wangwei
/
antliscence
forked from youys/ant

<html>
<head>
<title>.NET Tasks</title>
</head>

<body>
<h1>.NET tasks</h1>


<hr>
<h2>&lt;CSC&gt;</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/XP or other platforms with csc.exe or an equivalent.
CSC must be on the execute path.

<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>

<p>

The task is a directory based task, so attributes like 
<b>includes=&quot;**/*.cs&quot;</b> and 
<b>excludes=&quot;broken.cs&quot;</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 destFile -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>'destfile'</b> seems prudent. </p>
<p>
Also, dependency checking only works if destfile is set.

<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">&quot;true&quot;(default) or &quot;false&quot;</td>
    </tr>
<tr>
    <td valign="top">definitions</td>
    <td valign="top">defined constants</td>
    <td valign="top"> &quot;RELEASE;BETA1&quot;</td>
    </tr>
<tr>
    <td valign="top">debug</td>
    <td valign="top">include debug information</td>
    <td valign="top">&quot;true&quot;(default)</td>
    </tr>

<tr>
    <td valign="top">destFile</td>
    <td valign="top">name of exe/library to create</td>
    <td valign="top">&quot;example.exe&quot;</td>
    </tr>
<tr>
    <td valign="top">docFile</td>
    <td valign="top">name of file for documentation</td>
    <td valign="top">&quot;doc.xml&quot;</td>
    </tr>
  <tr>
    <td valign="top">excludes</td>
    <td valign="top">comma- or space-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>&quot;/warnaserror+ /baseaddress:0x12840000&quot;</td>
  </tr>

  <tr>
    <td valign="top">failOnError</td>
    <td valign="top">Should a failed compile halt the build?</td>
    <td valign="top">&quot;true&quot;(default) or &quot;false&quot;</td>
  </tr>
  
  <tr>
    <td valign="top">fileAlign</td>
    <td valign="top">
     set the file alignment.
     Valid values are 0,512, 1024, 2048, 4096, 8192, and 16384
     0 means 'leave to the compiler'    
    </td>
    <td valign="top">512</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- or space-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">Controls csc's /nostdlib argument,
    &quot;true&quot;(default) implies /nostdlib-.
    </td>
    <td valign="top">&quot;true&quot;(default) or &quot;false&quot;</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">&quot;true&quot; or &quot;false&quot;(default)</td>
    </tr>
<tr>
    <td valign="top">mainClass</td>
    <td valign="top">name of main class for executables</td>
    <td valign="top">&quot;com.example.project.entrypoint&quot;</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">&quot;true&quot; or &quot;false&quot;(default)</td>
    </tr>
<tr>
    <td valign="top">optimize</td>
    <td valign="top">optimisation flag</td>
    <td valign="top">&quot;true&quot; or &quot;false&quot;(default)</td>
    </tr>
<tr>
    <td valign="top">references</td>
    <td valign="top">Semicolon separated list of dlls to refer to</td>
    <td valign="top">&quot;mylib.dll;nunit.dll&quot;</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">&quot;.&quot;</td>
    </tr>
<tr>
    <td valign="top">targetType</td>
    <td valign="top">Type of target</td>
    <td valign="top">&quot;exe&quot;, &quot;module&quot;, &quot;winexe&quot; or &quot;library&quot;</td>
    </tr>
<tr>
    <td valign="top">unsafe</td>
    <td valign="top">enable the <b>unsafe</b> keyword</td>
    <td valign="top">&quot;true&quot; or &quot;false&quot;(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">&quot;true&quot; or &quot;false&quot;(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">&quot;1&quot;-&quot;4&quot;</td>
    </tr>
<tr>
    <td valign="top">win32Icon</td>
    <td valign="top">filename of icon to include</td>
    <td valign="top">&quot;res/myicon.ico&quot;</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">&quot;res/myapp.res&quot;</td>
   </tr>

</table>
<p>
Example
</p>
<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;
        destFile=&quot;NetApp.exe&quot;
        /&gt;   
</pre>
<hr>
<h2>&lt;VBC&gt;</h2>

This task compiles VisualBasic.NET source into executables or modules.

This task compiles VisualBasic.NET source into executables or modules. 
The task will only work on win2K/XP or other platforms with vbc.exe 
or an equivalent. VBC must be on the execute path.

<p>
All parameters are optional: &lt;vbc/&gt; should suffice to produce a debug
build of all *.vb 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=&quot;**/*.vb&quot;</b> and 
<b>excludes=&quot;broken.vb&quot;</b> can be used to control 
the files pulled in. By default, 
all *.vb files from the project folder down are included in the command. 
When this happens the destFile -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>'destfile'</b> seems prudent. </p>
<p>
Also, dependency checking only works if destfile is set.

<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">&quot;true&quot;(default) or &quot;false&quot;</td>
    </tr>
<tr>
    <td valign="top">definitions</td>
    <td valign="top">defined constants</td>
    <td valign="top"> &quot;RELEASE;BETA1&quot;</td>
    </tr>
<tr>
    <td valign="top">debug</td>
    <td valign="top">include debug information</td>
    <td valign="top">&quot;true&quot;(default)</td>
    </tr>

<tr>
    <td valign="top">destFile</td>
    <td valign="top">name of exe/library to create</td>
    <td valign="top">&quot;example.exe&quot;</td>
    </tr>
  <tr>
    <td valign="top">excludes</td>
    <td valign="top">comma- or space-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 VisualBasicCompile task </td>
    <td>&quot;/warnaserror+ /baseaddress:0x12840000&quot;</td>
  </tr>

  <tr>
    <td valign="top">failOnError</td>
    <td valign="top">Should a failed compile halt the build?</td>
    <td valign="top">&quot;true&quot;(default) or &quot;false&quot;</td>
  </tr>
  <tr>
    <td valign="top">imports</td>
    <td valign="top">comma-separated list of global imports for namespaces
	   in referenced metadata files.</td>
  </tr>
  <tr>
    <td valign="top">includes</td>
    <td valign="top">comma- or space-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">mainClass</td>
    <td valign="top">name of main class for executables</td>
    <td valign="top">&quot;com.example.project.entrypoint&quot;</td>
    </tr>
<tr>
    <td valign="top">optimize</td>
    <td valign="top">optimisation flag</td>
    <td valign="top">&quot;true&quot; or &quot;false&quot;(default)</td>
    </tr>
<tr>
    <td valign="top">optionCompare</td>
    <td valign="top">Text or binary string comparisons.</td>
    <td valign="top">&quot;text&quot; or &quot;binary&quot;(default)</td>
    </tr>
<tr>
    <td valign="top">optionExplicit</td>
    <td valign="top">Require explicit declaration of variables?</td>
    <td valign="top">&quot;true&quot; or &quot;false&quot;(default)</td>
    </tr>
<tr>
    <td valign="top">optionStrict</td>
    <td valign="top">Enforce strict language semantics?</td>
    <td valign="top">&quot;true&quot; or &quot;false&quot;(default)</td>
    </tr>
<tr>
    <td valign="top">references</td>
    <td valign="top">Semicolon separated list of dlls to refer to</td>
    <td valign="top">&quot;mylib.dll;nunit.dll&quot;</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">removeIntChecks</td>
    <td valign="top">Remove integer checks?</td>
    <td valign="top">&quot;true&quot; or &quot;false&quot;(default)</td>
    </tr>
<tr>
    <td valign="top">rootNamespace</td>
    <td valign="top">Root namespace for all type declarations.</td>
    <td valign="top">com.example</td>
    </tr>
    
<tr>
    <td valign="top">srcDir</td>
    <td valign="top">source directory (default = project directory)</td>
    <td valign="top">&quot;.&quot;</td>
    </tr>
<tr>
    <td valign="top">targetType</td>
    <td valign="top">Type of target</td>
    <td valign="top">&quot;exe&quot;, &quot;module&quot;, &quot;winexe&quot; or &quot;library&quot;</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">&quot;true&quot; or &quot;false&quot;(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">&quot;1&quot;-&quot;4&quot;</td>
    </tr>
<tr>
    <td valign="top">win32Icon</td>
    <td valign="top">filename of icon to include</td>
    <td valign="top">&quot;res/myicon.ico&quot;</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">&quot;res/myapp.res&quot;</td>
   </tr>

</table>
<p>
Example
</p>
<pre>&lt;vbc
        optimize=&quot;true&quot;
        debug=&quot;false&quot;
        warnLevel=&quot;4&quot;
        targetType=&quot;exe&quot;
        definitions=&quot;RELEASE&quot;
        excludes=&quot;src/unicode_class.vb&quot;
        mainClass = &quot;MainApp&quot;
        destFile=&quot;NetApp.exe&quot;
        optionExplicit=&quot;true&quot;
        optionCompare=&quot;text&quot;
        /&gt;   
</pre>
<hr>
<h2>&lt;ilasm&gt;</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: &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>

<p>

The task is a directory based task, so attributes like <b>includes=&quot;*.il&quot;</b> and 
<b>excludes=&quot;broken.il&quot;</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
      (&quot;yes&quot;/&quot;no&quot;). 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">&quot;true&quot;(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">&quot;true&quot;(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">&quot;on&quot;, &quot;off&quot; (default)</td>
    </tr>
<tr>
    <td valign="top">outputFile</td>
    <td valign="top">filename of output</td>
    <td valign="top">&quot;example.exe&quot;</td>
    </tr>
<tr>
    <td valign="top">resourceFile</td>
    <td valign="top">name of resource file to include</td>
    <td valign="top">&quot;resources.res&quot;</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">&quot;exe&quot;(default), &quot;library&quot;</td>
    </tr>
<tr>
    <td valign="top">verbose</td>
    <td valign="top">output progress messages</td>
    <td valign="top">&quot;on&quot;, &quot;off&quot; (default)</td>
    </tr>

</table>
<p>
Example</p>
<pre>&lt;ilasm
        outputFile=&quot;app.exe&quot;
        verbose=&quot;on&quot;
        listing=&quot;on&quot;
        owner=&quot;secret&quot;
        /&gt;
</pre>
<h2>&lt;WsdlToDotnet&gt;</h2>
Why add a wrapper to the MS WSDL tool? 
So that you can verify that your web services, be they written with Axis or
anyone else's SOAP toolkit, work with .NET clients.
<p>
This task is dependency aware when using a file as a source and destination;
so if you &lt;get&gt; the file (with <code>usetimestamp="true"</code>) then
you only rebuild stuff when the WSDL file is changed. Of course,
if the server generates a new timestamp every time you ask for the WSDL,
this is not enough...use the &lt;filesmatch&gt; &lt;condition&gt; to
to byte for byte comparison against a cached WSDL file then make
the target conditional on that test failing.   
 
<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">destFile</td>
    <td valign="top">name of file to generate. Required</td>
    <td valign="top">ApacheNet.cs</td>
  </tr> 
  <tr>
    <td valign="top">srcFile</td>
    <td valign="top">name of WSDL file to use. 
      Required if url is not set</td>
    <td valign="top">service.wsdl</td>
  </tr>
   <tr>
    <td valign="top">url</td>
    <td valign="top">url to retrive WSDL from.
    required if srcFile is unset</td>
    <td valign="top">http://localhost/service?wsdl</td>
  </tr>  
  <tr>
    <td valign="top">server</td>
    <td valign="top">generate server stubs, not client proxy code.
      optional; default false</td>
    <td valign="top">"false"(default)</td>
  </tr> 
  <tr>
    <td valign="top">namespace</td>
    <td valign="top">namespace to place  the source in.
      optional; default ""</td>
    <td valign="top">Apache.Net</td>
  </tr> 
  <tr>
    <td valign="top">language</td>
    <td valign="top">language; one of "CS", "JS", or "VB"
      optional; </td>
    <td valign="top"> "CS" (default)</td>
  </tr> 
  <tr>
    <td valign="top">failOnError</td>
    <td valign="top">Should failure halt the build?</td>
    <td valign="top">"true"(default)</td>
  </tr>
  <tr>
    <td valign="top">extraOptions</td>
    <td valign="top">Any extra options which aren't explicitly 
        supported by the task, like all the proxy server config stuff</td>
    <td></td>
  </tr>  
 
  </table>
<hr>

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

<h4>Version 0.5</h4>
This revision goes along with NET 1.0 (SP1) 
<ol>
<li>CSC: added filealign</li>
<li>CSC: added reference to office.dll</li>
<li>CSC: dependency checking! only if destFile is set!
<li>WsdlToDotnet written
</ol>

<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>
<li>CSC: added win32res , noConfig, utf8output, fullpaths</li>
<li>CSC: </li>
</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. 


<p align="center">Copyright &copy; 2000-2003 Apache Software Foundation. All rights
Reserved.</p>

</body>
</html>