Building packages

Building packages

If you have just created your first project, and followed the default conventions, you’ll can create a package with a grand total of one-line.

C:\src\wraps\Castle.Services.Transaction> o build-wrap -quiet

# OpenWrap v1.0.0.0 ['C:\src\wraps\Castle.Services.Transaction\wraps\_cache\openwrap-1.0.0.19333731\bin-net35\OpenWrap.dll']
Copying: bin-net35 - C:\src\wraps\Castle.Services.Transaction\src\Castle.Services.Transaction\obj\Debug\Castle.Services.Transaction.dll
Copying: bin-net35 - C:\src\wraps\Castle.Services.Transaction\src\Castle.Services.Transaction\bin\Debug\Castle.Services.Transaction.XML

Package built at 'C:\src\wraps\Castle.Services.Transaction\Castle.Services.Transaction-2.1.0.19335506.wrap'.

By convention, OpenWrap tries and compile any file that ends with .*proj.

Customizing the build

The build can be customized by providing one or many build instructions in your descriptor, one per line.

Files included by default in any build

All build providers automatically include a few files automatically:

• A package descriptor (.wrapdesc) including the generated version number
• The version file (version) containing the generated version number

For more information on versions, see Package versioning.

Null package builder

Sometimes there is nothing to build, such as for meta packages. In this case the build provider is the null one.

build: none

MSBuild package builder

You may want to build your MSBuild files differently than what the default convention does.

Equivalent to not having a build instruction

Not specifying a build instruction is the equivalent of specifying the following line.

build: msbuild

Choosing which project gets compiled

To customize which projects get used you can add a build instruction in your descriptor, and add a project parameter.

build: msbuild;project=src\Castle.Services.Transaction\Castle.Services.Transaction-vs2010.csproj

This line states that msbuild is how you want to build your package, and provides the path to the msbuild project you want to build, relative to your package descriptor. In this example, only that project will be built.

Of course, you can add more projects by simply adding a new project parameter, they're all separated by a semi-column.

Targetting multiple versions of .net

In some projects, you may end up wanting to build your project once per version you support. The typical example would be to build it once for the Microsoft CLR, and a second time specifically for mono. We support that too.

build: msbuild;profile=net20;profile=net35

By adding those parameters to the msbuild instruction, OpenWrap will call every project to be compiled with a different value for the OpenWrap-TargetProfile parameter. Each of the builds will impact what assemblies get included (by selecting the correct version of an assembly in each of the folders of all referenced packages), and will set the OpenWrap-TargetProfile msbuild property with the version that was provided.

The default build also sets a bunch of compile constants you may find useful when conditionally compiling code for different profiles and platforms.

The current profile is defined in OW_PROFILE_ID where ID is net20, net30, net30cp etc.

The current platform is defined in OW_PLATFORM_ID where ID is AnyCPU, x86 or x64.

Adding your own files in the package folders

OpenWrap tries to play dumb when it comes to parsing the result of your build. The only thing it’s looking for are instructions you output in your build.

Each of those instructions should follow a simple template.

[built(targetFolder, “pathToFile”)]

Whenever such an instruction is encountered in the output of your msbuild file, OpenWrap will package the file at pathToFile in a folder named targetFolder. pathToFile is relative to the descriptor file.

If you wanted to add a custom file in your bin-net20 folder that is situated as /lib/native.dll, you'd add the following in your MSBuild file in the AfterBuild target:

<Target Name="AfterBuild">
  <Message Text='[built(bin-net20, "lib\native.dll")]' />
</Target>

Changing the default package location

If you want a project to compile to a specific folder in your package and not in the default /bin, you can do so by updating your .csproj add add an OpenWrap-ExportName property. For example, to put the compiled assembly in the commands folder, you can add the following.

<PropertyGroup>
  <OpenWrap-ExportName>commands</OpenWrap-ExportName>
</PropertyGroup>

Supporting nant, rake and other build tools

Other build tools are also supported by providing custom command-line tools. You can configure your own tool by using a command instruction.

build: command; path=tools\nant\nant.exe; args=argsToTool

In your build, you now only need to output a message in the format [built(targetExport,pathToFile)] to include any file you may want in a custom folder. Note that the descriptor and version files will be copied in the correct location automatically so you don't need to copy those.

Adding files individually

If you cannot the command builder, and prefer a manual step, you can use the files build provider.

build: files; file=targetExport -> path\to\file

This will copy the file at path\to\file in the folder named targetExport. As with the command-driven tool, the descriptor and version files will be copied automatically.

Custom build provider

It's possible to provide a custom build provider, which is a type implementing the IPackageBuilder interface.

build: custom;typeName=Type,Assembly

Any property provided as part of the build will get assigned to public instance properties on that type. The following attributes provided to the build-wrap command will be automatically converted on to properties with a corresponding name when they exist:

• -Incremental
• -Configuration (with -Debug and -Release setting the -Configuration property to the strings Debug and Release respectively).