mathnet-numerics/build/MSBuild.Community.Tasks.v1.2.0.306/DevelopersGuide.txt

$Id: DevelopersGuide.txt 279 2006-12-11 22:43:40Z iko $

Developer's Guide for http://msbuildtasks.tigris.org/
=====================================================

Build Environment Prerequisites
------------------------------

- .NET2.0

- MSBuild; typically already installed as part of .NET2.0,
  for example in C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\MSBuild.exe

- NUnit 2.2.X (http://www.nunit.org/);
  necessary to run the tests

- Microsoft Visual SourceSafe(R) 2005;
  the library Microsoft.VisualStudio.SourceSafe.Interop gets referenced
  
- NDoc 1.3 (http://ndoc.sourceforge.net/)
  additionally configure NDoc to use .NET2; see
  http://ndoc.sourceforge.net/wiki/dotNet_2.0_Support
  
- Microsoft Visual Studio 2005 as IDE

Optional Services
-----------------

- Subversion client (http://subversion.tigris.org/);
  typically in C:\Program Files\Subversion

- IIS

- Email

- ILMerge (http://research.microsoft.com/~mbarnett/ILMerge.aspx)

- FxCop (http://www.gotdotnet.com/Team/FxCop/)


Before writing your own task
----------------------------

1.  Checkout/Update the svn repository
    http://msbuildtasks.tigris.org/svn/msbuildtasks/trunk
    with your tigris user/password
    to a local working copy <msbuildtasks> of your choice.

2.  Check that you can build the project on the command line:
	** Important ** You must run the build from the command line before attempting to
	open the Visual Studio solution file, in order to create some required files.

    - Add the directory of MSBuild.exe to your PATH environment variable, e.g.
      C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727.

    - Open cmd.exe in the top directory of the local working copy
      where MSBuildTasks.proj is located.

    - Run "msbuild MSBuildTasks.proj";
      the default target "build" is executed
      and should yield "Build succeeded".

    - Run "msbuild MSBuildTasks.proj /p:devel=true /p:nunitpath=c:\tools\nunit\bin /t:test" to run the NUnit test suite;
      "Build succeeded." indicates that the tests have been executed successfully.
      /p:devel=true is necessary when you want to work with 
      the assemblies of your own build, for example because
      you did not run the installer of MSBuildCommunityTasks yet.
      /p:nunitpath must point to the bin folder of your local installation of NUnit 2.2.x

    - Open <msbuildtasks>\Debug\test\TestReport.html
      and check the test results.
      Tests must be either successful
      or ignored because an optional service
      such as FTP server or Email server is missing
      on your machine.

3.  Check that you can build the project in VS2005:

    - Open <msbuildtasks>\Source\MSBuild.Community.Tasks.sln.

    - Set MSBuild.Community.Tasks.Tests as startup project.

    - Open the properties of MSBuild.Community.Tasks.Tests;
      in Debug/Start Action, set the external program to NUnit,
      e.g. "C:\Program Files\NUnit 2.2.5\bin\nunit-gui.exe";
      in Debug/Start Options, set command line arguments to
      "MSBuild.Community.Tasks.Tests.dll".

    - If you work with another version of NUnit,
      it may be necessary to the NUnit library
      from your NUnit's installation folder to
      <msbuildtasks>\Libaries\NUnit\<version>\nunit.framework.dll
      and to re-import it to the test project.

    - Run the project in debugging mode (F5);
      NUnit starts up with the test suite;
      Tests can be executed in interaction 
      with the debugger (breakpoints etc.)


Writing your own task
----------------------

1.  Add a folder
    <msbuildtasks>\Source\MSBuild.Community.Task\<MyTask>
    and place <MyTask>.cs and related files in there;
    always add a folder, even if you want to add just one file.

2.  Add third party libraries that you are allowed to redistribute to
    <msbuildtasks>\Libraries\<ThirdParyTool>\<ReleaseNumber>\
    (e.g. <msbuildtasks>\Libraries\NUnit\2.2.5\nunit.framework.dll).
   
3.  For third party libraries that you are not allowed to redistribute,
    add an entry in the prerequisits section of this document
    together with information where to get it.

4.  Implement your task

	- Insert the character sequence '$', 'Id', '$'
	  (not concatenated here to avoid expansion by svn in this text itself)
	  somewhere in the fileheader comment.

	- When adding source files to the repository, set the metadata "svn:keywords" to "Id".
	  
	  From the command line: svn ps svn:keywords "Id" myNewTask.cs
	  
	  With TortoiseSVN: Right-click the myNewTask.cs in Explorer, choose Properties, change
	  to Subversion tab, choose svn-keywords from dropdown in Properties section, 
	  enter "Id" in the text box, and press the Set button.

	- Avoid Console.WriteLine, use Log.LogMessage instead.
	
    - For log messages in your task,
      use resource strings instead of hard coded strings,
      e.g. "Log.LogError(Properties.Resources.XsltNoInputFiles);".
      
    - Recommended Tab width is 4.

5.  For your NUnit tests, add a folder
    <msbuildtasks>\Source\MSBuild.Community.Task.Test\<MyTask>
    and place <MyTask>Test.cs, <MyTask>Test.proj and related files in there;
    always add a folder, even if you want to add just one file.

6.  Implement NUnit tests for your task in <MyTask>Test.cs;
    this is important to have something for debugging.
    
    - Provide a description to every test, e.g.
      [Test(Description = "Test the weather forecast task in rainy season")].
   
    - From within your NUnit test,
      check for the availability of an optional service
      that your task depends on (such as FTP, IIS, Email);
      when not available, it's good style to
      Assert.Ignore("<MyTask> test needs <FancyService> to be executed")
      instead of having the test just fail.
      
    - Also for optional services that a test depends on,
      it's good style to have server access data
      such as URLs, logins and paths
      located in a config file
      rather than hard coded in the test code.

7.  Add an entry to 
    <msbuildtasks>\Source\MSBuild.Community.Tasks\MSBuild.Community.Tasks.Targets
    
8.  Implement <MyTask>Test.proj
    and add an entry in MSBuildTasks.proj so that it gets executed
    as part of the "test-proj" target there;
    this is important to test and demonstrate your task in action.
   
    - It's good style to have tests work only below
      <msbuildtasks>\Build\<Configuration>\test\<TestSuite>\
      and to avoid having them creating any folders or files 
      in the source tree below
      <msbuildtasks>\Source\
      
    - If your test depend on an optional service or tool,
      it's good style to have the test skipped by default
      and to provide an extra switch like "/p:withILMerge=true"
      to execute the test.
   
9.  Test your task

    - Run NUnit test interactively.

    - Run NUnit test on the command line.

    - Run "msbuild MSBuildTasks.proj /p:devel=true /p:nunitpath=c:\tools\nunit\bin /t:test", 
      which should include calling <MyTask>Test.proj

10. Document your task

    - Provide all xml code comments for your task
      (no need to do so for private members and for NUnit test code).

    - Provide an <example> section in the xml code comment
      of your task class.

    - Make an entry for your task in 
      <msbuildtasks>\Documentation\Overview.html
      
11. Before commiting your task,
    - run "msbuild MSBuildTasks.proj /p:configuration=Release",
      which treats warnings as errors.
     
    - run "msbuild Master.proj" to validate the nightly build
      still works. You can also verify the documentation for your task
      was included correctly in Documentation\MSBuild.Community.Tasks.chm