du_tool

Create and manage deployment units

Applicability


Product	Command type
ClearCase®	Perl script


Platform
Windows
Linux
UNIX

Synopsis

du_tool.pl --generate
             --directory staging-dir [[--directory staging-dir]...]
             --name release-name --version release-version
             [--tag dynamic-view-tag | --pname snapshot-view-pname]
             [--out output-file]

du_tool.pl { --decorate [--instance instance-id]
               [[--baseline baseline-text]...]
               [[--logvendor vendor] [--buildlog log-file]...]
             | --resolve
             }
             [--tag dynamic-view-tag | --pname snapshot-view-pname]
             [--out output-file]
             [input-file]

du_tool.pl --verify [input-file]

Description

The du_tool Perl script is a command-line utility that is supported in environments running either base ClearCase or Unified Change Management (UCM). The du_tool utility must be invoked using ratlperl on a ClearCase client host from which named views and VOBs are accessible.

The following table lists operations that can be run on deployment units using du_tool.

Table 1. du_tool operations
Operation	Command-line argument	Description
Generate	–generate	Searches through one or more directory trees within one or more VOBs and generates a deployment unit template XML file that consists of entries for each file found.
Decorate	–decorate	Creates a deployment unit XML file from the deployment unit template, and adds the following information to the file: VOB object references (OREFs) to the files listed in the deployment unit The config spec of the view in which the decorate option was run The specific config spec rule that selected the versions in your VOB that are selected by the decorate option The names of the registry server and registry region of the machine on which the decorate operation was run A history element indicating that the decorate option has been run on the deployment unit template
Resolve	–resolve	Is run at deployment time to resolve the OREFS in a deployment unit to version-extended pathnames.
Verify	–verify	Verifies that a deployment unit template is in valid XML format. If you have created your deployment unit template file by means other than running du_tool –generate, you can use this option to verify that the files consist of well-formed XML.

Additional options and arguments

Specifying which VOB directory trees to search
The following option enables you to specify one or more directory trees in one or more VOBs in which you want du_tool to search for files that will be deployed. This option is required and only valid for the du_tool –generate command.
–directory
You must specify at least one VOB directory tree in which you want du_tool to search for files that you want to deploy. You can specify multiple directories as needed.
Specifying a view context
When running the du_tool –generate, –decorate, or –resolve commands, you must either be in a view context or specify a view context using the following options. A view context is not required for the du_tool –verify command.
–tag
This option is used to specify the tag of a dynamic view in which you want to run du_tool.
–pname
This option is used to specify the pathname to a snapshot view in which you want to run du_tool.
Specifying information about your release
The following options can be used with the du_tool –generate and –decorate commands to enter information about your release, such as the release's name, version, instance ID, and baselines, into a deployment unit. You must specify these options using the appropriate quoting syntax for the shell you are running.
–name
This option is required for the du_tool –generate command; it is not valid when running du_tool with other command-line options. This option is used to specify the name of your release, which gets noted in your deployment unit template file.
–version
This option is required for the du_tool –generate command; it is not valid when running du_tool with other command-line options. This option is used to specify the version of the release that you specified using the –name option.
–instance
This argument is optional for the du_tool –decorate command; it is not valid when running du_tool with other command-line options. This option can be used to specify an additional ID for a particular decorated instance. You can use this argument multiple times to specify multiple IDs.
–baseline
This argument is optional for the du_tool –decorate command; it is not valid when running du_tool with other command-line options. This option can be used to specify the name of a baseline, which gets noted in your deployment unit XML file. This option can be specified multiple times to specify multiple baselines; for example, you could use this option multiple times to describe all constituent baselines in a composite baseline.
Specifying an output file name
The following option enables you to specify an output file name when running du_tool with supported command-line options other than –verify.
–out
This option is optional for commands other than du_tool –verify. This option can be used to specify the name of the output file resulting from running the du_tool –generate, – decorate, or –resolve commands. If a value is not specified for this option, the results of the du_tool command are directed to STDOUT.
Specifying information about your build
The following options can be used with du_tool to enter information about your build into a deployment unit, such as the location in your VOB of the build log and the name of the vendor of your build software. These options must be used with one another; they are not valid when used alone.
–buildlog
This argument is optional for the du_tool –decorate command; it is not valid when running du_tool with other command-line options. This option can be used to specify the location of a build audit log that has been checked in to your VOB. It can be specified multiple times to specify multiple build logs.
–logvendor
This argument is optional for the du_tool –decorate command; when running du_tool with other command-line options. This option can be used to specify the vendor of the software that you are using to perform builds.

Restrictions

