uppercut - getting started

UppercuT – The insanely easy to use build framework for .NET http://uppercut.googlecode.com

ath

The Insanely Easy to Use Automated Build Framework http://uppercut.googlecode.com

of 28

UPPERCU

TGETTING STARTED

http://uppercut.googlecode.com/


http://uppercut.googlecode.com/%00%E5%A1%B9%EF%92%81%E1%B4%BB%E4%A1%BF%E2%B2%AF%E5%B6%82%E8%97%84%E6%8C%A7%00%00%EA%AE%A5

UppercuT – Getting Started

ContentsPrerequisites..............................................................................................................3

Download.....................................................................................................................................3Ensure Path..................................................................................................................................3

Get UppercuT............................................................................................................5Download.....................................................................................................................................6Get the Source..............................................................................................................................7

Add UppercuT to Your Project..................................................................................7UppercuT.config......................................................................................................14

Get Building Fast.......................................................................................................................14An Explanation of the Full Configuration.................................................................................17

External Libraries/Tools..........................................................................................19BUILD IT! What You’ve Been Waiting For...........................................................20To Be or Not To Be (UppercuT & Source Control)................................................22

Artifacts of the Build.................................................................................................................22build_output...........................................................................................................................23code_drop..............................................................................................................................23SolutionVersion.cs/SolutionVersion.vb.................................................................................23

Check It In.................................................................................................................................24TortoiseSVN Global Ignore List................................................................................................25

Next Steps................................................................................................................27The Power of UppercuT............................................................................................................27

VersionBuilder.......................................................................................................................27Integration with Continuous Integration Server (like Team City or CruiseControl.NET)....27Implement Custom Tasks if necessary...................................................................................27ConfigBuilder........................................................................................................................27DeploymentBuilder................................................................................................................28Other Features........................................................................................................................28

Resources...................................................................................................................................28Ask Questions / Learn About Changes & New Versions...........................................................28

of 28


Welcome to UppercuT, the insanely easy to use automated build framework. You are making a step in the right direction when you choose to use automated builds. As you read through this, you will see how easy it is to get into the world of automated builds. As you read through some of the other documents, you will learn just how powerful UppercuT is.

Prerequisites

Source control command line tool on the path

Download

In our case Subversion Command line client. You can get that from Collabnet (you will have to register) at http://www.collab.net/downloads/subversion/.

Choose CollabNet Subversion Command-Line Client v1.x.x (for Windows).

Register, download, and install that.

Ensure Path

Then you have to ensure it's on the path so you can open a command line in any folder and type svn.

Note: If you install CollabNet's SVN client, it should already be on the path.

1. These instructions are geared to WindowsXP. Adjust for other Operating Systems.

2. Right click on My Computer on the Desktop and select [Properties].

of 28

http://www.collab.net/downloads/subversion/


3. Click on the Advanced tab. Click on {Environment Variables}.

of 28


4. In the System variables section, there is a variable named Path. Select Path, and then click {Edit}.

5. Ensure that somewhere in that long set of text is C:\Program Files\CollabNet Subversion Client. If it's not there, add it. Make sure you separate each path with a semi-colon (;).

6. Click {OK}. Click {OK} all the way out.

Note: We do not want to bind your source code to the version of source control that you use. So we don't want you to check that in as a reference. We could certainly do it, but there could be a lot of issues with that approach. You may upgrade SVN once every two months. How many different places do you want to do that? Would you want to do that in every repository? Probably not - and that couples source code to its source control.

Get UppercuT

The first thing you need to do is download or pull the source to your computer and build it. Either way, you have probably already done that if you are reading this.

of 28


Download

1. Head out to http://code.google.com/p/uppercut/downloads/list and download the latest.

2. One thing to note, when you do download the zip file, the very first thing you will want to do (before extracting) is right click on that file and select [Properties]. On the General tab click {Unblock} if you have it. Otherwise you may have to unblock each file one at a time later.

