• PackageDoc

• This is a description of the XML configuration file for the Packager

• The packager is a glorified file copy and Zip (also .tar.gz) program. It copies files from the source directory to a target directory and optionally zips (or .tar.gz's) them.

• Files are always copied to a temporary directory. This allows the source tree to be altered without affecting the source files. Files can be deleted or arranged into different folders. (come to think of it, renaming should also be a supported feature, but this can be achieved via <Destination>)

• This document can contain BuildRobotExpressions; for example, to refer to environment variables

• If the packager is executed via the BuildRobot, it is possible reference build robot variables like $options via the "cfgmgmt::build" package, e.g., $cfgmgmt::build::options{Sandbox}

• The packager is typically invoked via the BuildRobot via the BuildDoc, in which case the ConfigMapDoc also applies

• This information is accurate for 1.8.2 and later. This documentation is no longer accurate for previous versions of the toolkit.

• See the PackageDocExamples.

<Package-Doc>

<FTP> Sets FTP settings so that files can be posted to an FTP server.

• FTP elements can appear anywhere in the document. All elements are optional -- they override each other sequentially. See an example.

• <Clear>1</Clear>

  • Clear the previous FTP settings

  <HostName> Provide the name of the FTP server to access

  </HostName>

  <UserName> Provide the user to log into the FTP server

  </UserName>

  <Password> Provide the password to use to log into the FTP server

  </Password>

  <HostPath> Provide the full path on the FTP server where the file should

  • be uploaded.

    Example: ="incoming/examples_$ENV{dg_bldno}.tar.gz" This example adds the environment variable dg_bldno to the filename

  </HostPath>

  <Timeout> Specify the connection and packet transmission timeout

  • in seconds. Defaults to 120.

  </Timeout>

</FTP>

<PSCP> Sets Putty SCP settings so that files can be posted

• to a secure FTP (SFTP) server via putty's PSCP (secure copy) program. PSCP elements can appear anywhere in the document. All elements are optional -- they override each other sequentially. Get pscp here and put it in your PATH.

  Warning: PSCP can hang if it's the first time you have initiated pscp against the particular host, or if the host changed its public key. This will cause automated processes to hang, and you're at the mercy of the SFTP server administrator to not change their public key file.

• <Clear>1</Clear>

  • Clear the previous PSCP settings

  <HostName> Provide the name of the SFTP server to access

  </HostName>

  <UserName> Provide the user to log into the SFTP server

  </UserName>

  <Password> Provide the password to use to log into the SFTP server

  </Password>

  <HostPath> Provide the full path on the SFTP server where the file should

  • be uploaded.

    Example: ="incoming/examples_$ENV{dg_bldno}.tar.gz" This example adds the environment variable dg_bldno to the filename

  </HostPath>

</PSCP>

<CVS> Sets CVS settings. This element can appear anywhere

• in the document. All elements are optional -- they override each other sequentially. The packager can check out files from CVS and can also commit to CVS (and can also commit new files). See CVSWebSync.

• <CVSModule> Provide the name of the CVS module to retrieve or commit into

  </CVSModule>

  <CVSROOT> Provide the CVS login path. If omitted, the CVSROOT

  • directory is used

  </CVSROOT>

  <Tag> Provide the name of the CVS tag to use when checking

  • out files

  </Tag>

• <CommitMessage> Provide the text to use when committing files (1.8.2.13 and later)

  </CommitMessage>

  <Clear>1</Clear> Clear previous CVS settings

</CVS>

<GroupBegin/> Marks the beginning of a group. Can appear anywhere in

• the document. A group allows you to create a zip (or .tar.gz) file containing other files created/copied by the packager. This is more easily described via an example.

<GroupEnd/> Marks the end of a group. Can appear anywhere in the document.

• This element must contain no text or sub-elements.

<Module> A module is a set of related files

• Multiplicity: * There is a bug preventing multiple modules in the same file

  Name of the module

• <Description> The description of the module

  • Multiplicity: 0,1

  </Description>

  <Project> Specify the name of a project - the project

  • is used to determine directory names for $d in 'filespec.' The <Filespec>s listed in this project are relative to the path of the DevStudio project.

    The project can be a DSW file - if so, all projects in the workspace are processed.

    If the files to copy don't have a DevStudio project, you can specify a path name and the entire path will be used as the location of the <Filespec>s

  • <Description>

    • The description of the project Multiplicity: 0,1

    </Description>

    <Exclude> Specify a project to exclude from the build. If

    • a project is not given, the entire project entry will be excluded. Project names should be relative to the sandbox.

      Multiplicity: *

    </Exclude>

    <Source>

    • <Type> Classifies the filespec.

      • This contains one of the following values:

        • Intermediate - All intermediate files Development - PDB files Release - EXEs, DLLs, etc.

        Multiplicity: 1..*

      </Type>

      <Description> The description of the files

      • Multiplicity: 0,1

      </Description>

      <Once>1</Once> Only process this element once, even when

      • multiple configurations are specified

        Multiplicity: 0,1

      <CVS>1</CVS> Retrieve files from CVS into the destination.

      • Can contain sub-elements (see above) -- if previous <CVS> elements appear in the document, they will be used. Checks out the module specified in the <CVSModule> element using the tag specified in the <Tag> element.

        After checking out files and completing all other tasks, the packager returns to the root of the destination path and invokes "cvs commit" using the comment "CVSWebsync is updating files."

        Do not specify a <Filespec> -- it will be ignored.

        Multiplicity: 0,1

      <Filespec> List a filespec, which may contain wildcards,

      • of the file(s) to copy, relative to the "sandbox" directory.

        See also PackageDocExamples.

        If the filespec starts with a backslash, or if the second character is a colon, the filespec is assumed to be an absolute path. This is useful for copying external DLLs.

        If the filespec is a directory name and ends with a slash, the rightmost directory name will be the root directory of the copied file, relative to the <Destination> tag if given. Use dirname/* if you want to "hide" dirname.

        The $ expressions as described in BuildRobotExpressions are not accepted here. Use = expressions instead.

        Use "$t" to specify the target of the project, including the directory. Shorthand for $d$n$e.

        Use "$d" to specify the directory containing target files. Ends with a directory slash character.

        Use "$i" to specify the directory containing intermediate files. Ends with a directory slash character.

        Use "$n" to specify the name of the target without any directory or extension.

        Use "$e" to specify the extension starting with a period.

        Use "$s" to specify the directory where the source files are located. Ends with a directory slash character.

        Multiplicity: 1..*

      </Filespec>

      <Destination> List a filespec, where the files should be copied to,

      • relative to the "destination" directory given as a script parameter.

        If it starts with a slash, backslash, or dot, or if the second character is a colon, the path is assumed to be an absolute path, which will cause files to be copied to the specified path.

        You may also use this element to control where files are stored in a ZIP archive. For example, if you specify "exe" and the filespec is source/foo/bar/*.exe, foo.exe will be stored in the archive as exe/foo.exe.

        This element may also appear inside <Filespec>.

        Multiplicity: 0,1

      </Destination>

      <NoSandbox>1</NoSandbox>

      • The file listed in <Filespec> are not relative to the sandbox -- use the filespecs literally. Generally this is not needed but is provided in case the absolute path detection mentioned above is not working.

        Multiplicity: 0,1

      <KeepDirectoryStructure>1</KeepDirectoryStructure>

      • Keep the directory structure of the copied files as they are in the sandbox. This is intended for zipping up OBJ, EXE, etc. files for debug builds.

        This element may also appear inside <Filespec>.

        Multiplicity: 0,1

      <Recursive>1</Recursive>

      • Instructs the script to copy files in the sub-directories. If Tar is used, recursiveness is the default.

        This element may also appear inside <Filespec>.

        Multiplicity: 0,1

      <Delete> Files are copied from the source directory to

      • a temporary directory and then copied or archived to the destintion directory.

        This element causes the specified file paths to be deleted from the temp directory after files are copied there.

        Can be a file specfication including wildcards. If a directory matches the filespec, it is removed, along with its contents.

        Multiplicity: *

      • <Recursive>1</Recursive>

        • Delete these paths in subdirectories recursively

      </Delete>

      <DeleteDir> Files are copied from the source directory to

      • a temporary directory and then copied or archived to the destintion directory.

        This element causes the specified directory and its contents to be removed from the temp directory after files are copied there.

        This is similary to <Delete> with <Recursive>1</Recursive> but <DeleteDir> doesn't accept wildcards.

        Multiplicity: *

      </DeleteDir>

      <FTP>1</FTP> Upload the file via FTP protocol to a remote server.

      • See above for additional FTP subelements that can appear here. If <Filespec> resolves to multiple filenames and <Zip> is not provided, <FTP> will not do anything.

        Multiplicity: 0,1

      <PSCP>1</PSCP> Upload the file via SFTP protocol to a remote server.

      • See above for additional PSCP subelements that can appear here. If <Filespec> resolves to multiple filenames and <Zip> is not provided, <PSCP> will not do anything.

        Multiplicity: 0,1

      <Tar>1</Tar> Create a TAR archive. If <Zip>1</Zip> element is also specified,

      • use gzip to compress the archive.

        Provide the name of the archive, 1 to enable, or 0 to disable. Multiplicity: 0,1

      • 1.8.0 and later only

      <Zip> Add the files to a ZIP archive. Set the element

      • text to 1 to use a default file or specify the name of the archive file.

        If <Zip> is specified in the BuildDoc, and <Zip> is not specified in PackageDoc, the <Zip> in the BuildDoc is used. Otherwise, this element overrides the <Zip> in BuildDoc.

        It isn't possible to create directories in Zip archives that contain no files or folders. You must also use the <Tar> element if you want empty folders in a compressed archive.

        Multiplicity: 0,1

      • <Erase>1</Erase>

        • Erase the Zip file before adding files Multiplicity: 0,1

        <Store>1</Store>

        • Add the files without any compression.

        <Compression>

        • Provide the level of compression, where 0 means no compression and 9 means maximum compression. See <DefaultZipCompression> in BuildOptionsDoc.

          Multiplicity: 0,1

        </Compression>

      </Zip>

    </Source>

  </Project>

</Module>

</Package-Doc>