CI Factory - How to Create Packages

Latest Content
Packages Anatomy Branch Creation Workspace Wix VSTSVersionControl

Popular
Installation Introduction Unable to load DLL svn_client-1 HRESULT: 0x800736B1 Power Tools Anatomy MSBuild

Home

Packages Documentation

How to Create Packages

Live Build Dashboard

Most Recent Changes

Blogs

CI Factory is in Windows Developer Power Tools

How to Create Packages

PDF

Print

How to Create Packages

CI Factory packages generally consist of a NAnt script and Xslt for producing dashboard reports. They are contained in a directory located in C:\Projects\<Project Name>\<Code Line Name>\Build\Packages\<Package Name>. Lets take a look at the Package MSBuild to get an idea of all the moving parts.

There is always a Something.Targets.xml file and most times a Something.Properties.xml file. The properties files is the ONE that a user could edit to alter the behavior of the Package. It is preferred that a user not have to edit the target file. You may have noticed that I did not refer to the files like <Package Name>.Target.xml and <Package Name>.Properties.xml. This is because CI Factory makes use of indirection to increase flexibility. This allows several packages to use the name Compile.Target.xml. This in itself does not do much, the file naming is used to signal that the package contains shared target and property names; similar to polymorphism. The VS.NETCompile package also contains a file named Compile.Target.xml.

The bin directory contains the MSBuild Xml logger. Other packages that have resources that are specific to that package have bin folders too. Some of the packages have NAnt task assemblies in a bin folder. They are loaded with the task loadtasks.

There are several Xslt files in the MSBuild package. Two are for generating html in the CCNet dashboard. The other is used in a CCNet server Xsl merger publisher task. Currently there are three types of dashboard Xsl plugins: one for the main build report (processing the build log), one for creating dedicated build reports (again processing the build log), and one more for creating dedicated build reports (processing any file in the Artifact directory). See the dashboard.config bellow.

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

<dashboard>

  <remoteServices>

    <servers>

      <server name="TestProject" url="tcp://localhost:21236/CruiseManager.rem" />

    </servers>

  </remoteServices>

  <plugins>

    ...

    <buildPlugins>

      <buildReportBuildPlugin>

        <xslFileNames>

          <xslFile>xsl\header.xsl</xslFile>

          <xslFile>xsl\modifications.xsl</xslFile>

          <xslFile>xsl\compile.xsl</xslFile>

          <xslFile>Packages\MSBuild\compile-msbuild.xsl</xslFile>

        </xslFileNames>

      </buildReportBuildPlugin>

      <buildLogBuildPlugin />

      <xslReportBuildPlugin description="NAnt Output" actionName="NAntOutputBuildReport" xslFileName="xsl\Nant.xsl" />

      <artifactXslBuildPlugin description="MSBuild Compile Details" actionName="MSBuildCompileDetails" xslFileName="Packages\MSBuild\msbuild.xsl" artifactRootUrl="/TestProject Artifacts" xmlFileName="MSBuildLog.xml" />

    </buildPlugins>

  </plugins>

</dashboard>

See in the screen shot below The section named Compiler Warnings. It is generated by compile-msbuild.xsl.
Also see the links on the left menu: NAnt Output and MsBuild Compile Details.

To produce these reports there also needs to be Xml in either the build log or a file in the Artifact directory. To get xml into the build log you have at least 3 means at your disposal; the echo task in the NAnt script, the xml file merger publication task, and the xsl file merger publication task. See the snippet taken from the publishers section of the CCNet project file.

<merge>

  <files>

    <file>c:\Projects\TestProject\Current\Build\SimianReport\SimianReport.xml</file>

  </files>

</merge>

<xslmerger>

  <filepairs>

    <filepair>

      <xslfile>C:\Projects\TestProject\Current\Build\Packages\MSBuild\MSBuildMerge.xsl</xslfile>

      <xmlfile>c:\Projects\TestProject\Current\Build\CompileLogs\*.xml</xmlfile>

    </filepair>

  </filepairs>

</xslmerger>

<xmllogger />

To publish a file to the Artifact directory you can do one of two things: write the file directly to Artifact directory or copy it there. The Deployment Package has serveral targets to help you publish to the Artifact directory. Some of them have the added bonus of having a download link created for them in the Deployment File(s) section of the main build report (it uses the echo means to communicate the href info to the xsl). If you wish to handle publishing a file yourself the following properties will be of interest to you:

ArtifactRootDirectory = C:\Projects\${ProjectName}\${ProjectCodeLineName}\Build\Artifacts
Common.ArtifactFolderName = a number - yyyymmddhhmmss
Common.ArtifactDirectoryPath = ${ArtifactRootDirectory}\${Common.ArtifactFolderName}
Deployment.WebPathRoot = /${ProjectName} Artifacts

To have anything at all to merge, publish, or echo we need to have a target in the Something.Target.xml file executed. The Main.Build.xml and Post.Build.xml are your to main possibilities; both follow the same format. See the highlights in the Main.Build.xml file below (... denotes a collapsed region).

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