3. Unzip the files. What we will need to bring into a project is in the UppercuT folder.

of 28

http://code.google.com/p/uppercut/downloads/list


Get the Source

1. The other way to get UppercuT is to point your favorite SVN client at http ://uppercut.googlecode.com/svn/trunk/ .

2. Once it has completed downloading, just click on the build.bat (or open a command line in this directory and type build).

3. Once it has completed, there is a folder called code_drop. This is one of the artifact folders of UppercuT. We will talk about that later. For now, navigate to the folder. What we will need to bring into a project is in the UppercuT folder.

Add UppercuT to Your Project

Now we have UppercuT ready to put in a project that needs automated builds. Let’s UppercuT our code!

1. We open the folder at the top level of the project (usually just under trunk or a branch). Below you can see we have a project called MoneyQIFGenerator and it has no automated build love yet.

of 28

http://uppercut.googlecode.com/svn/trunk/


2. We already have a references folder (lib) so we are going to do something differently when bringing in UppercuT. For any existing project this could be 3rdParty, ThirdParty, References, External, lib, libs, etc. This is where you keep your external references and tools and where we will ultimately put parts of UppercuT. The remainder of the time we are going to call this third party references folder lib.

3. We pull up the folder where we have downloaded or compiled UppercuT.

4. We select everything except the lib folder. We already have a lib folder so we are going to bring the items in this folder over in pieces. If we are adding this to a brand new project we select the lib folder as well and bring it over in whole.

of 28


5. Select [Edit]->[Copy] in the UppercuT folder.

6. Go to the project folder. Select [Edit]->[Paste].

7. We should now have all of these new folders and files ready to add to source control.

of 28


8. If we brought over the lib folder, we can skip the next few steps. If we are adding to a project that already had a references folder, we go back to UppercuT’s folder and into the lib folder.

9. Open the lib folder on the project. This could be 3rdParty, ThirdParty, References, External, lib, libs, etc. This is where you keep your external references and tools.

of 28


10. In the references folder (UppercuT side), copy either the MbUnit or NUnit folder over to the project’s references folder. If you already have the references to your test framework (as we do below), there is nothing to do (unless there are missing components).

11. In the tools folder (UppercuT side), we have NAnt and NCover. If we already have these referenced, we don’t need to copy them over. If we don’t have these referenced, bring over the entire tools folder into the lib folder. You can see that we don’t have either of these in the project, so we bring over the entire tools folder.

of 28


12. Now we need to add all of these files to source control. If we are using TortoiseSVN, we right click in the top level folder (but not on a file, click in the white space). Select [TortoiseSVN]->[Add…].

13. Make sure all items are selected.

14. If you already have a build_output folder, a code_drop folder, or a SolutionVersion.cs/SolutionVersion.vb file, uncheck those entire folders and that file. You would only have these the first time if you have already tried to build. These are items we never want in source control (they are generated items).

of 28


15. Click {OK}.

16. The items are being staged to be committed to source control.

17. With Subversion, this is basically what we should see as a result.

of 28


UppercuT.config

1. Navigate to the Settings folder and open the UppercuT.config file in your favorite editor.

2. Take a moment to familiarize yourself with all of the options available in the configuration file.

Get Building Fast

3. Here are the three questions most people need to answer.

<property name="project.name" value="__SOLUTION_NAME_WITHOUT_SLN_EXTENSION__" overwrite="false" />

of 28


<property name="path_to_solution" value="." overwrite="false" /><property name="repository.path" value="__REPOSITORY_PATH__" overwrite="false" /><property name="company.name" value="__COMPANY_NAME__" overwrite="false" />

becomes

<property name="project.name" value="MoneyQIFGenerator" overwrite="false" /><property name="path_to_solution" value="." overwrite="false" /><property name="repository.path" value=" https://robz.homedns.org/svn/utilities/" overwrite="false" /><property name="company.name" value="FerventCoder Software" overwrite="false" />