You must invoke du_tool using ratlperl; du_tool will not work with other versions of Perl.
du_tool must be run on a machine accessible by ClearCase views and VOBs.
du_tool works with dynamic and snapshot views only. Web views are not supported.

Examples

Generating a deployment unit template

In the following example, a list of files to be built and deployed is captured by running the du_tool –generate command. This command creates a deployment unit template XML file, myApp_du_template.xml, that lists all files in \testvob\shlib to be deployed:

Z:\test_vob\shlib>ratlperl "\Program Files\DevOps\Code\ClearCase\etc\du_tool.pl" 
--generate --directory \test_vob\shlib --name "My Test App" --version 1.0 
 --out myApp_du_template.xml
Z:\test_vob\shlib>more myApp_du_template.xml

<?xml version="1.0" encoding="UTF-8"?>
<tracking:deploymentUnit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:tracking="http://www.ibm.com/deployment/schema/deploymentTracking.xsd" 
name="My Test App" version="1.0">
    <file path="\test_vob\shlib\foo.so" origPath="foo.so" />
    <file path="\test_vob\shlib\bar.so" origPath="bar.so" />
    <file path="\test_vob\shlib\baz.so" origPath="baz.so" />
    <file path="\test_vob\shlib\linked_foo.txt" origPath="linked_foo.txt" />
    <history changeOperation="Generate" changeNote="" user="deployment_engr" 
hostname="melamine.lexma.ibm.com" datetime="2005-11-11T15:05:04-05:00" />
</tracking:deploymentUnit>

Add your deployment unit template file to version control by checking it into your VOB.

Verifying a deployment unit template
Run du_tool to verify that your deployment unit template consists of valid XML only if you have created it by means other than running du_tool –generate. If you use du_tool –generate to create your deployment unit template, the template is guaranteed to be in valid XML format.
The following example shows how to run du_tool –verify to verify a deployment unit template:
```
Z:\testvob\shlib>ratlperl "\Program Files\DevOps\Code\ClearCase\etc\du_tool.pl" 
--verify myApp_du_template.xml
```

Decorating a deployment unit

In the following example, a deployment unit called myApp_du.xml is created from the template file myApp_du_template.xml by running the du_tool –decorate command:

Z:\test_vob\shlib>ratlperl "\Program Files\DevOps\Code\ClearCase\etc\du_tool.pl" 
--decorate --instance build_20051102 --baseline some_baseline --logvendor "ISV" 
--buildlog \test_vob\build_log_20051102.txt 
--buildlog \test_vob\build_log_20051102_secondary.txt 
--out myApp_du.xml myApp_du_template.xml
Z:\test_vob\shlib>more myApp_du.xml

<?xml version="1.0" encoding="UTF-8"?>
<tracking:deploymentUnit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
instanceID="build_20051102-20051111150819-0500" version="1.0" name="My Test App" 
xmlns:tracking="http://www.ibm.com/deployment/schema/deploymentTracking.xsd">
    <file path="\test_vob\shlib\foo.so" versionURI="ccase:/vobs/test_vob/shlib/foo.so?
OREF=oid%3A286b43cd.291e11da.8af5.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=at1_r_d_unc" csrule="\main\LATEST" 
origPath="foo.so" />
    <file path="\test_vob\shlib\bar.so" versionURI="ccase:/vobs/test_vob/shlib/bar.so?
OREF=oid%3A290b43d9.291e11da.8af5.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=at1_r_d_unc" csrule="\main\LATEST" 
origPath="bar.so" />
    <file path="\test_vob\shlib\baz.so" versionURI="ccase:/vobs/test_vob/shlib/baz.so?
OREF=oid%3A290b43e5.291e11da.8af5.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=at1_r_d_unc" csrule="\main\LATEST" 
origPath="baz.so" />
    <file path="\test_vob\shlib\linked_foo.txt" 
versionURI="ccase:/vobs/test_vob/shlib/linked_foo.txt?
OREF=oid%3A70f083b0.29e611da.8b9b.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=at1_r_d_unc" csrule="\main\LATEST" 
origPath="linked_foo.txt" />
    <CCOrigin>
        <baseline baselineName="some_baseline" originAuthority="UserProvided" />
        <configSpec>
            element * CHECKEDOUT
            element * /main/LATEST
        </configSpec>
    </CCOrigin>
    <buildOrigin>
        <buildLog path="\test_vob\build_log_20051102.txt" 
versionURI="ccase:/vobs/test_vob/build_log_20051102.txt?
OREF=oid%3A142327c7.4bac11da.8678.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=at1_r_d_unc" vendor="ISV" />
        <buildLog path="\test_vob\build_log_20051102_secondary.txt" 
