enterprise automation - perforce€¦ · 8.0 tools for developers ... 1 stephen r. covey, the 7...

i

Enterprise Automation:

Canonical Automation

For The

Evolving Codebase

Vince Maiorana

Technical Lead / Supervisor SQA

Abstract

How does a startup company achieve enterprise-level automation during the development cycle in

an environment of rapidly changing software components? How do external tools surround

Perforce to create field-deployable products? How does the repository manage firmware,

hardware graphics, and software to enforce company-wide technical policies and procedures?

What role does the repository play to promote a successful interface to external manufacturing

policies?

This paper discusses the scripts, triggers, policies, procedures, and expert organizational tips on

how to achieve practical automation in a timely and cost-effective manner.

Although this implementation has its foundation on the ‘Wintel’ platform, the Perl, JScript, and

BATCH scripts are reasonably portable to other platforms.

Vince Maiorana, BlueShift Technologies, Inc. Enterprise Automation:

r1.1 Canonical Automation For The Evolving Codebase

ii

Table of Contents Table of Figures..............................................................................................................................iii

Table of Snippets ............................................................................................................................ iv

1.0 Introduction................................................................................................................................ 1 1.1 Definitions ............................................................................................................................. 1

2.0 Implementation .......................................................................................................................... 3 2.1 Enterprise Events................................................................................................................... 3 2.2 Implementation of Events...................................................................................................... 4

2.2.1 Build System Bootstrap .................................................................................................. 4 2.2.2 Build System Bootstrap Files ......................................................................................... 5 2.2.3 Build System Entry Point ............................................................................................... 6

3.0 Build System Execution............................................................................................................. 7 3.1.1 Secondary and Primary Meta-Commands ...................................................................... 8 3.1.2 Viewing Meta-Commands: The Trial Mode................................................................... 9 3.2.1 The BlueShift.bat Configuration File .................................................................. 9 3.2.2 The Build System Execution ........................................................................................ 10 3.2.3 Parameterized Directory Organization ......................................................................... 10

4.0 Manufacturing Process Support............................................................................................... 18

5.0 Perforce Triggers ..................................................................................................................... 22

6.0 Directory and Branch Architecture.......................................................................................... 23

7.0 Perforce BackUp...................................................................................................................... 30

8.0 Tools for Developers ............................................................................................................... 31

9.0 Tools for Test........................................................................................................................... 33 9.1 Perl Generation of C++ Code.............................................................................................. 33 9.2 Object Level Communication.............................................................................................. 34

10.0 Conclusion ............................................................................................................................. 34

Appendix Appendix A - Map of Components to Products............................................................................ A1 Appendix B - Trigger: Comment Checker.................................................................................... B1 Appendix C - Change List Notification........................................................................................ C1 Appendix D - BackUp Process ..................................................................................................... D1



iii

Table of Figures

Figure 2-1 Event Information for Staff Members............................................................................ 3 Figure 2-2 Build System Scheduled Tasks for Check-Out Report and Daily Build........................ 3 Figure 2-3 Build System Results for three ‘Nightly Build’ Scheduled Tasks ................................. 3 Figure 2-4 Build System Event Results for Perforce ‘Change’ Trigger .......................................... 4 Figure 2-5 Build System Software Prerequisites ............................................................................. 4 Figure 2-6 Bootstrap Build System File Flow ................................................................................. 5 Figure 2-7 Two Temporary Perforce Clients................................................................................... 5 Figure 3-1 Build System Interface................................................................................................... 7 Figure 3-2 C:\init Directory ........................................................................................................... 10 Figure 3-3 BlueShift.bat, Emacs Start-Up ..................................................................................... 10 Figure 3-4 Establishing the BlueShift.bat Environment ...................................................... 11 Figure 3-5 Establishing the Emacs Environment........................................................................... 11 Figure 3-6 Minimum Set of Meta-Commands............................................................................... 12 Figure 3-7 The ‘_Tools’ Client Completes Its Work..................................................................... 12 Figure 3-8 Partial ‘_Tools’ Client (Right Side) ............................................................................. 12 Figure 3-9 QAsystems Tool Set..................................................................................................... 13 Figure 3-10 QAtools Directory...................................................................................................... 13 Figure 3-11 Build System Action Scripts ...................................................................................... 14 Figure 3-12 Perforce Workspace Dynamic Client Results ............................................................ 15 Figure 3-13 Launch of the “unattended.js” Script ............................................................... 15 Figure 3-14 Build Failure Highlighted .......................................................................................... 16 Figure 3-15 The productRelease Directory.................................................................................... 17 Figure 4-1 AssemblyVersion3DEngine file................................................................................... 18 Figure 4-2 Plot of File Version Changes vs. Index of File ............................................................ 18 Figure 4-3 Version Identification Rule .......................................................................................... 19 Figure 4-4 Version Number Selection ........................................................................................... 19 Figure 4-5 Version Number Process E-mail.................................................................................. 19 Figure 4-6 Perforce Populates Product “bins” Upon Build Completion ....................................... 20 Figure 4-7 The “Main Line” and the “Current Line” .................................................................... 20 Figure 4-8 Manufacturing Support ................................................................................................ 21 Figure 5-1 Comment Prompt ......................................................................................................... 22 Figure 5-2 Comment Links to Bugzilla Issue #84......................................................................... 22 Figure 5-3 Product and Version Notification................................................................................. 23 Figure 6-1 Major Directories ......................................................................................................... 23 Figure 6-2 Position of User Branches............................................................................................ 24 Figure 6-3 Branch Architecture ..................................................................................................... 24 Figure 6-4 Directory/Branch Architecture..................................................................................... 26 Figure 6-5 Shared Product Workspaces......................................................................................... 26 Figure 6-6 Protected Workspace.................................................................................................... 27 Figure 6-7 Heterogeneous Workspace........................................................................................... 27 Figure 6-8 Bug-Fix Branches ........................................................................................................ 28 Figure 6-9 Illustrations of Frozen Points Along the Product Line................................................. 29 Figure 6-10 Illustrations of Bug Fixes Along the Product Line .................................................... 30 Figure 8-1 Merge “Nag” Display................................................................................................... 31 Figure 8-2 Client Workspace Tool ................................................................................................ 32



iv

Table of Snippets

Snippet 2-1 Build System Entry Point for “Web Page” Launch...................................................... 5 Snippet 2-2 Icon Command ............................................................................................................. 6 Snippet 3-1 Complete Meta-Commands (runbuild.pl)............................................................ 8 Snippet 3-2 Secondary Meta-Commands (runbuild.pl) .......................................................... 8 Snippet 3-3 Primary Meta-Commands (runbuild.pl) .............................................................. 8 Snippet 3-4 Trial Mode.................................................................................................................... 9 Snippet 3-5 Non-Volatile Environment Variable ............................................................................ 9 Snippet 3-6 Additional Environment Variables............................................................................... 9 Snippet 3-7 Primary Meta-Commands (runbuild.pl) ............................................................ 11 Snippet 3-8 The Build System is Cleaned and QA Tools Are Instantiated ................................... 13 Snippet 3-9 Arguments to perforceCreateClient.pl ...................................................... 14 Snippet 3-10 Screen Shot of the Compilation Process .................................................................. 15 Snippet 3-11 Detail of E-mail Sent to Developer .......................................................................... 16 Snippet 3-12 BlueShift Copy Report ............................................................................................. 17 Snippet 4-1 Label Report............................................................................................................... 21 Snippet 4-2 Perforce “sync” BATCH File..................................................................................... 21 Snippet 5-1a The jobcheck.bat Trigger to Prepare Various E-mail Messages .............................. 22 Snippet 5-2b The job.bat: Sending Various E-mail Messages...................................................... 22 Snippet 8-1 Command Set Used to Run the Integration................................................................ 31 Snippet 9-1 High Level Loop of Data-Driven Test ....................................................................... 33 Snippet 9-2 Sample Perl to C++ Template .................................................................................... 34 Snippet 9-3 Sample C++ Results................................................................................................... 34 Snippet 9-4 Sample Test Thread.................................................................................................... 34



1

1.0 Introduction

Enterprise-level automation begins with the requirement to identify the top-level interfaces into

the repository. The automation begins “with the end in mind1”; a clear definition of the external

requirements that support the repository. This definition forms the requirements of the events