4. Copy the name of the solution file (minus .sln).

5. Select the current value of the project.name property. Currently it is __SOLUTION_NAME_WITHOUT_SLN_EXTENSION__.

6. Paste the solution name you copied.

7. Find and copy the url to the project in source control (provided you have a url). Otherwise just use http://something. At the time of writing this document, the revision side of VersionBuilder only works with Subversion repositories.

of 28


8. Select the current value of the repository.path property. Currently it is __REPOSITORY_PATH__.

9. Paste the url you copied. Remember that this should be to the top level of the repository, even if you are in the trunk or a branch.

10. Select the current value of the company.name property. Currently it is __COMPANY_NAME__.

of 28

The solution name is MoneyQIFGenerator.sln, so we include it as the project name without the .sln extension. The repository path is not down to a trunk or a branch, but at the very top level of the repository. The company is either a company you work for or your own personal company if you are open source.

An Explanation of the Full Configuration

Let's talk about each property in the configuration:

<?xml version="1.0" encoding="utf-8" ?><project name="BuildSettings">  

 <property name="project.name" value="__SOLUTION_NAME_WITHOUT_SLN_EXTENSION__" overwrite="false" /> <property name="path_to_solution" value="." overwrite="false" /> <property name="repository.path" value="__REPOSITORY_PATH__" overwrite="false" /> <property name="company.name" value="__COMPANY_NAME__" overwrite="false" /> <property name="dirs.db.project" value="__DATABASE_FOLDER_NAME__" overwrite="false" /> <property name="dirs.report.project" value="__REPORT_PROJECT_FOLDER__" overwrite="false" /> <property name="dirs.documentation" value="docs" overwrite="false" />

<property name="app.drop.folder" value="app" overwrite="false" />   <property name="microsoft.framework" value="net-3.5" overwrite="false" />   <property name="language.short" value="cs" overwrite="false" />  <property name="test.framework" value="mbunit" overwrite="false" />  <property name="source_control_type" value="svn" overwrite="false" />

 <property name="version.major" value="0" overwrite="false" /> <property name="version.minor" value="0" overwrite="false" />  <property name="allow.partially_trusted_callers" value="false" overwrite="false" />



of 28

<property name="app.ncover" value="..\..\lib\tools\NCover\NCover.Console.exe" overwrite="false" /> <property name="app.ncover_explorer" value="..\..\lib\tools\NCover\NCoverExplorer.Console.exe" overwrite="false" /> <property name="app.ncover.tester" value="..\..\lib\references\MbUnit\MbUnit.Cons.exe" overwrite="false" />  <property name="app.ndepend" value="C:\Program Files\NDepend\NDepend.Console.exe" overwrite="false" /></project>

project.name = This is your solution file name (minus the .sln). This is also used in quite a few other places like with NCover and the assembly file.

path_to_solution = This is the RELATIVE PATH to the folder your solution file is in. For most people this might be src. This is used to locate your solution file and also used for where to put the assembly file (i.e. SolutionVersion.cs).

respository.path = This is the path to the top level of your repository. Not to a trunk or a branch. This is used to attempt to get revision information.

company.name = This is the name of your company, the company you work for, or something else. This is currently used as part of the assembly file.

