treesurgeon Wiki & Documentation Rss Feed

Updated Wiki: About

bsimser — Thu, 31 May 2012 12:31:39 GMT

About

Open Source
Tree Surgeon is an open source project. This means you are free to use it, and the source code is available to look at.

Tree Surgeon is released under the MIT License. Please make sure to read the License before using or distributing the software.

Project Team
Check out the team here.

Copyright
Copyright © 2007 - 2012 Bil Simser
Copyright © 2005 - 2006 Mike Roberts & ThoughtWorks

Updated Wiki: Documentation

bsimser — Thu, 31 May 2012 12:30:15 GMT

Using Tree Surgeon

Tree Surgeon is pretty simple, but it is fully functional. Its based on Mike Roberts's series of articles on How to setup a .NET Development Tree (see links below).

Download the installer, and just run the GUI. Your generated project will appear in your My Documents folder and you should move it to wherever you like to develop on your machine (the meta-root if you read the article above.)

Your generated project has a Visual Studio solution waiting for you in the src folder. Also, if you go into the project root directory, you can run an automated build. It should look a bit like this:

C:\Program Files\TreeSurgeon\MyNewProject>go
NAnt 0.85 (Build 0.85.1793.0; rc1; 28/11/2004)
Copyright (C) 2001-2004 Gerry Shaw
http://nant.sourceforge.net

Buildfile: file:///C:/Program Files/TreeSurgeon/MyNewProject/MyNewProject.build
Target(s) specified: test

compile:

 [solution] Starting solution build.
 [solution] Building 'MyNewProjectConsole' [AutomatedDebug] ...
 [solution] Building 'Core' [AutomatedDebug] ...
 [solution] Building 'UnitTests' [AutomatedDebug] ...

run-unit-tests:

    [mkdir] Creating directory 'C:\Program Files\TreeSurgeon\MyNewProject\build\test-reports'.
     [exec] NUnit version 2.2.2
     [exec] Copyright (C) 2002-2003 James W. Newkirk, Michael C. Two, Alexei A. Vorontsov, Charlie Poole.
     [exec] Copyright (C) 2000-2003 Philip Craig.
     [exec] All Rights Reserved.
     [exec]
     [exec] OS Version: Microsoft Windows NT 5.1.2600.0    .NET Version: 1.1.4322.2032
     [exec]
     [exec] .
     [exec] Tests run: 1, Failures: 0, Not run: 0, Time: 0.060 seconds
     [exec]
     [exec]

test:

BUILD SUCCEEDED

Total time: 4.4 seconds.

Creating a .NET Development Tree Blog Series

This is the series of blog posts created by Mike Roberts that started Tree Surgeon.

Introduction
Building the Development Tree
Adding Files to the Tree
Checking into Source Control
Automating the Build
Extending the Build
Adding Unit Tests
Automating Unit Tests and Packaging

Updated Wiki: Documentation

bsimser — Thu, 31 May 2012 12:29:56 GMT

Using Tree Surgeon

C:\Program Files\TreeSurgeon\MyNewProject>go
NAnt 0.85 (Build 0.85.1793.0; rc1; 28/11/2004)
Copyright (C) 2001-2004 Gerry Shaw
http://nant.sourceforge.net

Buildfile: file:///C:/Program Files/TreeSurgeon/MyNewProject/MyNewProject.build
Target(s) specified: test

compile:

 [solution] Starting solution build.
 [solution] Building 'MyNewProjectConsole' [AutomatedDebug] ...
 [solution] Building 'Core' [AutomatedDebug] ...
 [solution] Building 'UnitTests' [AutomatedDebug] ...

run-unit-tests:

    [mkdir] Creating directory 'C:\Program Files\TreeSurgeon\MyNewProject\build\test-reports'.
     [exec] NUnit version 2.2.2
     [exec] Copyright (C) 2002-2003 James W. Newkirk, Michael C. Two, Alexei A. Vorontsov, Charlie Poole.
     [exec] Copyright (C) 2000-2003 Philip Craig.
     [exec] All Rights Reserved.
     [exec]
     [exec] OS Version: Microsoft Windows NT 5.1.2600.0    .NET Version: 1.1.4322.2032
     [exec]
     [exec] .
     [exec] Tests run: 1, Failures: 0, Not run: 0, Time: 0.060 seconds
     [exec]
     [exec]