around the repository. The action plan of the enterprise drives the implementation of the events.

1.1 Definitions Enterprise Events

The repository must inform its users about enterprise events that arise from the actions of:

• Compilers

• Backup processes

• Check-out

• Delayed check-in

• Module versioning processes

• Security and obfuscation processes

• Packaging processes

• Pending merge operations

• Test processes

The most efficient way to announce an event is to use a programmatic set of e-mail messages sent

from a process. Such e-mail announcements simultaneously inform developers, management, and

QA about Perforce integrations, build status, and test status. The body of the e-mail displays the

links to inform the staff of relevant data about the event, including the status of the event. This

paper will describe a framework for the announcement of enterprise events.

The Build System

The Build System is a dedicated, autonomous, computer that is responsible for the automatic

creation of a customer’s installation package. The Build System executes several dynamically

created Perforce workspaces (clients) to retrieve and process source code. The installation

packages stem from the compilation of source code resident upon different build-lines. The Build

System also supports the backup system and the test system via a network connection.

In addition to the notification of events, the Build System must also display the history of builds

on a Web page. These results must be immediately available from any machine on the intranet or

extranet (VPN).

The Build System must support the manufacturing process. Each software module and each

configuration file must be control-stamped for the purpose of archival and retrieval. In addition to

stamping software modules, configuration files must also be under management control in a

manner similar to that of software modules. The system must allow for the integration of various

third-party software analysis tools. This paper describes a framework that will accomplish these

objectives.

1 Stephen R. Covey, The 7 Habits of Highly Effective People, Free Press, 1989, 2004



2

Table-Driven Product Management During the development cycle, directories and software components will change. The Build

System cannot expect that software components will reside in stationary directories. Given a set

of rapidly changing software components and changing customer requirements, the movement of

products and projects will demand dynamic Perforce workspaces. To solve this challenge, change

control for the location and construction of products is under regulation by the use of a “table-

driven” approach to building components and workspaces. This paper will describe one technique

for table driven management.

Third-Party Tools and Methods External tools must surround Perforce to provide automated services, including:

• Release of MSI (Microsoft Installation) Package

• Use of Web-Based Merge Tools

• Application of .NET Security Signing

• Attachment of Software Security Certificate

• Obfuscation of DLLs and EXEs

• Generation of Automatic Documents

• Generation of Quality Metrics from Source Code Scan

• Generation of a Cumulative, End-User Configuration Report

• Generation of a BOM (Build Of Materials)

• Generation of Delta Analysis and Label Lists

• Generation of an Intra-Build Change List Report

• Generation of a Copy Report to Analyze File Movement

• Generation of Perforce ‘Sync’ Statements for Playback

• Generation of Developer Workspaces

Enforcement of Policies and Procedures: Triggers Perforce triggers allow both the QA staff and the developers to manage change successfully.

Perforce triggers are in use to enforce Bugzilla bug tracking, and are effective in bug management

during the application of the “SCRUM”2 development methodology.

2 SCRUM: An agile software development methodology developed by Ken Schwaber and Jeff Sutherland in the mid-

1990s. The name comes from the game of Rugby. The term scrum defines the action required to get the Rugby ball moving again, after the ball has gone ‘out of play’.



3

2.0 Implementation

2.1 Enterprise Events The most abstract events are operations that involve a large amount of files. Typical abstract

events come from these operations (Figure 2-1):

• Compiler process

• BackUp process

• Check-out process

Figure 2-1 Event Information for Staff Members

The purpose of each e-mail message in Figure 2-1 will inform the staff that:

• A build has started

• A ‘nightly backup’ has begun (Actually ~4:00 AM)

• A staff member has outstanding check-outs

For example, the first e-mail, with (Subject: A build has started), arrives upon compiler

invocation, via the ‘sendmail’ function of cygwin. The second e-mail (Nightly Perforce Backup)

runs from a Windows XP Scheduled Task. The last e-mail (List of checked-out files) sends a

“checked-out” file report at 11:59 PM. Figure 2-2 shows the scheduled tasks, and Figure 2-3

shows the results of the Build System’s compilation of the Main Line.

Figure 2-2 Build System Scheduled Tasks for Check-Out Report and Daily Build

Figure 2-3 Build System Results for three ‘Nightly Build’ Scheduled Tasks



4

Another e-mail identifies the Perforce change events by stating the workspace and the user who

made the change (Figure 2-4). The e-mail body identifies the list of files that have changed. A

trigger prepares and sends the e-mail.

Figure 2-4 Build System Event Results for Perforce ‘Change’ Trigger

2.2 Implementation of Events Each Build Event takes its implementation from a script. The top-level script is the

“runwebpage.bat” script. Although this is an MS-DOS BATCH file, a translation to other

platforms is not difficult. This section describes the construction of the Build System and the

implementation of enterprise events.

2.2.1 Build System Bootstrap

Each Build Event emanates from a script. This section describes the initialization of the computer

to provide the Build Events and the Build System actions.

Prerequisites for Build System Computer

The Build System computer utilizes multiple entry points, for the convenience of either a GUI or

a script interface. The requirements for the Build System will vary with your particular compiler

environment (Figure 2-5). The Build System assumes that your compiler resides on the Build

System.3

Figure 2-5 Build System Software Prerequisites

The Perl language, Cygwin4 and the GNU emacs editor are used. This toolset creates a powerful

environment to control both the software process and other tasks.

3 The BlueShift Technologies, Inc. development environment uses .NET 2.0 with Direct X 9.0c. The software package

executes under Windows XP-Embedded, (a.k.a. Win XPe). The Win XPe OS is a licensed, customized, optimized, embedded version of Windows XP Professional.

4 Cygwin = GNU + Cygnus + Windows



5

2.2.2 Build System Bootstrap Files

Figure 2-6 depicts the initial Build System file flow. The Build System may start from a GUI (via

icon) or by using the runwebpage.bat file. It may also start a BATCH interface with the

midnightOptions.bat file. This arrangement allows for programmatic flexibility. The files

show the approximate order in which they are used. Table 2-1 [next page] shows the bootstrap

files and describes the purpose of each file in Figure 2-6.

Figure 2-6 Bootstrap Build System File Flow

Dynamic Perforce Clients

The file perforceCreateClient.pl is a multipurpose script. Figure 2-7 shows the two

temporary clients that perforceCreateClient.pl generates. It also generates other

clients such as a Tools client (to populate QA files into the Build System), a Deployment client

(to assist in MSI preparation), a Source Code client (to populate the source code to be compiled),

and a Document client (to allow access to BlueShift documents). The Build System deletes each

client after the operation on the particular fileset is complete.

Figure 2-7 Two Temporary Perforce Clients

The runwebpage.bat looks like this (Snippet 2-1):

"%PROGRAMFILES%\Internet Explorer\iexplore" %INIT%/runbuild.html

Snippet 2-1 Build System Entry Point for “Web Page” Launch



6

File Purpose

backup.bat Back up previous build directory

BlueShift.bat Set Build System Environment variables

buildparms.pl Set log filename and timestamp parameters

build_started.txt5 Text containing e-mail information that

“A build has started.” Read by cleanall.pl

cleanall.pl Recursively delete files on Build System

midnightOptions.bat Runs a fixed set of build options at night (~4:00AM);

creates the BATCH entry point of the Build System

perforceCreateClient.pl Creates six (6) different Perforce clients, depending on the

client workspace function that is requested:

1. Tools

2. Deployment

3. Products

4. Source Code

5. Versions

6. Document

runbuild.html Runs the top-level Web page (GUI) for the Build System;

creates the GUI entry point for the Build System

runbuild.pl Creates the meta-commands for execution

runwebpage.bat Starts the GUI entry point of the Build System from a

BATCH entry point Table 2-1 Build System File Bootstrap Description

2.2.3 Build System Entry Point

The Build System entry point does not start the compilation of code; rather, it prepares the Build

System for compilation. The statement below describes the ‘icon command’ (Snippet 2-2) on the

Target: entry.

%SystemRoot%\system32\cmd.exe /c

%INIT%\BlueShift.bat 0 0 & %INIT%\runwebpage.bat & %EMACS%\runemacs.exe

Snippet 2-2 Icon Command

After the selection of options, the directories and code are ready for a compilation.

