Packaging

Overview

The packager, dgpackage.exe or dgpackage.pl, is a file copy utility.  It copies files to a specified location.   The destination can be a drive path or it can be a Zip archive.

The packager can be used to:

• Copy all DLLs, EXEs, etc. to a "release tree" for testing
  • The release tree is optional.  Since COM objects "live" anywhere on a filesystem, developers can run the product directly from their private development directories.
• Zip up all components so they can be distributed over the intranet
• Copy web files (HTML, etc.) that are in development to an internet server for testing
• Prepare an installation directory to be consumed by programs like InstallShield.   This is essential for automating the creation of Setup programs.

Packages are described with an XML document.   Developers can create as many of these documents they need and save them anywhere in the source tree.

The packager also refers to a configuration document which specifies various attributes for projects.

For example, the build robot can execute a script which builds setup.exe.  You can then tell the packager to copy setup.exe to the build web page.  The build web page will contain a hyperlink to setup.exe.

The packager can extract target information from Microsoft Developer Studio files (SLN*, VCPROJ, DSP, and DSW).  This allows the build robot to zip up all DLLs, EXEs, etc. without requiring the end-user to type in the path names.  This means that if you add a new project to a SLN file, you don't have to modify any build robot configuration.  (*SLN support currently only works for VCPROJ projects).  This functionality is useful for developers to quickly download build artifacts.  It is not, however, a replacement for a setup program.

Examples -- Packaging Files Produced by the Build Robot

Copying all files in source/sql to an external file share \\star\nightly\sql, unzipped

• package_sql.xml consists of:
  <Package-Doc>
  <Module>
    <Project>
      <Source>
        <Filespec>source/sql/*.*</Filespec>
        <!-- This is the subdir to write to,
             relative to the <Destination> in the
             <BuildDoc> document -->
        <Destination>sql</Destination>
        <Recursive/> <!-- Copy subdirectories too -->
      </Source>
    </Project>
  </Module>
</Package-Doc>
• The build XML file contains:
  <Package>build/package_sql.xml
    <Destination>\\star\nightly</Destination>
</Package>

Packaging Setup.exe, unzipped

• The package file build/package_install.xml contains:
  <Project>source/install/myinstaller
  <Source>
    <Filespec>source/install/myinstaller/output/setup.exe</Filespec>
  </Source>
</Project>
• The build XML file contains:
  <Package>build/package_install.xml
    <Configuration>Win32 Unicode Release</Configuration>
    <Project>source/install/myinstaller</Project>
    <Copy/>
    <LinkName>My Installer -- Setup.exe</LinkName>
</Package>
• Note the use of <Copy/> rather than <Zip/>

Packaging Setup.msi, unzipped

• The package file build/package_install.xml contains:
  <Project>source/install/myinstaller
  <Source>
    <Filespec>source/install/myinstaller/output/setup.exe</Filespec>
  </Source>
</Project>
• The build XML file contains:
  <Package>build/package_install.xml
    <Configuration>Win32 Unicode Release</Configuration>
    <Project>source/install/myinstaller.sln</Project>
    <Copy/>
    <Filespec>$t</Filespec>
    <LinkName>My Installer</LinkName>
</Package>
• By providing the configuration name, the MSI file is copied once rather than once for each configuration
• If the sln file contains multiple projects and you only want to copy the targets from a subset of the projects contained in the MSI file, specify the project names (as their path names relative to the sandbox e.g., source/c/cat/cat.vdproj) in additional <Project> tags (one tag per project name).
• Note the use of <Copy/> rather than <Zip/>

Zipping all DLLs, EXEs, and PDBs (debugging info) produced by a VC++ DSW or vs.NET SLN file

• You don't have to list all of the projects in the workspace -- what a tedious process!
• The packager's support for SLN and DSW files only applies to C++ projects
• The package file build/package_net.xml consists of:
  <Package-Doc>
  <Module>
    <Project>build/utils.sln
      <Source>
        <Filespec>$t</Filespec>
        <Filespec>$d$n.pdb</Filespec>  
        <KeepDirectoryStructure/>
      </Source>
    </Project>
  </Module>
</Package-Doc>
• The build XML file contains:
  <Package>build/package_net.xml
    <Configuration>Win32 Unicode Release</Configuration>
    <Configuration>Win32 Unicode Debug</Configuration>
    <Zip/>
</Package>