test:

BUILD SUCCEEDED

Total time: 4.4 seconds.

Creating a .NET Development Tree Blog Series

Updated Wiki: Home

bsimser — Thu, 31 May 2012 12:28:59 GMT

Welcome to the Tree Surgeon Project

Have you ever spent a few days setting up a new development tree? Have you ever spent several days setting up several development trees? Have you even spent weeks trying to perfect all your development trees using a set of best practices?

If the answer to any of the above answers is 'yes', then you'll like Tree Surgeon!

Tree Surgeon is a .NET development tree generator. Just give it the name of your project, and it will set up a development tree for you in seconds. More than that, your new tree has years worth of accumulated build engineering experience built right in.

Give Tree Surgeon a spin today!

More Information

Download
Acknowledgments
About
Support
License
Development

Updated Wiki: Documentation

bsimser — Thu, 31 May 2012 12:28:26 GMT

Creating a .NET Development Tree Blog Series

Updated Wiki: Documentation

bsimser — Thu, 31 May 2012 12:27:52 GMT

Creating a .NET Development Tree Blog Series

Updated Wiki: Documentation

bsimser — Thu, 31 May 2012 12:27:06 GMT

Creating a .NET Development Tree Blog Series

This is the series of blog posts created by Mike Roberts that started Tree Surgeon.

Introduction
Building the Development Tree
Adding Files to the Tree
Checking into Source Control
Automating the Build
DevelopmentTreePart5
DevelopmentTreePart6
DevelopmentTreePart7

Updated Wiki: Documentation

bsimser — Thu, 31 May 2012 12:26:20 GMT

Creating a .NET Development Tree Blog Series

This is the series of blog posts created by Mike Roberts that started Tree Surgeon.

Introduction
Building the Development Tree
Adding Files to the Tree
DevelopmentTreePart3
DevelopmentTreePart4
DevelopmentTreePart5
DevelopmentTreePart6
DevelopmentTreePart7

Updated Wiki: Documentation

bsimser — Thu, 31 May 2012 12:25:40 GMT

Creating a .NET Development Tree Blog Series

This is the series of blog posts created by Mike Roberts that started Tree Surgeon.

Introduction
Building the Development Tree
DevelopmentTreePart2
DevelopmentTreePart3
DevelopmentTreePart4
DevelopmentTreePart5
DevelopmentTreePart6
DevelopmentTreePart7

Updated Wiki: Documentation

bsimser — Thu, 31 May 2012 12:25:17 GMT

Creating a .NET Development Tree Blog Series

This is the series of blog posts created by Mike Roberts that started Tree Surgeon.

Introduction
DevelopmentTreePart1
DevelopmentTreePart2
DevelopmentTreePart3
DevelopmentTreePart4
DevelopmentTreePart5
DevelopmentTreePart6
DevelopmentTreePart7

Updated Wiki: Documentation

bsimser — Thu, 31 May 2012 12:24:56 GMT

Creating a .NET Development Tree Blog Series

This is the series of blog posts created by Mike Roberts that started Tree Surgeon.

DevelopmentTreeIntroduction
DevelopmentTreePart1
DevelopmentTreePart2
DevelopmentTreePart3
DevelopmentTreePart4
DevelopmentTreePart5
DevelopmentTreePart6
DevelopmentTreePart7

Updated Wiki: Documentation

bsimser — Thu, 31 May 2012 12:24:27 GMT

Creating a .NET Development Tree Blog Series

Updated Wiki: Home

bsimser — Thu, 31 May 2012 12:24:04 GMT

Welcome to the Tree Surgeon Project

Using Tree Surgeon

Tree Surgeon is available to Download. Its pretty simple, but it is fully functional. Its based on Mike Roberts's series of articles on How to setup a .NET Development Tree .

Download the installer, and just run the GUI. Your generated project will appear in your My Documents folder and you should move it to wherever you like to develop on your machine (the meta-root if you read the article above.)

Your generated project has a Visual Studio solution waiting for you in the src folder. Also, if you go into the project root directory, you can run an automated build. It should look a bit like:

C:\Program Files\TreeSurgeon\MyNewProject>go
NAnt 0.85 (Build 0.85.1793.0; rc1; 28/11/2004)
Copyright (C) 2001-2004 Gerry Shaw
http://nant.sourceforge.net

Buildfile: file:///C:/Program Files/TreeSurgeon/MyNewProject/MyNewProject.build
Target(s) specified: test

compile:

 [solution] Starting solution build.
 [solution] Building 'MyNewProjectConsole' [AutomatedDebug] ...
 [solution] Building 'Core' [AutomatedDebug] ...
 [solution] Building 'UnitTests' [AutomatedDebug] ...

run-unit-tests:

    [mkdir] Creating directory 'C:\Program Files\TreeSurgeon\MyNewProject\build\test-reports'.
     [exec] NUnit version 2.2.2
     [exec] Copyright (C) 2002-2003 James W. Newkirk, Michael C. Two, Alexei A. Vorontsov, Charlie Poole.
     [exec] Copyright (C) 2000-2003 Philip Craig.
     [exec] All Rights Reserved.
     [exec]
     [exec] OS Version: Microsoft Windows NT 5.1.2600.0    .NET Version: 1.1.4322.2032
     [exec]
     [exec] .
     [exec] Tests run: 1, Failures: 0, Not run: 0, Time: 0.060 seconds
     [exec]
     [exec]

test:

BUILD SUCCEEDED

Total time: 4.4 seconds.

More Information

Download
Acknowledgments
About
Support
License
Development

Updated Wiki: Documentation

bsimser — Thu, 31 May 2012 12:23:38 GMT

Links

Updated Wiki: Development

bsimser — Wed, 31 Dec 2008 18:00:26 GMT

Development

Source Control
Tree Surgeon uses Team Foundation Server on CodePlex to manage it's codebase. You can access the repository (preferred) using any Subversion client. The SVN address for the project is https://treesurgeon.svn.codeplex.com/svn.

Issue Tracking
Issue Tracking is done using CodePlex here.

Version Naming

Released Versions

Released versions have the following numbering:

Major.minor.revision.buildnumber, where

We plan on updating Major versions only on a major milestone in the project.
We update minor versions when there is a significant improvement in the application, or a breaking change in configuration since the previous release. When updating the minor version number, we reset the revision to zero.
We use revision numbers of more than 0 when we do not want to update the minor version number, but do want to make a new release. This may be due to some bugfixes, minor updates, etc. We never just increase the revision number if there has been a breaking change
buildnumber is the Continuous Integration build number. We never reset this. A buildnumber of 0 implies a build that was produced outside of our Continuous Integration environment

Our Continuous Integration process creates a build label that includes the Major.minor.revision part. We update this as late as possible before a release, or release candidate, for a new release version.

Unreleased versions

Unreleased versions have the following names:

Next - The next release, where the final release name has not yet been set
Soon - Issues that we hope to resolve soon
Eventually - Issues that we hope to resolve at some point in the future, but after the next major release

All unresolved issues should be assigned to one of these versions by a project administrator. Issues should only be moved to Next if they have been resolved since the last release, or are an unresolved blocker for the next release.

Coding Standards

Coding standards on the project, should you decide to contribute to it, are pretty light (and open to negotiation and discussion):

All code has unit test coverage
private class fields using _ prefix with camelCase
properties are PascalCased
public methods are PascalCased
private/protected methods are preferred to be camelCased but are acceptable as PascalCased
Order of members in a class: fields, constructors, everything else
Use interfaces to define contracts
do not use regions

Use tabs, not spaces in your patches - Some folks like 2 spaces, some like 4, but that's an IDE setting. Change your IDE settings to use tabs, not spaces, and then you can set your tab to 2 spaces if you prefer that. Here is a quick macro to flip between tabs and spaces in Visual Studio: http://abombss.com/blog/2007/12/12/toggle-between-tabs-spaces-with-ease/

Patches

To contribute new features to this project please follow these steps:

Download the source code from the source code repository. You can check it out with TortoiseSVN here: https://treesurgeon.svn.codeplex.com/svn
Add your feature.
Create a subversion patch for your code from the root directory using the instructions found here.
Submit the patch to the patch upload page. Go to http://www.codeplex.com/treesurgeon/SourceControl/UploadPatch.aspx and upload the patch file.
Update the issue (story) you were working on with a note that you've uploaded a patch
Subscribe to the patch rss feed so that you know when a Committer adds comments to your submission.
The project coordinators will evaluate and apply your patch
If a committer makes some suggestions please take these at face value and help us keep a solid codebase.

Updated Wiki: Development

bsimser — Wed, 31 Dec 2008 17:58:58 GMT

Development

We plan on updating Major versions only on a major milestone in the project.
We update minor versions when there is a significant improvement in the application, or a breaking change in configuration since the previous release. When updating the minor version number, we reset the revision to zero.
We use revision numbers of more than 0 when we do not want to update the minor version number, but do want to make a new release. This may be due to some bugfixes, minor updates, etc. We never just increase the revision number if there has been a breaking change
buildnumber is the Continuous Integration build number. We never reset this. A buildnumber of 0 implies a build that was produced outside of our Continuous Integration environment

Next - The next release, where the final release name has not yet been set
Soon - Issues that we hope to resolve soon
Eventually - Issues that we hope to resolve at some point in the future, but after the next major release

All unresolved issues should be assigned to one of these versions by a project administrator. Issues should only be moved to Next if they have been resolved since the last release, or are an unresolved blocker for the next release.

Coding Standards

Coding standards on the project, should you decide to contribute to it, are pretty light (and open to negotiation and discussion):

All code has unit test coverage
private class fields using _ prefix with camelCase
properties are PascalCased
public methods are PascalCased
private/protected methods are preferred to be camelCased but are acceptable as PascalCased
Order of members in a class: fields, constructors, everything else
Use interfaces to define contracts
do not use regions

Use tabs, not spaces in your patches - Some folks like 2 spaces, some like 4, but that's an IDE setting. Change your IDE settings to use tabs, not spaces, and then you can set your tab to 2 spaces if you prefer that. Here is a quick macro to flip between tabs and spaces in Visual Studio: http://abombss.com/blog/2007/12/12/toggle-between-tabs-spaces-with-ease/

Patches

To contribute new features to this project please follow these steps:

Download the source code from the source code repository. You can check it out with TortoiseSVN here: https://treesurgeon.svn.codeplex.com/svn
Add your feature.
Create a subversion patch for your code from the root directory using the instructions found here.
Submit the patch to the patch upload page. Go to http://www.codeplex.com/treesurgeon/SourceControl/UploadPatch.aspx and upload the patch file.
Update the issue (story) you were working on with a note that you've uploaded a patch
Subscribe to the patch rss feed so that you know when a Committer adds comments to your submission.
The project coordinators will evaluate and apply your patch
If a committer makes some suggestions please take these at face value and help us keep a solid codebase.

UPDATED WIKI: Home

bsimser — Wed, 21 Nov 2007 22:53:33 GMT

Welcome to the Tree Surgeon Project

Using Tree Surgeon

C:\Program Files\TreeSurgeon\MyNewProject>go
NAnt 0.85 (Build 0.85.1793.0; rc1; 28/11/2004)
Copyright (C) 2001-2004 Gerry Shaw
http://nant.sourceforge.net
 
Buildfile: file:///C:/Program Files/TreeSurgeon/MyNewProject/MyNewProject.build
Target(s) specified: test
 
compile:
 
 [solution] Starting solution build.
 [solution] Building 'MyNewProjectConsole' [AutomatedDebug] ...
 [solution] Building 'Core' [AutomatedDebug] ...
 [solution] Building 'UnitTests' [AutomatedDebug] ...
 
run-unit-tests:
 
    [mkdir] Creating directory 'C:\Program Files\TreeSurgeon\MyNewProject\build\test-reports'.
     [exec] NUnit version 2.2.2
     [exec] Copyright (C) 2002-2003 James W. Newkirk, Michael C. Two, Alexei A. Vorontsov, Charlie Poole.
     [exec] Copyright (C) 2000-2003 Philip Craig.
     [exec] All Rights Reserved.
     [exec]
     [exec] OS Version: Microsoft Windows NT 5.1.2600.0    .NET Version: 1.1.4322.2032
     [exec]
     [exec] .
     [exec] Tests run: 1, Failures: 0, Not run: 0, Time: 0.060 seconds
     [exec]
     [exec]
 