5 Not shown in Figure 2-6



7

3.0 Build System Execution

The Build System begins its first stage of execution with the QA bootstrap, listed below.

QA bootstrap (C:\init)

• All previous files are inside a backup

• The system is clean

• The next build options are selected

• The build line is established

• The source code workspace is established

• The version increments are established

• Staff is informed that “A build has started”

3.1 Build System Menu It is instructive to take a first look at the Build System Web Page menu (Figure 3-1). While this

menu could have been presented earlier, the reader would have had less knowledge of the design

goals of the Build System, and would have been unaware of the build bootstrap process. The

menu allows for a selection of Build System options, such as a selection of versioning strategies,

labeling, and the creation of a Bill-Of-Materials. It also allows the builder to select either the

Current Line or the Main Line. A selection of third party tools (doxygen, packaging, obfuscation)

exists. Options also exist for .NET signing, and internal manufacturing steps (productization).

Figure 3-1 Build System Interface



8

The “Run build” button in Figure 3-1 generates the meta-commands (Snippet 3-1) based on the

selection of the operator.

@ECHO OFF set BST_ENABLE_SMaster=0 perl c:\init\cleanall.pl c: cd c:\IPPerforce\Software\QAsystems\QAtools\buildScripts perl increaseDLLversion.pl perl makeRules.pl perl SetQAToken.pl perl updateAssemblyInfo.pl set WIN_LOGO=0 set TIMER_ENABLED=0 cscript unattended.js //nologo call net share productRelease /delete call net share productRelease="C:\Software\QAsystems\productRelease" call net share

Snippet 3-1 Complete Meta-Commands (runbuild.pl)

3.1.1 Secondary and Primary Meta-Commands

Secondary Meta-Commands

Not all the meta-commands will apply in every situation. For example, some environment

variables for particular functions (WIN_LOGO, Standards Master, shared directory sets) will be

different in other environments. These meta-commands, shown in Snippet 3-2 are of secondary

importance and do not need documentation in this paper.

set BST_ENABLE_SMaster=0 set WIN_LOGO=0 set TIMER_ENABLED=0 call net share productRelease /delete call net share productRelease="C:\IPPerforce\Software\QAsystems\productRelease" call net share

Snippet 3-2 Secondary Meta-Commands (runbuild.pl)

Primary Meta-Commands These meta-commands, (Snippet 3-3) are of primary importance and need documentation in this

paper. These meta-commands form the instruction of the Build System, and they direct its initial

action.

@ECHO OFF perl c:\init\cleanall.pl c: cd c:\IPPerforce\Software\QAsystems\QAtools\buildScripts perl makeRules.pl cscript unattended.js //nologo

Snippet 3-3 Primary Meta-Commands (runbuild.pl)



9

3.1.2 Viewing Meta-Commands: The Trial Mode

The Trial Mode of runbuild.pl displays a list of meta-commands to the console (Snippet 3-4).

The –T (Trial) and the -B (BATCH) option must be used to prevent execution and to allow for

silent (no query) operation when the trial commands are viewed.

Snippet 3-4 Trial Mode

The next section describes the execution of the meta-commands.

3.2 Execution of the Meta-Commands This section details the execution of the meta-commands. However, it is important to establish

that your compiler environment has a correct installation before you begin. The BlueShift

environment has an additional environment variable that guides the compiler choice. For example,

if the MSVC .NET 2005 compiler is desired, the BST_VS_VERSION variable is set to “8”. This

variable is a system variable. (Snippet 3-5)

Snippet 3-5 Non-Volatile Environment Variable

3.2.1 The BlueShift.bat Configuration File

Each establishment will have a compiler environment. The BlueShift.bat file sets additional environment variables that make sense for the environment. For example, Snippet 3-6 displays

the list of variables that guide the Perforce build.

BST_BASE_DIR=Software BST_COMPILER_ROOT=C: BST_P4_DEPOT=IPPerforce BST_QUICKLINKS=1 BST_QUICKLINK_PM=_2PM BST_ROOT_DIR=IPPerforce BST_SYSTEM_TYPE=SoftwareTool BST_RLSE_NAME=BST_CFTB1_Support

Snippet 3-6 Additional Environment Variables



10

3.2.2 The Build System Execution

Introduction

Each establishment will have different tools and requirements for build execution. Here is the

framework around which BlueShift creates its Perforce environment. The organization consists of

a Perforce directory and a set of scripts that perform the work of the system. Not all scripts have

documentation; those scripts left undocumented are not critical to a working system.

3.2.3 Parameterized Directory Organization

Environment variables

The directory framework is the organization around which BlueShift creates its Perforce

environment. The directory is rooted around the root BST_ROOT_DIR=IPPerforce name and the

depot BST_P4_DEPOT=IPPerforce name. The lower level directory happens to apply to the

software contents, so the directory immediately below BST_ROOT_DIR is the

BST_BASE_DIR=Software name. The entire directory is rooted at the BST_COMPILER_ROOT=C:

root. These environment variables completely parameterize the location of the Perforce depot.

The BST_RLSE_NAME=BST_CFTB1_Support variable parameterizes the location of the build

products. The BST_QUICKLINK_PM=_2PM and BST_QUICKLINKS=1 parameterizes the physical

characteristics of the robot.

Establishment of the Build System Bootstrap (c:\init)

The only manual step to initialize the Build System is to retrieve the QA’s “init” directory from

Perforce and then copy the contents of the “init” directory into c:\init on the Build System. This

location could be in %INIT%, if desired. Figure 3-2 shows the directory contents.

Figure 3-2 C:\init Directory

An emacs shell will demonstrate the constituent steps of the Build System. This allows an internal

“debugging” view of the system. First, set the BlueShift.bat variables, and then start the emacs editor via an MS-DOS command. This action will allow the capture and the display of

script output. The Figure 3-3 shows the action.

Figure 3-3 BlueShift.bat, Emacs Start-Up



11

The scripts notify QA that the ‘Version 8’ compiler is in use (Figure 3-4).

C:\init>BlueShift.bat

________________________ COMPILER_____________________________________

Setting environment to use Microsoft .NET Framework v2.0 SDK tools

For a list of SDK tools, see the 'StartTools.htm' file in the bin folder.

Microsoft Visual Studio 8

________________________ COMPILER_____________________________________

Figure 3-4 Establishing the BlueShift.bat Environment

The bash-3.2$ prompt appears (Figure 3-5) after the emacs M-x (meta-x) command is issued,

indicating that the Cygwin bash shell is available. The command perl runbuild.pl -T

-B produces the expected primary meta-commands.

Figure 3-5 Establishing the Emacs Environment

As a reminder, Snippet 3-7 shows the primary meta-commands for execution.

@ECHO OFF perl c:\init\cleanall.pl c: cd c:\IPPerforce\Software\QAsystems\QAtools\buildScripts perl makeRules.pl cscript unattended.js //nologo

Snippet 3-7 Primary Meta-Commands (runbuild.pl)



12

These options correspond to a minimum build (Figure 3-6). No automatic versioning is used. No

build options are used. The point of this exercise is to identify how the Build System will respond

to a minimum set of meta-commands.

Figure 3-6 Minimum Set of Meta-Commands

Figure 3-7 shows the Build System response when the Perforce ‘_Tools’ client executes. Figure

3-8 shows the Partial ‘_Tools’ client that deposits the QA Tools from Perforce to the hard drive.

Backing up the last build

Recursively delete local storage.

Retrieve build scripts and data needed.

Client vmaiorana_Tools saved.

Figure 3-7 The ‘_Tools’ Client Completes Its Work

//IPPerforce/Software/QAsystems/QAtools/buildScripts/* //IPPerforce/Software/QAsystems/QAtools/buildScripts/deployShell/* //IPPerforce/Software/QAsystems/QAtools/buildScripts/deployShell/icons/workingIimages/*.ico //IPPerforce/Software/QAsystems/QAtools/Deployment/* //IPPerforce/Software/QAsystems/QAtools/Deployment/res/* "//IPPerforce/Software/QAsystems/QAtools/autoplay for manufacturing/Copyright/..." //IPPerforce/Software/QAsystems/QAtools/management/... //IPPerforce/Software/QAsystems/QAtools/popUpMessage/... //IPPerforce/Software/QAsystems/QAtools/StandardsMaster/*.sms //IPPerforce/Software/QAsystems/ILMerge/... //IPPerforce/Software/QAsystems/init/... //IPPerforce/Software/QAsystems/Licenses/... //IPPerforce/Software/QAsystems/CodeVeilDirectives/...