versionURI="ccase:/vobs/test_vob/build_log_20051102_secondary.txt?
OREF=oid%3A4bcddb45.4d4411da.87b4.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=at1_r_d_unc" vendor="ISV" />
    </buildOrigin>
   < history changeOperation="Decorate" changeNote="" user="deployment_engr" 
hostname="melamine.lexma.ibm.com" datetime="2005-11-11T15:08:19-05:00" />
    <history changeOperation="Generate" changeNote="" user="deployment_engr" 
hostname="melamine.lexma.ibm.com" datetime="2005-11-11T15:05:04-05:00" />
</tracking:deploymentUnit>

Add your deployment unit file to version control by checking it into your VOB.

Resolving a deployment unit

In the following example, version-extended pathnames of the files that you want to deploy are added to the deployment unit file by running the du_tool –resolve command. This enables the versions of the files that are being deployed to be tracked throughout the deployment lifecycle:

Z:\test_vob\shlib>ratlperl "\Program Files\DevOps\Code\ClearCase\etc\du_tool.pl" 
--resolve --out myApp_du_resolved.xml myApp_du.xml
Z:\test_vob\shlib>more myApp_du_resolved.xml
<?xml version="1.0" encoding="UTF-8"?>
<tracking:deploymentUnit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
instanceID="build_20051102-20051111150819-0500" version="1.0" name="My Test App" 
xmlns:tracking="http://www.ibm.com/deployment/schema/deploymentTracking.xsd">
    <file path="\test_vob\shlib\foo.so" versionURI="ccase:/vobs/test_vob/shlib/foo.so?
OREF=oid%3A286b43cd.291e11da.8af5.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=at1_r_d_unc" 
xname="\test_vob\shlib\foo.so@@\main\0" csrule="\main\LATEST" origPath="foo.so" />
    <file path="\test_vob\shlib\bar.so" versionURI="ccase:/vobs/test_vob/shlib/bar.so?
OREF=oid%3A290b43d9.291e11da.8af5.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=at1_r_d_unc" 
xname="\test_vob\shlib\bar.so@@\main\0" csrule="\main\LATEST" origPath="bar.so" />
    <file path="\test_vob\shlib\baz.so" versionURI="ccase:/vobs/test_vob/shlib/baz.so?
OREF=oid%3A290b43e5.291e11da.8af5.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=at1_r_d_unc" 
xname="\test_vob\shlib\baz.so@@\main\0" csrule="\main\LATEST" origPath="baz.so" />
   < file path="\test_vob\shlib\linked_foo.txt" 
versionURI="ccase:/vobs/test_vob/shlib/linked_foo.txt?
OREF=oid%3A70f083b0.29e611da.8b9b.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=at1_r_d_unc" 
xname="\test_vob\foo.txt@@\main\1" csrule="\main\LATEST" origPath="linked_foo.txt" />
    <CCOrigin>
        <baseline baselineName="some_baseline" originAuthority="UserProvided" />
        <configSpec>
            element * CHECKEDOUT
            element * /main/LATEST
        </configSpec>
    </CCOrigin>
    <buildOrigin>
        <buildLog path="\test_vob\build_log_20051102.txt" 
versionURI="ccase:/vobs/test_vob/build_log_20051102.txt?
OREF=oid%3A142327c7.4bac11da.8678.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=at1_r_d_unc" vendor="ISV" />
        <buildLog path="\test_vob\build_log_20051102_secondary.txt" 
versionURI="ccase:/vobs/test_vob/build_log_20051102_secondary.txt?
OREF=oid%3A4bcddb45.4d4411da.87b4.00%3A01%3A80%3Aa6%3Ad4%3A39%40
vobuuid%3Aaf2b2c77.291a11da.8ae0.00%3A01%3A80%3Aa6%3Ad4%3A39&
registry_server=melamine.lexma.ibm.com&region=at1_r_d_unc" vendor="ISV" />
   < /buildOrigin>
    <history changeOperation="Resolve" changeNote="" user="deployment_engr" 
hostname="melamine.lexma.ibm.com" datetime="2005-11-11T15:11:54-05:00" />
    <history changeOperation="Decorate" changeNote="" user="deployment_engr" 
hostname="melamine.lexma.ibm.com" datetime="2005-11-11T15:08:19-05:00" />
   < history changeOperation="Generate" changeNote="" user="deployment_engr"
 hostname="melamine.lexma.ibm.com" datetime="2005-11-11T15:05:04-05:00" />
</tracking:deploymentUnit>