<project xmlns="http://nant.sf.net/schemas/nant.xsd" name="Main Build" default="Triggered">

  <include buildfile="Properties.build.xml"/>

  <include buildfile="Common.Build.xml" />

  <description>Begin Package Includes</description>

  ...

  <include buildfile="${PackagesDirectory}\MSBuild\Compile.Target.xml" />

  <description>End Package Includes</description>

  <target name="Triggered" depends="SetUps" >

    <trycatch>

      <try>

        <description>Begin Main Build</description>

        <description>Begin Pre Build Actions</description>

        ...

        <description>End Pre Build Actions</description>

        <description>Begin Clean Up Actions</description>

        ...

        <description>End Clean Up Actions</description>

        <description>Begin Compile Actions</description>

        <call target="Compile.CompileSource" />

        <description>End Compile Actions</description>

        <description>Begin Varification Actions</description>

        ...

        <description>End Varification Actions</description>

        <description>Begin Post Build Actions</description>

        ...

        <description>End Post Build Actions</description>

        <description>End Main Build</description>

      </try>

      <finally>

        <call target="TearDowns"/>

      </finally>

    </trycatch>

  </target>

  <target name="SetUps" >

    <call target="Common.SetUp" />

    <description>Begin SetUps</description>

    ...

    <call target="Compile.SetUp"/>

    <description>End SetUps</description>

  </target>

  <target name="TearDowns">

    <description>Begin TearDowns</description>

    ...

    <call target="Compile.TearDown"/>

    <description>End TearDowns</description>

  </target>

</project>

Beyond reporting you will be interested in knowing the properties defined in the file Properties.Build.xml and Common.Build.xml located in the Build directory. These properties will help you write a robust Package.

To get your Package installed into a Factory you have two options. You can write and installer or you can have users perform a manual deployment. Writing and installer is not that much work. In your package create a directory named Install. in it create at least these two file: Install.xml and Properties.xml Here is an example Install.xml:

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

<project xmlns="http://nant.sf.net/schemas/nant.xsd" name="MSBuild.Install" default="MSBuild.Install">

  <include buildfile="Properties.xml" />

  <property name="Compile.SolutionFile" value="${ProductDirectory}\${ProjectName}.sln"/>

  <property name="Compile.OpenSolutionBat" value="${ProductDirectory}\OpenSolution.bat"/>

  <property name="Compile.Default2005SolutionFile" value="${SourcePackagesDirectory}\MSBuild\Install\2005.sln.remove"/>

  <property name="Compile.DefaultOpenSolutionBat" value="${SourcePackagesDirectory}\MSBuild\Install\OpenSolution.bat"/>

  <target name="MSBuild.Install">

    <largeproperty name="Packages.AddCompileActions.Block">

      <value xml="false"><![CDATA[<call target="Compile.CompileSource" />]]></value>

    </largeproperty>

    <call target="Packages.AddCompileActions"/>

    <copy file="${Compile.Default2005SolutionFile}" tofile="${Compile.SolutionFile}"/>

    <copy tofile="${Compile.OpenSolutionBat}" file="${Compile.DefaultOpenSolutionBat}">

      <filterchain refid="Common.FilterChain" />

    </copy>

    <largeproperty name="Packages.AddbuildReportBuildPlugin.Block">

      <value xml="false"><![CDATA[<xslFile>Packages\MSBuild\compile-msbuild.xsl</xslFile>]]></value>

    </largeproperty>

    <call target="Packages.AddbuildReportBuildPlugin"/>

    <largeproperty name="Packages.AddbuildPlugins.Block">

      <value xml="false" expand="true"><![CDATA[<artifactXslBuildPlugin
description="MSBuild Compile Details"
actionName="MSBuildCompileDetails"
xslFileName="Packages\MSBuild\msbuild.xsl"
artifactRootUrl="/${ProjectName} Artifacts"
xmlFileName="MSBuildLog.xml" />]]></value>

    </largeproperty>

    <call target="Packages.AddbuildPlugins"/>

    <largeproperty name="Packages.AddXslMerger.Block">

      <value expand="true">

        <![CDATA[<filepair>

            <xslfile>${PackagesDirectory}\MSBuild\MSBuildMerge.xsl</xslfile>

            <xmlfile>${Compile.LogFileDirectory}\*.xml</xmlfile>

          </filepair>]]></value>

    </largeproperty>

    <call target="Packages.AddXslMerger"/>

  </target>

  <target name="MSBuild.SetAsCurrentPackage">

    <property name="Packages.CurrenctPackage.PackageDirectoryName" value="MSBuild"/>

    <property name="Packages.CurrenctPackage.PackageTargetFileName" value="Compile.Target.xml"/>

    <property name="Packages.CurrenctPackage.PackageName" value="Compile"/>

  </target>

  <target name="MSBuild.ValidateParameters">

  </target>

</project>

Notice there are three targets defined, they are required: <package name>.Install, <package name>.SetAsCurrentPackage, and <package name>.ValidateParameters. If your package has values that must be set by a user then you should validate they they where set in the validate parameters target. In the SetAsCurrentPackage target you need to set at least the properties listed above: Packages.CurrenctPackage.PackageDirectoryName, Packages.CurrenctPackage.PackageTargetFileName, and Packages.CurrenctPackage.PackageName. If your package is one that is not invoked by the Main.Build.xml file then you need to set the value of the Current.BuildFile property to the correct build file (e.g. Post.Build.xml). In the Install target you can call on helper targets defined in the script Properties.Install.xml located in the Install scripts directory. These helper targets allow you to add to the ccnetproject.xml, dashboard.config, and build files (e.g. Main.Build.xml). The targets follow a naming convention: Packages.<Section to Add to>. There is a companion property following the format: Packages.<Section to Add to>.Block. Notice for example the first lines in the Install target. The property Packages.AddCompileActions.Block companion target Packages.AddCompileActions. The base scripts will add the include, <package name>.SetUp, and <package name>.TearDown to the current build script. Your installer does not need to add them.

< Prev