Figure 3-8 Partial ‘_Tools’ Client (Right Side)



13

Snippet 3-8 shows the detail of the script that starts the process.

@echo off

%COMSPEC% /c sendmail -t <C:/init/build_started.txt

echo.

echo Backing up the last build.

%COMSPEC% /c c:/init/backup.bat

echo.

echo Recursively delete local storage.

echo.

c:/cygwin/bin/rm -rf "C:/IPPerforce/Software"

echo.

echo Retrieve build scripts and data needed.

echo.

perl c:/init/perforceCreateClient.pl Tools

p4 -c %USERNAME%_Tools sync -f

Snippet 3-8 The Build System is Cleaned and QA Tools Are Instantiated

Establishment of the QA Tool Set

The C:\init bootstrap files deposit the QA Tool set under QAsystems directory, as in Figure 3-9.

Figure 3-9 QAsystems Tool Set

A Quick Tour of the QAsystems Directory

These tools will allow the code to compile under script control, and form the actions of the rest of

the Build System requests. Note that a copy (read-only) of the C:\init directory is present. There is

also the ILMerge utility, directives for security obfuscation (CodeVeil) and a set of license files

that accompany the final MSI distribution.

The QAtools directory, (Figure 3-10) however, defines the bulk of the scripting action around

Perforce.

Figure 3-10 QAtools Directory

A Quick Tour of the QAtools Directory

The QAtools directory (Figure 3-10) contains scripts for management, (management) building

(buildScripts), and Deployment (Deployment) directory. The deployment script uses

the commercial PerlMSI package, and is not discussed in this paper. The ‘autoplay for



14

manufacturing’ directory contains the freeware utility from

http://www.naughter.com/shelexec.html that allows for easy creation of the autoplay function,

and is not discussed. The popUpMessage directory registers BlueShift extensions with the

registry and is not discussed.

A Quick Tour of the QAtools Directory

The buildScripts directory contains the following actions (Figure 3-11):

Figure 3-11 Build System Action Scripts

The next script that is to run is the makeRules.pl file; it reuses the

perforceCreateClient.pl to create the Perforce workspace and the sync commands that

create all the directories in Figure 3-12 [next page]. The perforceCreateClient.pl may

retrieve either the Current Line or the Main Line codeline, as shown in Snippet 3-9.

perforceCreateClient.pl Sourcecode productnameflag currentmain

Snippet 3-9 Arguments to perforceCreateClient.pl

The projectFile.txt also dynamically drives the contents of the Perforce workspace client

The rational behind the projectFile.txt is located in Appendix A. Essentially, the file is a



15

table driven approach to the direction and the creation of Perforce workspaces and syncs, based

on different types of components.

Figure 3-12 Perforce Workspace Dynamic Client Results

The result of the makeRules.pl script is a set of product directories (solution files) and corresponding projects directories (source files) that ultimately defines the compliable source

code. This directory organization will produce over 40 distinct products. Refer to Figure 3-12 for

this directory set.

Compilation Phase

The next step of the process is the compilation of the source projects. The unattended.js script does the work (Figure 3-13).

cscript unattended.js //nologo

Figure 3-13 Launch of the “unattended.js” Script

The script recursively deletes any leftover derived files that might be latent in the debug and the

release directory areas. It is a rather crude deletion ‘algorithm’, and it is a good candidate for a

more elegant script.

The compiler builds the requested products with buildProducts.pl by using either a debug or a release directive. The compiler builds either all products or a single product depending on the

argument. The release/debug derived products are stored in a directory with a name containing its

timestamp. The ‘saveSystemState’ directory saves the state of the system.

Snippet 3-10 shows an example screen shot of the compilation process.

Snippet 3-10 Screen Shot of the Compilation Process



16

Compilation Phase – Build Failure

What happens if a build fails? The script handles the error (Figure 3-14) with an e-mail that

shows the failed build. The content of the e-mail shows exactly what has failed and gives a

pointer to a concatenated log of the compile output, as well as an aggregate of all the known good

debug/release modules. Snippet 3-11 shows the corresponding e-mail.

Figure 3-14 Build Failure Highlighted

Doxygen Documentation \\SYSBUILD2005\doxygenOut\html\index.html All Main Line Builds \\SYSBUILD2005\buildpage\BuildSYSBUILD2005.html --------------------------------------------------------- This is a list of links to the "Main Line" BlueShift build DEBUG Tue_03_20_2007_05_33_23.00 RELEASE Tue_03_20_2007_05_35_25.00 140 built 238 succeeded, 2 failed, 0 skipped bstsupervisorteachui.dll not found, bstsupervisorteachui.dll not found ======PRODUCT BST_CFTB1_Support ======DEBUG REPORT \\SYSBUILD2005\productRelease\BST_CFTB1_Support\debug\Tue_03_20_2007_05_33_23.00\debugReport_Tue_03_20_2007_05_33_23.00.html ====RELEASE REPORT \\SYSBUILD2005\productRelease\BST_CFTB1_Support\release\Tue_03_20_2007_05_35_25.00\releaseReport_Tue_03_20_2007_05_35_25.00.html =======DEBUG BUILD \\SYSBUILD2005\productRelease\BST_CFTB1_Support\debug\Tue_03_20_2007_05_33_23.00 =====RELEASE BUILD \\SYSBUILD2005\productRelease\BST_CFTB1_Support\release\Tue_03_20_2007_05_35_25.00 Rules for Build 3.0.0.1583 @echo off perl C:\%BST_ROOT_DIR%\%BST_BASE_DIR%\QAsystems\init\perforceCreateClient.pl Sourcecode p4 -c %USERNAME%_Sourcecode sync -f "C:/%BST_ROOT_DIR%/%BST_BASE_DIR%/Products/QuickBlue Class Library/..." p4 -c %USERNAME%_Sourcecode sync -f "C:/%BST_ROOT_DIR%/%BST_BASE_DIR%/Projects/Internal/Common/BSTCommon/..." p4 -c %USERNAME%_Sourcecode sync -f "C:/%BST_ROOT_DIR%/%BST_BASE_DIR%/Projects/Internal/Common/BSTInterfaces/..." p4 -c %USERNAME%_Sourcecode sync -f "C:/%BST_ROOT_DIR%/%BST_BASE_DIR%/Projects/Internal/Common/BSTException/..." p4 -c %USERNAME%_Sourcecode sync -f "C:/%BST_ROOT_DIR%/%BST_BASE_DIR%/Projects/External/BlueShift/BSTClassLibrary/..." p4 -c %USERNAME%_Sourcecode sync -f "C:/%BST_ROOT_DIR%/%BST_BASE_DIR%/Products/QuickLink Controller/..." p4 -c %USERNAME%_Sourcecode sync -f "C:/%BST_ROOT_DIR%/%BST_BASE_DIR%/Products/QuickBlue Tools/..."

Snippet 3-11 Detail of E-mail Sent to Developer



17

If the build is successful, then the contents of the product are “released” into a time stamped

directory. A copy report demonstrates exactly what modules are “copied” from the development

area into the release area. The script releaseProduct.pl creates the list. In this way, there

is no ambiguity as to the origination or the destination of a file (Snippet 3-12).

BlueShift Release Copy

This is MainGUI version 1.0.0.1584 DEBUG last 'built' timestamp of 'Tue_03_20_2007_14_20_06.00' RELEASE last 'built' timestamp of 'Tue_03_20_2007_14_22_02.00' RELEASE ROOT is C:\IPPerforce\Software\QAsystems\productRelease\BST_CFTB1_Support Configuration File ROOT is C:\IPPerforce\Software\Configuration\SoftwareTool VS Version is 8 MEI Version is 030400 Timer is TimerEnabled

