v1 Home

Albacore is a professional quality suite of Rake tasks for building .NET or Mono based systems. You can use our specialized tasks to create the build of your choice. You can jump right into the list of tasks by following the links on the right or follow this quick start for a guided tour.

Rake Quick Start

Rake is a Ruby DSL that provides a task infrastructure including dependency resolution and chaining, file and path manipulation, parallel task execution, and more. By convention, your build tasks will reside in a rakefile at your repository root. A rakefile contains executable Ruby code.

The default rake task is used to start the process. Here you can see the default task depends on the build and test tasks.

task :default => [:build, :test]

A typical task is a "block" of code that is only executed when you ask rake or when rake is required, by dependencies, to execute it. Tasks can be described (desc "a description") so that they can be summarized with rake --tasks or rake -T.

desc "Build the solution in Release mode"
task :build do 
  system "msbuild.exe MySolution.sln /target:Build /property:Configuration=Release"
end

You may run the default task in the default rakefile by simply executing the rake task on your command line

> rake

Or you can specify one or more tasks explicitly

> rake build test

Albacore Quick Start

If you're used to tinkering with CC.NET, NAnt, or MSBuild "scripts", you probably know to put aside several hours -- if not a day -- to work on your build tasks. The good news is that, with Albacore, you can have a working build in a few minutes. And, it will be maintainable and readable!

First, make sure that you're running on a supported version of Ruby and that you have properly installed Albacore. Create a rakefile at the root of your repository and include the Albacore gem.

require "albacore"

Let's look at the common tasks for a .NET solution: version the assemblies, compile the solution in a Release configuration, and run all of the tests.

task :default => [:version, :build, :test]

Versioning

Most .NET projects have a shared AssemblyInfo.cs project where all of the static/common assembly attributes are encoded, then that file is linked in each project. Here we use the assemblyinfo task to overwrite that file with the custom version number for this build.

desc "Increment the file and assembly version"
assemblyinfo :version do |cmd|
  cmd.version = cmd.file_version = "1.0.0"
  cmd.input_file = cmd.output_file = "source/AssemblyInfo.cs"
end

Obviously, we don't want the version number to be static. You may use one of the Ruby gems that provide version management in a VERSION file. You would assign the version to the gem's method.

version = bump_version.to_s

Or, maybe your build server manages your build number and you incorporate that into an overall version number. You can pass that to your rake command as an environment variable, right on the command line.

> rake version=%your.build.systems.variable.notation.here%

And read it off in your task

version = ENV["version"] || "some.default.version.number"

Building

We'll do a basic Release configuration build using the msbuild task, which shells to msbuild.exe. If you're familiar with the msbuild.exe command line usage, some of these properties will look familiar to you.

desc "Build the solution in the Release configuration"
msbuild :build do |cmd|
  cmd.solution = "MySolution.sln"
  cmd.targets = [:Clean, :Build]
  cmd.properties = {:Configuration => "Release"}
end

Testing

Now, let's test those compiled assemblies. The nunit task knows how to generate the command line call for any of the many nunit-*.exe tools. We also have tasks for all of the major test runners. We use Ruby's path matching facilities to find all of the test assemblies in any of the output paths.

desc "Run all of the nunit test assemblies"
nunit :test do |cmd|
  cmd.command = "path/to/nunit-console.exe"
  cmd.assemblies = FileList["**/bin/Release/*.Tests.dll"]
  cmd.parameters = ["/nologo", "/noresults"]
end

But, wait, you shouldn't (and in some cases, can't) test without first building the assemblies. So, let's add the dependency.

nunit :test => [:build] do |cmd|

Summary

That's it, you've got a fully configured Rake build for your .NET or Mono based system in a few minutes and a couple dozen lines of Ruby code!

require "albacore"

task :default => [:version, :build, :test]

desc "Increment the file and assembly version"
assemblyinfo :version do |cmd|
  cmd.version = cmd.file_version = ENV["version"] || "1.0.0"
  cmd.input_file = cmd.output_file = "AssemblyInfo.cs"
end

desc "Build the solution in the Release configuration"
msbuild :build do |cmd|
  cmd.solution = "MySolution.sln"
  cmd.targets = [:Clean, :Build]
  cmd.properties = {:Configuration => "Release"}
end

desc "Run all of the nunit test assemblies"
nunit :test => [:build] do |cmd|
  cmd.command = "path/to/nunit-console.exe"
  cmd.assemblies = FileList["**/bin/Release/*.Tests.dll"]
  cmd.parameters = ["/nologo", "/noresults"]
end

Let's explore these wonderful tasks from our command line

> rake -T
rake build    # Build the solution in the Release configuration
rake test     # Run all of the nunit test assemblies
rake version  # Increment the file and assembly version

And run just the ones we want from our local shell

> rake test

or configure the full build on the build server

> rake version=%system.build.number%