test:
 
BUILD SUCCEEDED
 
Total time: 4.4 seconds.

More Information

Download
Acknowledgments
About
Support
License
Development

Original Creating a .NET Development Tree Blog Series

UPDATED WIKI: DevelopmentTreePart6

donnfelker — Sat, 02 Jun 2007 23:17:02 GMT

Part 6 - Adding Unit Tests

By now we have some source code checked in to our Source Control server. Its got a structured folder hierarchy and we're being careful about how we check specific files in (and ignore others). We're combining Visual Studio and NAnt to have a simple yet powerful automated build that works closely with the changes we make during interactive development.

So far though we only have 1 source file and shockingly no tests. We need to change this.

To do this we're going to create 2 new assemblies - one application DLL, and one DLL for unit tests. .NET won't allow you to use .exe assemblies as references for other projects, so a unit test DLL can only reference another DLL. Its slightly off-topic but because of this reason I try to keep my .exe projects as small as possible (because any classes in them can't be unit tested) and have nearly all code in a DLL.

So let's create our new Application DLL. I'm going to call it Core. Following the conventions we set down in part 2, the VS Project Folder is stored in src and we change the default namespace to SherwoodForest.Sycamore.Core. Before closing the Project Properties window though, there are 2 more things to change.

Firstly, for DLLs I like to use the naming convention that the Assembly has the same name as the default namespace. Also, following what we did in the previous part, create an 'AutomatedDebug' configuration, based on the 'Debug' Configuration, except with the output path of ..\..\build\Debug\Core. Make sure your Solution build configurations are all mapped correctly. We won't need the 'Class1' which VS automatically creates, so delete it.

We follow exactly the same procedure for our Unit Test DLL, giving the VS Project the (not particularly original, nevertheless informative) name of UnitTests. Save everything and make sure you can compile in Visual Studio and using your build script.

Before we write a test, we need to setup our project with NUnit. There's a few hoops to go through here but we only have to do it once for our project. Firstly, download NUnit - I'm going to be using NUnit 2.2.2 for this example. Download the binary zip file, not the MSI. While its downloading, open up your Global Assembly Cache (or GAC) - it will be in C:\Windows\Assembly, or something similar. Look to see if you have any NUnit assmblies in it. If you do, try to get rid of them by uninstalling any previous versions of NUnit from your computer.

Why are we worrying about not using the GAC and MSI's? Well, for pretty much exactly the reasons as we specified for NAnt, we want to use NUnit from our development tree . The problem is that if we have any NUnit assemblies in the GAC, they will take priority over the NUnit in our development tree. We could go through being explicit about the versions of NUnit each assembly requries, but that's a lot of hassle. Its easier just not to make NUnit a system wide tool, and this means getting it out of the GAC. (Mike Two, one of the NUnit authors, is probably going to shoot me for suggesting all of this. If you want to make NUnit a system tool then that will work too, you just have a few more hoops to jump through.)

By now your NUnit download should be complete. Extract it, take the bin folder and put in next to the nant folder in your project's tools folder. Rename it to nunit.

To create test fixtures in our UnitTests VS Project, we need to reference the nunit.framework assembly. This introduces a new concept - that of third party code dependencies. To implement these, I like to have a new toplevel folder in my project root called lib. Do this in your project and copy the nunit.framework.dll file from the NUnit distribution to the new folder. Once you've done that, add lib\nunit.framework.dll as a Reference to your UnitTests project.

Because of the previous step we now have the same file (nunit.framework.dll) copied twice in our development tree. Its worth doing this because we have a clear separation between code dependencies (in the lib folder) and build time tools (in the tools folder). We could delete the entire tools folder and the solution would still compile in Visual Studio. This is an example of making things clean and simple. It uses more disk space, but remember what we said back in Part 1 about that?

So finally we can actually write a test! For Sycamore, I'm going to add the following as a file called TreeRecogniserTest.cs to my UnitTests project:

using NUnit.Framework;
using SherwoodForest.Sycamore.Core;
namespace SherwoodForest.Sycamore.UnitTests
{
	[TestFixture]
	public class TreeRecogniserTest
	{
		[Test]
		public void ShouldRecogniseLarchAs1()
		{
			TreeRecogniser recogniser = new TreeRecogniser();
			Assert.AreEqual(1, recogniser.Recognise("Larch"));
		}
	}
}

To implement this, I add Core as a Project Reference to UnitTests and create a new class in Core called TreeRecogniser:

namespace SherwoodForest.Sycamore.Core
{
	public class TreeRecogniser
	{
		public int Recognise(string treeName)
		{
			if (treeName == "Larch")
			{
				return 1;
			}
			else
			{
				return 0;
			}
		}
	}
}

I can then run this test by using TestDriven.NET within the IDE, or by using the NUnit GUI and pointing it at src\UnitTests\bin\Debug\SherwoodForest.Sycamore.UnitTests.dll. The tests should pass in either case.

If we run our automated NAnt build, everything should compile OK, and you should be able to see each of the VS Projects compiling in their AutomatedDebug Build Configuration. The tests aren't run yet, but that's what we'll be looking at next time. Even so, we are still at a check-in point. We have 2 new project folders to add, but remember the exclusion rules (*.user, bin and obj). Being a Subversion command-line user, I like to use the the -N (non recursive) flag of svn add to make sure I can mark the svn:ignore property before all the temporary files get added.

Also, don't forget to check in tools\nunit or the new lib folder.

The current state of Sycamore is available here (link not available).

So let's wrap up this part then. We covered some new generic principles about projects and dependencies. We also looked at the specifics of using NUnit. Some concrete points to take away are:

Set DLL Names to be the same as the default namespace
Put your Unit Tests in a separate VS project called UnitTests
Save NUnit in your development tree in its own folder under tools
Put all DLLs your code depends on in a top level folder called lib. Theonly exceptions are system DLLs such as .NET Framework Libraries.

Next Section Unit Test Automation

UPDATED WIKI: DevelopmentTreePart5

donnfelker — Sat, 02 Jun 2007 23:16:09 GMT

Part 5 - Extending the Automated Build

In the last part we started using NAnt to automate a build for our project. In this part we'll add some more buildfunctionality.

When we added the compile target we used the <solution> task to compile our solution. However, we also specified which 'Build Configuration' to use. Build Configurations are a Visual Studio feature that allow you to build your project in different ways. The most common differences are between 'Debug' and 'Release' (2 configurations that Visual Studio always creates for you.) With a Debug build, the Visual Studio compiler is configured to create the .pdb files we use for ebugging (it gives us line numbers in exception stack traces, that kind of thing.) The 'Release' configuration doesn't have these files generated, but it does produce assemblies more geared towards production than development.

However, there are a whole bunch of other things you can configure for different build configurations. Right-click on aproject in Visual Studio, select Properties, then look at everything that appears under 'Configuration Properties' - all of those items can change for different Build Configurations. We're interested in the 'Output Path' property, and I'll explain why.

When we tell NAnt to compile the Debug Build Configuration of our solution, it tries to invoke the C# compiler to produce all the files that appear under the bin\Debug folder for each VS Project. There's a problem with this though - if we already have the Solution open in Visual Studio, VS will have locks on those files once they reach a certain size. That means that our NAnt compile will fail since it can't overwrite the assemblies. Anyway, it would be cleaner if we could separate out our 'automated' build from our 'interactive' build.

Thankfully, Build Configurations let us do this and still use the <solution> task. We do this by creating a new Build Configuration which we will just use for automated builds, and change where it outputs its files to.

To do this for Sycamore, I open up Visual Studio's 'Configuration Manager'(right click on the Solution, choose 'Configuration Manager'), and create a new configuration (open the drop-down menu, select '<New...>'). I'm going to call the new configuration AutomatedDebug and copy settings from the 'Debug' configuration (leave the 'create new project configuration(s)' box checked.) Close the dialog, and then bring up the properties for 'SycamoreConsole'. Select the 'Build' 'Configuration Properties' section, and make sure 'AutomatedDebug' is selected in the Configuration drop-down. Select the 'Output Path' box and change its value to '..\..\build\Debug\SycamoreConsole'. Switch Visual Studio back to the normal 'Debug' configuration which we use for interactive builds.

Finally, edit the build script, and change the 'configuration' argument of the
<solution> task to be AutomatedDebug. It should now look like this:

<target name="compile">
<solution solutionfile="src\Sycamore.sln"
configuration="AutomatedDebug" />
</target>

So what have we actually done here? If you run NAnt, you should see the following lines in your build output:

compile:
[solution] Starting solution build.
[solution] Building 'SycamoreConsole' [AutomatedDebug] ...

This tells us that NAnt is using the new Build Configuration. Now, look in the build\Debug\SycamoreConsole folder - you should see our compiled .exe file (and a .pdb file since we are compiling with debug options.)

That tells us what is happening, but why have we put these files in this directory? We use the build folder as another of our 'top level' project folders. It will contain all the build artifacts (assemblies, test reports, etc.) that we produce in the automated build. It will not contain any files that aren't generated by the build, so we don't need to check it into Source Control, and we can safely delete it whenever we want. Under build we will have a number of sub-folders, and so far we created one called Debug that will contain all of our Debug compilation artifacts. We put the artifacts for each VS Project in its own folder, with the same name as the VS Project it belongs to.

I said we could safely delete this folder, so let's add another NAnt target that will do this:

<target name="clean">
<delete dir="build" if="${directory::exists('build')}"/>
</target>

I also said we didn't need to check the build folder into Source Control, so we can also add it to our list of excluded files. With Subversion, I do this by editting the svn:ignore property of the project root folder.

Finally for this part, we're going to create a batch file that developers can use to kick off the build. Its very simple, having just the following line:

 
@tools\nant\NAnt.exe -buildfile:Sycamore.build %*

I like calling this file 'go.bat' since the targets in the build script tend to be 'action' type words. Since its closely associated with the build script, put it in the project root. Note that we specify which build script to use - change this for your project. To use this file, just pass the target to run as an option, so to delete the build folder, just enter go clean.

Note that this batch file really is just meant as a bootstrap for convenience. I've seen plenty of projects use a combination of batch files and NAnt / Ant scripts to configure a build system. This is a bad idea for several reasons:

Batch files are significantly less manageable or powerful than NAnt,and tend to get very 'hacky' very quickly.
Your build behaviour really is one distinct concept and NAnt can handle all of it - splitting it across technologies isn't necessary.
Don't go down the road of having multiple batch files to launch builds for different environments. I'm yet to see a project that managed to pull this off in a clean, manageable way. Apart from anything else it is redundancy, and introduces more manual work and possiblities for error. Instead, use logic in your NAnt script to use different property values for different environments (hopefully I'll get on to build configuration and refactoring concepts in the future.)

If you run your default target, it should still be successful. If you have all your ignored files and directories setup correctly you should have 4 files to commit - the build script, the build script launcher (go.bat), the solution, and the VS Project for Sycamore Console. I'm going to check in these changes and call it a day for this part. The current state of Sycamore is available here. To summarise this part:

Use a top-level, transient, folder called build as the target folder of your automated build.
Create a new Visual Studio Build Configuration for your automated NAnt Builds. This Build Configuration should output to build.
Setup a clean target to delete your transient files.
Create a simple build bootstrap batch file.
Don't put any kind of build logic in this build bootstrap - leave that allin the NAnt build script.

In the next part we'll start to add some unit tests.

UPDATED WIKI: DevelopmentTreePart4

donnfelker — Sat, 02 Jun 2007 23:15:28 GMT

Part 4 - Adding an Automated Build

At this point we have a basic Visual Studio solution checked into Source Control. Now its time to automate how we build this solution.

Most of the time .NET developers will work solely within the Visual Studio environment, compiling their solution with the in-built compiler, and running tests using TestDriven.NET (more on testing to come...). But relying solely on Visual Studio as a way to produce build artifacts and run your tests isn't enough. For instance:

How do you run scheduled or triggered builds for your project? Using the command line version of Visual Studio (devenv.com) provides you with only basic command line features.
Visual Studio's 'pre-' and 'post-' build events provide some build scripting beyond just compiling code, but such scripting is limited in scope and expressiveness.

The current 'de-facto' automated build tool for .NET projects is NAnt. NAnt is based on the Java build tool Ant and has similar strengths (integration with lots of useful tools, few dependencies) and also its weaknesses (being defined in XML means large build scripts quickly get hard to maintain). .NET 2 and Visual Studio 2005 will come with their own build scripting tool, MSBuild, which is very similar to NAnt. Investing in NAnt now should give you a build script you can easily convert to MSBuild later, should you want to.
NAnt is a tool that can be installed on every developers machine. However, I like to check NAnt into the project tree for some simple reasons:

It saves the manual steps of everyone copying it to their machine, and installing it. (Remember - manual steps take time and are a possible point of error.)
NAnt changes between versions, and such changes can effect the behaviour of a build. Making sure that everyone has the same version of NAnt when everyone is manually installing it can be tricky, and is time consuming when you want to upgrade the version of NAnt everyone uses.
Many projects use their own 'custom' NAnt tasks. Storing these in source control along with the project's own version of NAnt makes distribution to team members painless.
It is not a large tool, so the overhead of storing it in source control should not be a problem.

To add NAnt to your project tree, first download and unpack its binary zip file (I'm going to use NAnt 0.85 RC1, available here.) Then, copy the bin folder to your project directory. I like to put all build-time tools in a subfolder of my project root called tools, and then put the contents of NAnt's bin folder in tools\nant. Before going any further, commit NAnt to your project's source control, making sure to include in the commit message the version of NAnt you are using. Later on, this will help you decide whether you want to upgrade to a new version.

You tell NAnt what to do using a build script. The standard for naming NAnt build scripts is ProjectName.build. The build script is a gateway into our project, so I like to save it in the root folder. You can edit your build script with Visual Studio - create it as a 'solution item' (Right click on the solution icon in Solution Explorer and choose Add new item... or Add existing item...). If you follow the instructions here and here you'll even get IntelliSense! (Thanks to Serge van e Oever and Craig Boland for writing it up.)

Our first NAnt build script will just compile our project. There are several ways to do this, and I'm going to use the <solution> task:

<?xml version="1.0" ?>
<project name="nant" default="compile" xmlns="http://nant.sf.net/schemas/nant.xsd">
	<target name="compile">
		<solution solutionfile="src\Sycamore.sln" configuration="debug" />
	</target>
</project>

I like to use the <solution> task for a couple of reasons:

For developers to work in Visual Studio we need to define how to compile our project in Visual Studio using its'references' system. <solution> lets us re-use all this work in 1 line of script. If we were to use the <csc> task instead we would need to maintain a separate set of compile definitions (which would be time-consuming and might not match the Solution / VS Project setup).
Using <solution> rather than the <exec> task calling out to devenv.com is less resource intensive, gives more appropriate feedback and also allows us to run builds on machines without Visual Studio installed (it just needs the .NET SDK.) If you have a problem using <solution> you can always quickly replace it with an <exec> to devenv.com

To run your build, save the build script, open a command prompt and change to your project's root folder. Then just entertools\nant\NAnt. You should see output like:

NAnt 0.85 (Build 0.85.1793.0; rc1; 28/11/2004)
Copyright (C) 2001-2004 Gerry Shaw
http://nant.sourceforge.net
Buildfile: file:///c:/devel/sycamore/Sycamore.build
Target(s) specified: compile
compile:
[solution] Starting solution build.
[solution] Building 'SycamoreConsole' [debug] ...
BUILD SUCCEEDED
Total time: 0.2 seconds.

Woohoo - a successful build! We have something new, that works, so submit the build script (and your changes to theSolution file that include the build script) to source control.

The current state of Sycamore is available here (link unavailable).

To summarise this part:

Add an automated build system to your project.
Use NAnt to automate your .NET 1.1 and earlier projects.
Check the NAnt distribution into your development tree.
Create a build script and save it in your development tree.
Use the <solution> task to compile your project.

In the next part we'll be adding some more features to our automated build.