Copy files to 'releaseable' directory Tue 03/20/2007 02:24 PM `C:\\IPPerforce\\Software\\Projects\\Internal\\Common\\BSTBlackBoxLogger\\bin\\release\\BSTBlackBoxLogger.dll' -> `C:\\IPPerforce\\Software\\QAsystems\\productRelease\\BST_CFTB1_Support\\release\\Tue_03_20_2007_14_22_02.00\\dll/BSTBlackBoxLogger.dll' `C:\\IPPerforce\\Software\\Projects\\Internal\\Common\\BSTBlackBoxLogger\\bin\\debug\\BSTBlackBoxLogger.dll' -> `C:\\IPPerforce\\Software\\ProtoProjects\\MainGUI\\MainGUI\\bin\\debug/BSTBlackBoxLogger.dll'

Snippet 3-12 BlueShift Copy Report

The copy report is stored inside the savedSystemState directory. The productRelease directory

(Figure 3-15) stores all of the derived products (DLLs and EXEs) in timestamped directories.

Figure 3-15 The productRelease Directory



18

4.0 Manufacturing Process Support

Incrementing Version Identifiers Automatically

There are other build options surrounding Perforce, used to accomplish other important tasks. For

example, the .NET AssemblyVersion file (Figure 4-1) captures the version of each BlueShift

software component. The file is automatically maintained.

// DO NOT CHANGE THIS AUTOMATICALLY GENERATED FILE // THIS FILE IS generated and modified by QA using System.Reflection; #if BST_QA_BUILD [assembly: AssemblyVersion("1.0.0.1586")] #else [assembly: AssemblyVersion("0.0.0.0")] #endif

Figure 4-1 AssemblyVersion3DEngine file

There are 76 unique files in this system that require a version stamp. See Figure 4-2 for this

information. Each version file is plotted on the horizontal axis as ‘Index of File’. The vertical

axis identifies the number of times that the file has been compiled and/or had its version changed.

Some files have been changed more than 400 times, while earlier files have been changed about

40 times. The summation of all changes is: 15,396! It is a good thing that the version numbers

are auto-incremented. The Build System may increment any part of the quad-numbered version

identifier.

Version Marking

0

50

100

150

200

250

300

350

400

450

500

0 5 10 15 20 25 30 35 40 45 50 55 60 65 70 75 80

Index of File

File Version

Figure 4-2 Plot of File Version Changes vs. Index of File



19

BlueShift has a requirement to change the “A.B.C.D” version number as shown in Figure 4-3.

A.B.C.D | | | | | | | | | | | \...........Absolute Build Number automatically incremented | | | | | \............... Minor Version Number -v | \................. Major Version Number -V | \.......................... Proto Number 0 Alpha Number 1 Beta Number 2 Release to Customer >= 3

D is ALWAYS incremented upon compilation C resets to ZERO when 'B' is incremented

Figure 4-3 Version Identification Rule

While it is true that this may not be your version scheme, all software systems implement some

kind of version scheme requirements. It inefficient to implement this scheme manually; therefore,

it requires automation. The automated process begins in Figure 4-4; Figure 4-5 shows the

notification of the end of the process.

Figure 4-4 Version Number Selection

Figure 4-4 shows the selection of the version scheme, while Figure 4-5 shows the e-mail that the

Build System produces to notify the file version changes. The perforceClient.pl script creates the Perforce client that maps the correct files. After the Build System applies the version

numbers, the Perforce script checks-in the files.

Figure 4-5 Version Number Process E-mail

Suppose that software modules exist in the BlueShift hardware test labs that have no QA version

number: this is a problem. It is certainly possible to have a “rogue” software module that finds its

way into a test bench. One way to distinguish developer-owned objects from QA-owned objects

is to have only QA supply the #if BST_QA_BUILD identifier (refer: Figure 4-1). This technique allows a quick identification of QA-owned modules. Developer-owned modules will

always have an identifier of 0.0.0.0. BlueShift also .NET ‘signs’ its products, and applies a

VeriSign certification to the MSI installation package.



20

There are other ways to make the source-code tamper proof (e.g. source code checksums).

However, if a developer desires to:

1] Strip all the signing from the DLLs or EXEs from a packaged build

2] Put a code dump on the test system and re-compile

3] Swap-in a modified source code set with the QA’s released DLLs/EXEs

then, given these conditions, module traceability is lost. The use of the 0.0.0.0 version number

has helped QA identify such “rogue” modules in the BlueShift test lab.

SAP Manufacturing Support

Perforce assists in the support of SAP manufacturing data (Figure 4-6). For example, Perforce

assists in checking in the build products into “product” bins. The product “bins” are directory

names with serial numbers plus version numbers. The productFile.txt identifies the build

products, and then the perforceCreateClient.pl creates the Perforce client, copies files, and then checks the “binned” files into Perforce. This SAP support is an option in the Build; not

every build requires these manufacturing steps.

Figure 4-6 Perforce Populates Product “bins” Upon Build Completion

Build-Line Support

Perforce captures two “lines” of code: the “Main Line” and the “Current Line”. The “Main Line”

serves as a general repository, while the Current Line (branch) serves as the developer integration

branch. See Figure 4-7 to see the different e-mail subjects for each build line.

[SYSBUILD2005] Latest BlueShift BST_CFTB1_Support Build 3.0.0.1586 Current-branch SoftwareTool

[SYSBUILD2005] Latest BlueShift BST_CFTB1_Support Build 3.0.0.1577 MainLine SoftwareTool TimerEnabled

Figure 4-7 The “Main Line” and the “Current Line”

A script creates the Perforce client, and manages the files in the same way as the Main Line. The

only difference is that the Perforce workspace represents the “Current” branch.



21

A Final Word on Manufacturing Support It makes sense to tie all this information into a Web page (Figure 4-8). A script generates the Web

page. A script (interacting with Perforce) also produces the “rules” file and the “labels” file.

Figure 4-8 Manufacturing Support

The “label file”

There are 84 labels and 84 sync statements (on about 40 products) put on a single build. For

example, the label file looks like this (Snippet 4-1):

Snippet 4-1 Label Report

The “rules file”

The p4 “sync” rules are also available in a batch file; a developer running an MS-DOS prompt

can easily pull-down code (Snippet 4-2):

p4 sync -f "//IPPerforce/Software/Products/QuickBlue Class Library/...@QuickBlue_Class_Library_2.0.0.1586"

p4 sync -f "//IPPerforce/Software/Projects/Internal/Common/BSTCommon/...@BSTCommon_3.0.0.1586"

p4 sync -f "//IPPerforce/Software/Projects/Internal/Common/BSTInterfaces/...@BSTInterfaces_3.0.0.1586"

p4 sync -f "//IPPerforce/Software/Projects/Internal/Common/BSTException/...@BSTException_3.0.0.1586"

p4 sync -f "//IPPerforce/Software/Projects/External/BlueShift/BSTClassLibrary/...@BSTClassLibrary_2.0.0.1586"

p4 sync -f "//IPPerforce/Software/Products/QuickLink Controller/...@QuickLink_Controller_3.0.0.1586"

p4 sync -f "//IPPerforce/Software/Products/QuickBlue Tools/...@QuickBlue_Tools_3.0.0.1586"

Snippet 4-2 Perforce “sync” BATCH File



22

5.0 Perforce Triggers

The use of the Perforce server-side trigger is important in the BlueShift process. Each of the

triggers is important; it is challenging to describe the triggers in any particular order. Surprisingly,

there is not much code or sophistication to the triggers. However, the impact of the work of the

triggers is great. For example, consider these three essential triggers:

Prompt form-out change "bugform.bat %formfile%" Enforce change-submit //depot/... "commentSyntax.bat %change%" Email change-commit //depot/... "jobCheck.bat %changelist%"

The “Prompt" trigger creates a ‘comment prompt’ to link code entries with a Bug system. (Figure

5-1)

sed s/.enter.description.here./Bug=0;Doc=0;Test=0/g < %1 > temp_out_%~n1

Figure 5-1 Comment Prompt

While the first trigger creates the comment, the second trigger (‘Enforce’) enforces the rule, in

case that the comment disappears. (Figure 5-2)

Figure 5-2 Comment Links to Bugzilla Issue #84

The last trigger (‘Email’) creates the e-mail notices seen at the beginning of this paper. (Figure 5-

1a, Figure 5-2b)

@echo off if not x%1==x goto runtrigger echo Usage is %0[change#] :runtrigger call j.bat %1 > NUL if errorlevel 1 echo Not found for changelist %1 exit /B 0

Snippet 5-1a The jobcheck.bat Trigger to Prepare Various E-mail Messages

@echo off call cscript.exe //nologo mailchanges.js %1 exit /B 0

Snippet 5-2b The job.bat: Sending Various E-mail Messages



23

Appendix C shows the code that generates the e-mail. Bear in mind that the e-mail change

notification trigger also shows the progress of the build machine as it runs, so the trigger also

serves to monitor the Build System as it executes (Figure 5-3). This same trigger handles the

automated version change control and the importation of products into the official SAP “binned”

archive.

Figure 5-3 Product and Version Notification

6.0 Directory and Branch Architecture

An important aspect of the repository is the intentional positioning of directories and

corresponding branch structures. BlueShift uses a “Software” directory that contains the

following major categories (Figure 6-1, Table 6-1, Figure 6-2, and Figure 6-3):

Figure 6-1 Major Directories

The complete list of categories is in the Table 6-1, and organized as in Figure 6-2:

Item Description Identifier

Configuration XML files for Robotic Hardware Configuration CFG

DeveloperTest Various Developer Tests

Documents Root of all Documents

Graphics Root of all 2D, 3D Graphics and UI Panels Graphic

MEI_USBKeyImage Field Service Key

PerforceDepot Text Version of Product Workspaces

Products All “sln” files Products

Projects All C# “proj” files Projects

ProtoProjects Up and Coming Projects

QAsystems Root of QA scripts and support

QAtest Root of QA Automated Test Framework QA

SAPProducts Root of “binned” Modules, arranged by Serial Number SAP

Schedule MPP files

VersionKeys Root of strong name files (SNK)

VersionTracking Root of AssemblyVersion*.cs V

Table 6-1 List of Top Directories

SAP Graphics

Products Projects

QA V CGF



24

Figure 6-2 Position of User Branches

Figure 6-3 shows the branch organization.

Figure 6-3 Branch Architecture

Branch Design Goals

The Perforce directories allow developers to:

1. Check into Main Line

2. Check into Current Line (via Main Line)

3. Build from any customer codebase

4. Bug-Fix from any branch

There are six “lines”:

1. Current Line

2. Product Line

3. Project Line

4. Bug Fix Line

5. Main Line

6. Personal Branch



25

Product Support

The multi-product directory structure requires developers to use a Perforce workspec to build

particular versioned products, such as the QuickLink_3.0_1468 workspec. Workspecs are frozen

by QA after the product is released. Workspecs on any product may be bug-fixed with a

minimum of effort by applying the product workspec, checking in the changes, and asking QA to

create a new product with an alpha suffix such as QuickLink_3.0_1468A. Each ‘bug fix’ has a

branch; however all branches originate from a single point in time. This method will be fully

explained in the “Branch Type” section.

Branch Types

Developers use either Main Line or their private branch to check in files. The developer’s private

“Y” branch captures developer-private initiatives (pre-alpha or prototype code). These policies

are in place:

• The “Current” branch is the developer integration branch

• The build machine may build either Main Line or Current Line

• Developers have read-only access to “Current” branch.

Workspaces

These policies are in place:

• Developers create workspaces via QA tools

• Workspaces are prefaced with the depot name

• Developers create workspaces with a “Yc” in the name

• Product Workspace:

o Are static

o Are in a 1:1 relation with Workspace : Product

Placement of Quad-Numbered Branches

Product Branches are quad-numbered, and reside under the major directory. For example, Product

and ProtoProject are major directories, and the 1468 quad-numbered sub directory contains all the

branched changes for that particular delivery.

The Project directory is also a major directory and it will have quad-numbered subdirectories in

the near future; Figure 6-4 [next page].



26

Figure 6-4 Directory/Branch Architecture

Other Developer Workspaces [ 1:n Workspace : Product ]

• Heterogeneous ( Current & Release & “Y” )

• Homogeneous ( Current | Release | “Y” )

• Current is considered R/O, except when integrating

• Product Workspaces Are Frozen

Shared Product Workspaces

Many people share workspaces. Edits on them must be keyword-protected by using a trigger on a

keyword, QATemplate, inside the workspace. If the keyword is missing, there is no workspace

protection. (Figure 6-5)

Figure 6-5 Shared Product Workspaces

Temporary Workspaces

Other temporary workspaces have protection via the “IPPerforce_client_” workspace name.

Only QA may edit the IPPerforce_client_ workspace. These workspaces are used by QA to

instantiate new Perforce bug-fix branches, and must never be edited by developers.



27

Sample Protected Workspace

Figure 6-6 shows a sample ‘protected workspace’. Note the QATemplate keyword, which

provides the read-only protection.

//IPPerforce/Software/Projects/Internal/Common/BSTCommon/1468/...

//IPPerforce/Software/Projects/External/BlueShift/BSTClassLibrary/1468/...

//IPPerforce/Software/ProtoProjects/SomeAPI/1468/...

//IPPerforce/Software/Configuration/SoftwareTool/1468/...

//IPPerforce/Software/DeveloperTest/SomeTest/MotionTest/1468/...

Figure 6-6 Protected Workspace

Heterogeneous Workspaces

The heterogeneous workspace is a developer workspace that accesses different arrangements of

components. (Figure 6-7)

//IPPerforce/Software/Projects/Internal/Controller/Core/1476/…

//IPPerforce/Software/Projects/Internal/Controller/Interfaces/1876/...

//IPPerforce/Software/ProtoProjects/Services/1426/…

//IPPerforce/Software/ProtoProjects/Client/1376/…

//IPPerforce/Software/ProtoProjects/Security/1000/…

//IPPerforce/Software/ProtoProjects/Controls/1111/…

//IPPerforce/Software/ProtoProjects/Simulator/1212/…

//IPPerforce/Software/ProtoProjects/Motion/1477/…

//IPPerforce/Software/ProtoProjects/SomeAPI/1313/…

Figure 6-7 Heterogeneous Workspace



28

Figure 6-8 Bug-Fix Branches

Bug Fix Branch “Technology”

There are some new features in Figure 6-8, as compared with Figure 6-3. Note the existence of

bug-fix branches. These branches are indicated in the light blue color , and are marked with an

A or B, or some other alpha numeric end point. These bug-fix branches must originate from the

common point of the product release.



29

Figure 6-9 Illustrations of Frozen Points Along the Product Line

It is important to realize that the common point of the product release is frozen. Figure 6-9 shows

that the center point, indicated by the O point, is considered frozen while the “1468” or “1379”

Main Line may continue to change in the event of bug fixes past the frozen point.



30

Figure 6-10 Illustrations of Bug Fixes Along the Product Line

Bug Fix Merges are “Taken” [Merge–Up]

Merges from the bug-fix branch are taken from the Main Line of the product (green arrow).

Figure 6-10 shows the action. One and only shared workspace (the <Product>a.b_1468 workspec

is used by the developers to perform the bug fix. The Release Engineer takes the fixes from the

product’s Main Line, and then creates the branches needed to release the new version. Developers

never need to access the “A” or “B” line, since QA applies the merge.

7.0 Perforce BackUp

This section presents basic ideas on how to capture logs from a backup copy process. The

solution is a starting place for more scripts. Appendix D shows the script framework.

Backup Process Scripts Objective

It is important to monitor the backup and copy process. Assume that this (simplified) backup

process will run a scheduled Perforce checkpoint at 4:01AM, and then copy the entire depot

(excluding *.db) to a ‘safer’ place. Notable improvements to the present script process will be:

1. Perforce meta data and source (file data) should be separately mounted in two physical

machines. Perforce recommends this practice.

2. The shutdown of the Perforce server during the backup copy



31

8.0 Tools for Developers

Finding Potential Merges

It is important to monitor the differences between the “Main Line” and the “Current” Line. Figure

8-1 shows the BlueShift merge tool that assists QA to perform the merge.

Figure 8-1 Merge “Nag” Display

The script, which runs inside a Web page, creates a temporary IPPerforce_<user>_Current_Temp

client based on a stored text file. It then creates a branch called IPPerforce_Current_<user>.

Snippet 8-1 shows the instructions.

@echo off

p4 -c IPPerforce_vmaiorana_Current_Temp integrate -n -b IPPerforce_Current_vmaiorana

:: Delete temporary clients

p4 client -d IPPerforce_vmaiorana_Current_Temp

p4 branch -d IPPerforce_Current_vmaiorana

Snippet 8-1 Command Set Used to Run the Integration



32

The value of such a Web wrapper appears during its application. The script keeps track of the

QA-watched directories, and encourages developers to merge files. The Build System sends out a

daily e-mail message (called a “merge nag”) displaying the same contents of the Web page.

Developers may generate a workspace based on familiar product configurations using the

‘generate client’ tool. The interface appears in Figure 8-2.

Figure 8-2 Client Workspace Tool



33

9.0 Tools for Test

The Build System can also execute automated test procedures. Tests that use data-driven

techniques are the most robust. Here are two types:

9.1 Perl Generation of C++ Code This technique uses Perl “forms” to generate C++ code that runs a test. For example, a robot test

for a single robot with four stations will specify the test operations in terms of ‘stations’ (physical

locations) and ‘slots’ (a geometric surface on which to accept a wafer). See Snippet 9-1.

# The robot command to be tested, GotoStation. %cmd1 = ( '$t_MsgCmdGotoStation' => 'MsgCmdGotoStation' , '$t_GotoStation' => 'GotoStation' , '$t_GOTO' => 'GOTO' , '$t_Robot' => 'QL1.VR1' , '$t_Reset' => 'true' , '$t_bStop' => 'false' , '$t_slot_position' => 'BST_SLOT_ZUP' , '$t_Station' => '2' , ## default '$t_Slot' => '1' ) ; ## default # The robot slots per station %slotsPerStation = ( 'station1' => '2' , 'station2' => '1' , 'station3' => '1' , 'station4' => '1' ) ; # The permutation of the test

for ($j=1; $j<=$sizeOfHash ; $j++) ## Station { for ($i=1; $i<=$sizeOfHash ; $i++) ## Station { if ($i != $j) ## Mask (skip) this condition { $~ = 'command_MsgCmdGotoStation'; ## Command Name write; ## Write C++ code } ; ## Mask skip } ; ## inner } ; ## outer

Snippet 9-1 High Level Loop of Data-Driven Test

The Perl script that drives such a test must capture the data of the command, %cmd1, the

architecture of the slots in %slotsPerStation, and the permutation of the test. (Snippet 9-2).

format command_MsgCmdGotoStation = // Test ID MsgCmdGotoStation_@*_@* $j $i msgOperator(@*, @*.cmdbase, @*,"@*") ; $cmd1{'$t_MsgCmdGotoStation'} $cmd1{'$t_GotoStation'} $cmd1{'$t_GOTO'} $cmd1{'$t_Robot'} @*.iStation=@*; $cmd1{'$t_GotoStation'} $j @*.iSlot=1; $cmd1{'$t_GotoStation'} $i @*.eHeight = @*; $cmd1{'$t_GotoStation'} $cmd1{'$t_slot_position'} sprintf(banner,"Go To Station @* from Station @* \n" ); $cmd1{'$t_Slot'} $cmd1{'$t_Station'} runCommand(banner,(char * )&@*,sizeof(@*),m_socket,@*,@*,"Goto Station @* from Station @* completed!\n",hCompleteEvent); $cmd1{'$t_GotoStation'} $cmd1{'$t_MsgCmdGotoStation'} $cmd1{'$t_Reset'} $cmd1{'$t_bStop'} $j $i .



34

Snippet 9-2 Sample Perl to C++ Template

The Snippet in 9-3 shows the results of some of the perl execution. The Snippet is not a complete

test, nor does it have complete coverage. The Snippet only shows what is possible to do with a

template test script. Test templates produce many more lines of code.

// Test ID MsgCmdGotoStation_4_3 msgOperator(MsgCmdGotoStation, GotoStation.cmdbase, GOTO,"QL1.VR1") ; GotoStation.iStation=4; GotoStation.iSlot=3; GotoStation.eHeight = BST_SLOT_ZUP; sprintf(banner,"Go To Slot 3 and Station 4 \n" ); runCommand(banner,(char * )&GotoStation,sizeof(MsgCmdGotoStation),m_socket,true,false,"Goto Station 4 from Station 3 completed!\n",hCompleteEvent);

Snippet 9-3 Sample C++ Results

Summary

Perl scripts create the framework for data-driven tests. The execution of these tests produces data

that Perforce may manage, check-in, and process.

9.2 Object Level Communication There is another ‘data’ driven way that uses external script to drive tests. The data of the

command uses a custom object called BlueShift.QAEntry. This object receives command

messages. The technique of this method is beyond the scope of this paper. (Snippet 9-4).

var oTest = new ActiveXObject("BlueShift.QAEntry"); //Custom object oPop = WScript.CreateObject("WScript.Shell"); oTest.RunForm(); // Attach thread oTest.HelloWorld("Pass a string parameter"); // Pass string command oTest.button1_Click(); // Push button

Snippet 9-4 Sample Test Thread

Summary

Other scripts, such as JScripts, may also create an entry into the Build System framework for

data-driven tests. The execution of these tests produces data that Perforce may manage, check-in,

and process.

10.0 Conclusion

This paper shows how Perforce drives the enterprise when dynamic clients surround it with tools

and procedures that facilitate product management. The process allows a Web presentation of

both input and output tasks. Customer input drives the code changes, and MSI software modules

enter the test cycle as automatically packaged products.

The projectFile.txt file drives the matrix of requirements: products, packaging, and

Perforce workspaces. The matrix also drives the procedures that create the Perforce workspaces.

BlueShift configuration files, build parameters, signing, and the procedures that drive external

tools work together in an extensible framework of simple scripts.

If there are particular requests for more information about these scripts, contact the author.

1

Appendix A - Map of Components to Products

Appendix A-1 Component/Product Table Mapping



1

Appendix B - Trigger: Comment Checker @echo off :: Purpose : Enforce Comment of Bug=0;Doc=0;Test=0 :: File : comment_syntax.bat :: Example : Use "as is" basis. if "%1" == "" goto error p4 -u administrator describe %1 > C:\\temp\\here_%1%.txt set textBUG=N set textDOC=N set textTEST=N set countE=0 findstr /I "Bug=.*" C:\\temp\\here_%1%.txt if %errorlevel% EQU 0 set textBUG=Y findstr /I "Doc=.*" C:\\temp\\here_%1%.txt if %errorlevel% EQU 0 set textDOC=Y findstr /I "Test=.*" C:\\temp\\here_%1%.txt if %errorlevel% EQU 0 set textTEST=Y if "%textBUG%" =="N" ( set countE=1 echo. echo Comment must contain echo Bug= nnnn echo. or Bug= 0 for development. echo. ) if "%textDOC%" =="N" ( set countE=1 echo. echo Comment must contain echo Doc= nnnn echo. or Doc= 0 for development. echo. ) if "%textTEST%" =="N" ( set countE=1 echo. echo Comment must contain echo Test= nnnn echo. or Test= 0 for development. echo. ) if "%countE%"=="1" ( goto error ) :done del /q /f C:\temp\here_%1%.txt exit /B 0 :error exit /B 1

1

Appendix C - Change List Notification

// File: mailchanges.js // Purpose: Generally useful e-mail command for changelist notification // Example : Use "as is" basis. if (WSH.Arguments.Unnamed.length != 1) { stdout.WriteLine("You must supply the changelist number as an input parameter"); WSH.Quit(1); } // Secure place where sendmail exists var email = "C:\\sendmail\\bin\\sendmail.exe "; var basedir = "C:\\TEMP"; var changelist = WSH.Arguments.Unnamed(0); var tempfile1 = "C:\\TEMP\\tempdesc1_" + changelist + ".txt"; var tempfile2 = "C:\\TEMP\\tempdesc2_" + changelist + ".txt"; // For debugging var errfile = "C:\\TEMP\\errfile.txt"; var stdout = WScript.StdOut; var files = new Array(); var description = ""; var WSHShell = new ActiveXObject("Wscript.Shell"); var fso = new ActiveXObject("Scripting.FileSystemObject"); var options = " -p machine:#### -u Administrator " ; WSHShell.Run("%comspec% /c p4 " + options + " describe -s " + changelist + " >" + tempfile1, 0, true); var textfile1 = fso.OpenTextFile(tempfile1, 1); while (!textfile1.AtEndOfStream) { var text = textfile1.ReadLine(); var results = text.match(/^Change\s+\d+\s+by\s+(.+)\s+on\s+(.+)/); if (results != null) { var author = results[1]; var date = results[2]; } var results = text.match(/^\s+(.+)/); if (results != null) { description += results[1]; } var results = text.match(/^\.\.\.\s+(.+)\s+(.+)/); if (results != null) { files.push(results[2] + " " + results[1]); } } textfile1.close(); textfile2 = fso.CreateTextFile(tempfile2, true, false); textfile2.WriteLine("To:[email protected]"); textfile2.WriteLine("From:[email protected]"); textfile2.WriteLine("Subject: Perforce Change "+"["+changelist+"] "+author+" at "+ date); textfile2.WriteLine(description); textfile2.WriteLine(""); for (var index = 0 ; index <= files.length ; index++) { textfile2.WriteLine(files[index]); } textfile2.close(); // build e-mail command var cmd = "%comspec% /c " + email + " -t ^< " + tempfile2 ; WSHShell.Run( "%comspec% /c " + "echo " + cmd + " > " + basedir + "\\" + changelist + ".bat" , 0, true); WSHShell.Run( "%comspec% /c " + basedir + "\\" + changelist + ".bat" , 0, true); // clean up temp files WSHShell.Run("%comspec% /c del /q " + tempfile1 ); WSHShell.Run("%comspec% /c del /q " + tempfile2 ); WSHShell.Run("%comspec% /c del /q " + basedir + "\\" + changelist + ".bat" ); WSH.Quit(0);

1

Appendix D - BackUp Process

BackUp Statistics

• Freespace Results

• RoboCopy Results

• Checkpoint Results

runcheckpoint.vbs��p4backup.bat��runchecklog.bat(sendmail)��checklog.bat�� report.bat

Appendix E-2 BackUp Process Flow to Generate E-mail Summary

Note:

• It is important to determine if the backup script ran as expected.

• It is more important to split the meta-data from the source code location.

• The scripts do not show the shutdown / startup of the Perforce server during the copy.

Mon 03/26/2007 4:11:19.71 ____________________________________________________________________ Freespace on blue1 INFO: 106,634,721,280 bytes free on volume. Freespace on blue2 INFO: 429,718,528 bytes free on "C:" volume. Freespace on blue3 INFO: 2,761,124,864 bytes free on "C:" volume. Freespace on blue4 INFO: 3,824,290,816 bytes free on "C:" volume. ____________________________________________________________________ Started : Mon Jan 29 04:02:51 2007 Ended : Mon Jan 29 04:12:30 2007 Times : 0:09:38 0:00:54 0:00:00 0:08:44 Source : C:\someRoot\ Dest : \\anotherserver\assets Total Copied Skipped Mismatch FAILED Extras Dirs : 77280 121 77159 0 0 0 Bytes : 20.737 g 51.51 m 20.687 g 0 0 0 Speed : 998245 Bytes/sec. Speed : 57.120 MegaBytes/min. ______________________________________________ Checkpointing to checkpoint.348.gz... Saving journal to journal.347.gz... Truncating journal...

Appendix E-3 E-mail Alert for Backup Process



2

' Purpose: Daily Perforce Checkpoint. ' File : runcheckpoint.vbs ' Example: Use "as is" basis. Dim FSO, SrcDir , DestDir, WshShell, CmdString, DfsPath, objFolder, dateToday Dim userGroup , Directory, WshSysEnv Set objNetwork = Wscript.CreateObject("Wscript.Network") Set oFSO = CreateObject("Scripting.FileSystemObject") Set WshShell = WScript.CreateObject("WScript.Shell") set WshSysEnv = WshShell.Environment("SYSTEM") ' Prepare Log Directory = WshShell.ExpandEnvironmentStrings("%SYSTEMROOT%") Set FSO = WScript.CreateObject("Scripting.FileSystemObject") dateToday = weekdayname(weekday(date())) where = "C:\\WINDOWS\\SYSVOL\\sysvol\\BlueShift.com\\scripts\\p4backup.bat" SrcDir = "C:\someRoot" rootLog = "C:\NightlyPerforceTruncation\PerforceLogs\" DestDir = "\\anotherserver\assets" mn=month(date()) : dy=day(date()): yr=year(date()) : t=time() : h=hour(t): m=minute(t) : s=second(t) TimeNow=h&"_"&m&"_"&s ' Build filename ' Execute the Perforce Checkpoint with /MIR ' Exclude Perforce *.db; Covered by Checkpoint ' Use robocopy to Copy to \\anotherserver logIt = "perforceDailyBackuplog_"&mn&"_"&dy&"_"&yr&"_time_"&TimeNow ReturnVal = WshShell.Run("cmd /C " & where & " -zjc", 1, True) If FSO.FolderExists(SrcDir) Then CmdString = "robocopy """ & SrcDir & """ """ & DestDir & """ /XF db.* /R:3 _ /W:3 /REG /MIR /copy:dat /np /tee /log+:" &rootLog&logIt&".log" ReturnVal = WshShell.Run("cmd /C " & CmdString, 1, True) Else WScript.Echo "Source Directory does not exist. Exiting." WScript.Quit(1) End If ' E-mail and Report Process CmdString = "runchecklog.bat" ReturnVal = WshShell.Run("cmd /C " & CmdString, 1, True)

Appendix E-4 The runcheckpoint.vbs Backup Process Script



3

@ECHO OFF :: Purpose: Call the report process, send e-mail :: File : runchecklog.bat Call the report process, send e-mail :: Example: Use "as is" basis. SET T=C:\triggers del %T%\verify.txt , %T%\email.txt echo To:[email protected] > %T%\verify.txt echo From:[email protected] >> %T%\verify.txt echo Subject: Nightly Perforce Backup >> %T%\verify.txt echo %DATE% %TIME% >> %T%\verify.txt call %T%\checklog.bat :: Get the last nightly truncation, via date for /F "tokens=1,2 delims= " %%i in ("%DATE%") do ( forfiles /P C:\NightlyPerforceTruncation /d %%j /C "cmd.exe /C copy %T%\verify.txt + %T%\r.txt + @path %T%\email.txt")

call sendmail -t < %T%\email.txt

Appendix E-5 The runchecklog.bat

@ECHO OFF :: Purpose : Get date ; find a perforce log that matches filename-date :: File : checklog.bat :: Example : Use "as is" basis. for /F "tokens=1,2 delims= " %%i in ("%DATE%") do ( forfiles /P c:\ /m C:\NightlyPerforceTruncation\PerforceLogs\perforceDailyBackuplog*.log /d %%j /C "cmd /c report.bat @path > r.txt" )

Appendix E-6 The checklog.bat

@ECHO OFF :: File: report.bat :: Purpose: This BATCH file selects certain lines from the Robocopy report and :: prints them to the console, to confirm Nightly Backup execution. PASS in the :: robofile copy report as the first object :: Example: Use "as is" basis. SET THIS=%1 SET MORECMD=MORE ECHO. ECHO. findstr "Started ^:" %THIS% findstr "Ended ^:" %THIS% ECHO. findstr "Times ^:" %THIS% ECHO. findstr "Source ^:" %THIS% findstr "Dest ^:" %THIS% ECHO. ECHO. findstr "Total " %THIS% findstr "Dirs ^:" %THIS% ECHO. ECHO. REM findstr "Files ^:" %THIS% findstr "Bytes ^:" %THIS%

Appendix E-7 The report.bat



4

@ECHO OFF :: File : p4backup.bat :: Purpose: Parse prompt and get date and time stamp :: Example: Use "as is" basis. For /f "tokens=1-7 delims=:/-, " %%i in ('echo exit^|cmd /q /k"prompt $D $T"') do ( For /f "tokens=2-4 delims=/-,() skip=1" %%a in ('echo.^|date') do ( set dow=%%i set %%a=%%j set %%b=%%k set %%c=%%l set hh=%%m set min=%%n set ss=%%o ) ) For %%Z in (dow dd mm yy hh min ss) do set %%Z SET STAMP_DATETIME=%dow%_%mm%_%dd%_%yy%_%hh%_%min%_%ss% p4d -r C:\\someRoot -zjc >> "C:\\NightlyPerforceTruncation\\NightlyTruncation_%STAMP_DATETIME%.txt

Appendix E-8 The p4backup.bat