dirs.db.project = This is the folder name of where you keep your database scripts. Some people keep them in a folder named db. This is only used during packaging to bring the folder into the code_drop for deployment. If you have more than one, you need to use custom build scripts [http://uppercut.pbworks.com/CustomTasks].

dirs.report.project = This is the folder name where you keep your reports. This is only used during packaging to bring the folder into the code_drop for deployment. If you have more than one, you will need to use custom build scripts [http://uppercut.pbworks.com/CustomTasks].

dirs.documentation = This is the top level folder you keep your documentation in. This is used during building to bring items to the code_drop folder.

app.drop.folder = This is the name of the folder your application drops into after a build. microsoft.framework = This is the version of the Microsoft Framework you are using. This is

used during compile. language.short = What language are you building in? Valid values are vb or cs. Language is

used only to determine how to output the assembly file (i.e SolutionVersion.vb or SolutionVersion.cs).

test.framework = What test framework do you use? This is used to determine how to run your application's tests. Currently we only support MbUnit [http://www.mbunit.com/] and NUnit [http://www.nunit.org/]. You are welcome to submit a patch.

source_control_type = What kind of source control do you use? This is used to determine how to get revision/version information. Currently we only get version information if your source control type is svn.

version.major = In versioning your application, this is 1.x.x.x. This is used only when building the assembly file.

version.minor = In versioning your application, this is x.1.x.x. This is used only when building the assembly file.

of 28

http://www.nunit.org/

http://www.nunit.org/

http://www.mbunit.com/

http://www.mbunit.com/

http://uppercut.pbworks.com/CustomTasks


app.ncover = This is the relative path (from the BuildScripts\analyzers folder) to where you keep the reference to NCover.Console.exe. The last free version of NCover we include with UppercuT. This is used during the NCover build. If the location is non-existent, UppercuT moves on to the next build step.

app.ncover.explorer = This is the relative path (from the BuildScripts\analyzers folder) to where you keep the reference to NCoverExplorer.Console.exe. The last free version of NCover we include with UppercuT. This is used during the NCover build. If the location is non-existent and the app.ncover location exists, UppercuT will throw a non-fatal error and move on.

app.ncover.tester = This is the relative path (from the BuildScripts\analyzers folder) to where you keep the reference to the testing framework's console runner. This is used during the NCover build. If the location is non-existent and the app.ncover location exists, UppercuT will throw a non-fatal error and move on.

app.nepend = This is the path to NDepend.Console.exe. NDepend is not a free tool, but it is very valuable in determining code quality. Because it is not free, we can not include it in the framework. But we do provide the tools to leverage it if you do have a license for it. If the location is non-existent, UppercuT moves on to the next build step.

External Libraries/Tools

It’s important to note that not everyone keeps their references to external libraries in the same location (lib) in source control. That’s fine, but it does require a bit of additional work. In the configuration, you will want to edit where to find the tools UppercuT references.

1. If you are not using the same location for any item that UppercuT references in the lib folder, you will want to update the locations of those items.

2. Open UppercuT.config in your favorite editor and scroll to the bottom. Three items here are pointing to lib\tools and lib\references (based on a relative path from the BuildScripts\analyzers folder).

3. Update those locations to where you put the items.

of 28


4. Notice if you are using NUnit, there is a line commented out. You can comment out the MbUnit line and uncomment the NUnit line.

5. The most important change is the reference location of NAnt in all of the .bat files. Right click on each of them and select [Edit] or open them in your favorite editor.

6. Find the reference to nant.exe. This location is from where the bat file currently sits. Leave %DIR% on the left and update the reference location to NAnt.

7. The test.bat file has 3 places to change. Make sure you change all of them.

8. Close those files down. We are ready to build.

BUILD IT! What You’ve Been Waiting For

1. Open a command line in the current folder. There is an excellent tool called StExBar [http://ferventcoder.com/archive/2009/05/21/stexbar---a-great-add-on-for-windows-explorer.aspx] that will allow you to do this by pressing {Control} + {M}.

of 28

http://ferventcoder.com/archive/2009/05/21/stexbar---a-great-add-on-for-windows-explorer.aspx




2. Type build. Press {Enter}.

3. Now watch UppercuT in action.

of 28


4. If your build succeeds, it’s time to check it in!

To Be or Not To Be (UppercuT & Source Control)

Artifacts of the Build

UppercuT outputs some files and folders that should never be checked into source control. These are basically the same as what is in your bin directories with some differences. These folders/files should be excluded from source control.

of 28


build_output

The build_output folder is like the bin folder, but it’s the bin folder that puts every project in the solution’s output in this folder. Why not call it bin? We didn’t want to interfere with those projects that might have a top level bin folder.

code_drop

The code_drop folder is the nice packaging of the built application so that it is ready for deployment. Why code_drop? That’s a great question. The answer is that we had a lot of thoughts about what to call it, but in the end, code_drop seemed to make sense so we came back to it.

SolutionVersion.cs/SolutionVersion.vb

The SolutionVersion file is the file that changes with every build. It puts into it all of the common assembly elements. You can reference this file (using a link - see VersionBuilder) in every project and get the benefit of automatic versioning of your DLLs. If you are not using subversion or a continuous integration server, you can still get benefits of all of the other common elements by using the SolutionVersion file.

of 28


NOTE: A Visual Studio build will not work without SolutionVersion present. Some people find it is easier to go ahead and check that in on Open Source Projects to reduce the amount of confusion.

Check It In

Once we are building successfully, we need to get our changes updated in source control.

1. Open a commit dialog. Do not check in unversioned files. We have some files/folders that we don’t want to check in that are artifacts of the build.

2. We make sure {Show unversioned files} is unchecked. Click {OK}.

of 28


TortoiseSVN Global Ignore List

Because TortoiseSVN is the most commonly used client, it’s worth mentioning the Global Ignore list. You benefit when using it because you don’t have to manually exclude those files/folders that UppercuT creates.

1. Right click on anything in explorer. Select [TortoiseSVN]->[Settings].

2. On the General tab, in the Subversion section, you will find {Global ignore pattern:}.

of 28


3. Add *\build_output *\build_output\* *\code_drop *\code_drop\* SolutionVersion.cs SolutionVersion.vb to it.

4. Click {Apply}. Click {OK}.

5. This is the full ignore pattern:

*.suo *\bin *\obj *\bin\* *\obj\* *.resharper *.user _ReSharper* *.cache *.log *.vspscc *.vssscc *\build_output *\build_output\* *\code_drop *\code_drop\* SolutionVersion.cs SolutionVersion.vb

of 28


Next Steps

The Power of UppercuT

UppercuT comes with many great features! You now have automated build goodness; why not take a look at what else you can do? Some of these features will help you better maintain your code or even do less work to get the same results.

VersionBuilder

VersionBuilder allows you to tie your DLLs back to both a build and a revision number in source control. A common problem many of us have is versioning our DLL assemblies and keeping track of what’s in production versus what’s in source control. If you rock with Subversion, UppercuT has this problem solved UppercuT automatically generates an assembly version file for you during build. All you need to do is hook every project up to it.

See more in the VersionBuilder document [http://uppercut.googlecode.com/svn/trunk/docs/VersionBuilder.doc] or at http://ferventcoder.com/archive/2009/05/21/uppercut---automated-builds---versionbuilder.aspx

Integration with Continuous Integration Server (like Team City or CruiseControl.NET)

Having automated builds with UppercuT is good, but it’s even better once you get a continuous integration server to automatically check your code out on changes and run UppercuT for you!

See more in the CruiseControl.NET Integration Document [http://uppercut.googlecode.com/svn/trunk/docs/IntegrateUppercuTWithCruiseControl.NET.doc] or at http://ferventcoder.com/archive/2009/05/21/uppercut---automated-builds---cruisecontrol.net-integration.aspx

Get samples here: http://uppercut.googlecode.com/svn/trunk/docs/Samples/CC.NET/

Implement Custom Tasks if necessary

What good is a build framework if you can’t extend it? That is why we planned a way to allow you to hook right into UppercuT at certain points with Custom Tasks.

See more in the Custom Tasks Document [http://uppercut.googlecode.com/svn/trunk/docs/CustomTasks.doc] or at http://ferventcoder.com/archive/2009/05/21/uppercut---automated-builds---custom-tasks.aspx.

ConfigBuilder

How much maintenance are you doing on configuration files? What happens when you have to update a configuration? You usually have to update it in multiple places. ConfigBuilder allows

of 28

http://ferventcoder.com/archive/2009/05/21/uppercut---automated-builds---custom-tasks.aspx

http://uppercut.googlecode.com/svn/trunk/docs/CustomTasks.doc

http://uppercut.googlecode.com/svn/trunk/docs/CustomTasks.doc

http://uppercut.googlecode.com/svn/trunk/docs/Samples/CC.NET/

http://ferventcoder.com/archive/2009/05/21/uppercut---automated-builds---cruisecontrol.net-integration.aspx

http://ferventcoder.com/archive/2009/05/21/uppercut---automated-builds---cruisecontrol.net-integration.aspx

http://uppercut.googlecode.com/svn/trunk/docs/IntegrateUppercuTWithCruiseControl.NET.doc

http://uppercut.googlecode.com/svn/trunk/docs/IntegrateUppercuTWithCruiseControl.NET.doc

http://ferventcoder.com/archive/2009/05/21/uppercut---automated-builds---versionbuilder.aspx

http://uppercut.googlecode.com/svn/trunk/docs/VersionBuilder.doc

http://uppercut.googlecode.com/svn/trunk/docs/VersionBuilder.doc


you to get away from that and only maintain a template file that looks just like the configuration file, but with pointers to environment variables.

See more in the ConfigBuilder Document [http://uppercut.googlecode.com/svn/trunk/docs/ConfigBuilder.doc] or at http://ferventcoder.com/archive/2009/05/17/uppercut---automated-builds---the-configbuilder.aspx.

DeploymentBuilder

How much maintenance are you doing on deployment batch files (if you use scripted deployments)? Would you rather maintain just one file? That is where DeploymentBuilder comes in. It allows you to maintain a template file in much the same way as ConfigBuilder.

See more in the DeploymentBuilder Document [http://uppercut.googlecode.com/svn/trunk/docs/DeploymentBuilder.doc] or at http://ferventcoder.com/archive/2009/05/19/uppercut---automated-builds---deploymentbuilder.aspx.

Other Features

More features are being added to UppercuT. Stay tuned for a roadmap of what features are expected to be in 1.0.

Resources

UppercuT on GoogleCode – http://uppercut.googlecode.com

Source Control – http://uppercut.googlecode.com/svn/trunk

Documentation - http://uppercut.googlecode.com/svn/trunk/docs/

UppercuT User Group – see section below

FerventCoder blog – lots of great articles on UppercuT http://ferventcoder.com/category/uppercut.aspx

Ask Questions / Learn About Changes & New Versions

If you have questions, you want to know about new features, or you want to get more involved, feel free to join the group. http://groups.google.com/group/uppercut-users

of 28

http://groups.google.com/group/uppercut-users

http://ferventcoder.com/category/uppercut.aspx

http://uppercut.googlecode.com/svn/trunk/docs/

http://uppercut.googlecode.com/svn/trunk


http://ferventcoder.com/archive/2009/05/19/uppercut---automated-builds---deploymentbuilder.aspx

http://ferventcoder.com/archive/2009/05/19/uppercut---automated-builds---deploymentbuilder.aspx

http://uppercut.googlecode.com/svn/trunk/docs/DeploymentBuilder.doc

http://uppercut.googlecode.com/svn/trunk/docs/DeploymentBuilder.doc

http://ferventcoder.com/archive/2009/05/17/uppercut---automated-builds---the-configbuilder.aspx

http://ferventcoder.com/archive/2009/05/17/uppercut---automated-builds---the-configbuilder.aspx

http://uppercut.googlecode.com/svn/trunk/docs/ConfigBuilder.doc

http://uppercut.googlecode.com/svn/trunk/docs/ConfigBuilder.doc

uppercut - getting started

Technology

uppercut folder

project folder

uppercut source control

uppercut ready

power of uppercut

compiled uppercut

powerful uppercut

parts of uppercut