From 3c5b1c8a70e6b694f0e6a43f02656496bd899fb2 Mon Sep 17 00:00:00 2001 From: Steve Loughran Date: Thu, 11 Apr 2002 07:28:12 +0000 Subject: [PATCH] documentation of new task + cleanup of the rest git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@272361 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/OptionalTasks/dotnet.html | 362 ++++++++++++-------------- 1 file changed, 166 insertions(+), 196 deletions(-) diff --git a/docs/manual/OptionalTasks/dotnet.html b/docs/manual/OptionalTasks/dotnet.html index 27bb0845a..2570f7bc1 100644 --- a/docs/manual/OptionalTasks/dotnet.html +++ b/docs/manual/OptionalTasks/dotnet.html @@ -3,188 +3,19 @@ .NET Tasks - -

.NET classes for Ant

+ +

.NET tasks

-

Vision

-

-Make ant the definitive build tool for .NET projects, just -as it is becoming for java projects -

- -

Detail

- -

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

- -

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

- -

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

- -

Key .net Tasks

- -
    -
  1. csc - csharp compiler - *.csc -> output
    2. -
  2. ilasm - IL assembler - *.il ->.exe or .dll
    3. -
  3. ResX - ResXToResources.exe .resx -> .resources
    4. -
  4. al - assembly linker (.dll) ->
    5. -
  5. Signcode - .exe + keys -> .exe
    6. -
  6. Resgen - .properties -> .resources
    7. -
  7. Type Library Exporter (TlbExp.exe) .dll -> .tlb
    8. -
  8. TlbImp.exe Type Library Importer
    9. -
  9. RegAsm.exe Assembly Registration Tool .dll -> .reg | registration
    10. -
- -

Ant Wrapper for net tasks

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

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

- -

Plan

-
    - -
  1. code up C sharp task and distribute for feedback & identify possible -aid
    2. -
  2. Use for a real end to end development task
    3. -
  3. Add the next task I need (whatever that is)
    4. -
  4. Refactor to produce a base class for .net tasks
    5. -
  5. Leave it other people write all the other tasks
    6. -
- -

Risks

-
-

Using Ant in .net projects

- -To use the net tasks one needs - - -
-

Change Log

- -

Version 0.5

-This revision goes along with NET 1.0 (SP1) -
    -
  1. CSC: added filealign
    2. -
  2. CSC: added reference to office.dll
    3. -
- -

Version 0.4

-This is the beta-2 revision of the tasks. -
    -
  1. ILASM: pulled the owner attribute, added keyfile for giving binaries a strong name -(MD5 hash of the checksum)
    2. -
  2. CSC: added win32res , noConfig, utf8output, fullpaths
    3. -
  3. CSC:
    4. -
- -

Version 0.3

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

-External changes

- - -Internal changes - - -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) - -

Version 0.2

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

Version 0.1

-Initial proof of concept; very rudimentary support for CSC only. - -
-

Task: CSC

+

<CSC>

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

All parameters are optional: <csc/> should suffice to produce a debug @@ -193,13 +24,16 @@ enumeration, so are one of the first attributes to consider adding.

-The task is a directory based task, so attributes like includes="**/*.cs" and -excludes="broken.cs" can be used to control the files pulled in. By default, +The task is a directory based task, so attributes like +includes="**/*.cs" and +excludes="broken.cs" 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- +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 'outfile' seems prudent.

- +Specifying the output file with 'destfile' seems prudent.

+

+Also, dependency checking only works if destfile is set. @@ -226,9 +60,14 @@ Specifying the output file with 'outfile' seems prudent.

- + + + + + + @@ -313,11 +152,6 @@ Specifying the output file with 'outfile' seems prudent.

- - - - - @@ -383,11 +217,11 @@ Example definitions="RELEASE" excludes="src/unicode_class.cs" mainClass = "MainApp" - outputFile="NetApp.exe" + destFile="NetApp.exe" />
-

Task: ilasm

+

<ilasm>

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. @@ -429,7 +263,7 @@ manually specified with outfile

- + @@ -449,16 +283,16 @@ manually specified with outfile - - - - - - + + + + + + - +
debug include debug information"true"(default) or "false""true"(default)
destFilename of exe/library to create"example.exe"
docFile name of file for documentation optimisation flag "true" or "false"(default)
outputFilefilename of output"example.exe"
references Semicolon separated list of dlls to refer to debug include debug information true (default)
excludes
failOnErrorShould a failed compile halt the build?"true"(default)
failOnErrorShould a failed compile halt the build?"true"(default)
fullpaths Should error text provide the full path to files "true"(default)
includes comma separated list of patterns of files that must be @@ -517,7 +351,143 @@ Example

owner="secret" /> +

<WsdlToDotnet>

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

+This task is dependency aware when using a file as a source and destination; +so if you <get> the file (with usetimestamp="true") 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 <filesmatch> <condition> to +to byte for byte comparison against a cached WSDL file then make +the target conditional on that test failing. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionExample
destFilename of file to generate. RequiredApacheNet.cs
srcFilename of WSDL file to use. + Required if url is not setservice.wsdl
urlurl to retrive WSDL from. + required if srcFile is unsethttp://localhost/service?wsdl
servergenerate server stubs, not client proxy code. + optional; default false"false"(default)
namespacenamespace to place the source in. + optional; default ""Apache.Net
languagelanguage; one of "CS", "JS", or "VB" + optional; "CS" (default)
failOnErrorShould failure halt the build?"true"(default)
extraOptionsAny extra options which aren't explicitly + supported by the task, like all the proxy server config stuff

+ +
+

Change Log

+ +

Version 0.5

+This revision goes along with NET 1.0 (SP1) +
    +
  1. CSC: added filealign
    2. +
  2. CSC: added reference to office.dll
    3. +
  3. CSC: dependency checking! only if destFile is set! +
  4. WsdlToDotnet written +
+ +

Version 0.4

+This is the beta-2 revision of the tasks. +
    +
  1. ILASM: pulled the owner attribute, added keyfile for giving binaries a strong name +(MD5 hash of the checksum)
    2. +
  2. CSC: added win32res , noConfig, utf8output, fullpaths
    3. +
  3. CSC:
    4. +
+ +

Version 0.3

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

+External changes

+
    +
  • Recursive inclusion of .cs and .il files
    • + +
  • Documentation enhanced, includes examples and details of all parameters
    • + +
  • 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.
    • + +
  • References can also be referred to using the ReferenceFiles parameter, which +is an ant path specification. The old 'references' string is still retained.
    • +
  • An 'extraoptions' attribute enables the build file to include any CSC options +which are not explicitly supported in the CSC task.
    • +
+ +Internal changes +
    +
  • Some minor refactoring (move common code a method)
    • +
  • 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.
    • +
  • Removed throws clause from methods which can't throw exceptions
    • +
+ +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) + +

Version 0.2

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

Version 0.1

+Initial proof of concept; very rudimentary support for CSC only. + +

Copyright © 2000-2002 Apache Software Foundation. All rights Reserved.