Ravenbrook / Projects / Perforce Defect Tracking Integration / Master Product Sources / Design

Perforce Defect Tracking Integration Project


Build automation design

Gareth Rees, Ravenbrook Limited, 2001-07-13

1. Introduction

This document describes the design of the automated build support for the P4DTI.

The purpose of this document is to make it possible for people to maintain and adapt the build system. The build system is designed to help people make P4DTI releases of high quality at a low cost.

The readership of this document is the product developers.

This document is not confidential.

2. Design overview

2.1. History

The automated build system replaces a completely manual build system (see for example [GDR 2001-10-17a]) that became unwieldy as more build targets were added and as the complexity of the build process increased. The change that really required automatic support for the build process was the fix for job000331. This meant that manuals and other documents had to be processed before becoming part of the release, which meant that the products could no longer be built directly from the version sources in the Perforce repository.

2.2. Products

The release build procedure [GDR 2000-10-17b] produces the products in the following table:

Table 1. Build products.

This table lists the P4DTI build products. The "target" column gives the build target which generates the products. The "product" column gives the filename (relative to //info.ravenbrook.com/project/p4dti/release/RELEASE/).
Target Product Notes See
bugzilla p4dti-bugzilla-RELEASE.tar.gz Bugzilla integration (gzipped tar archive: any supported Unix platform). 3.1
p4dti-RELEASE-1.i386.rpm Bugzilla integration (RPM package: RedHat Linux only). 3.2
p4dti-bugzilla-RELEASE.zip Bugzilla integration (ZIP archive; Windows only). 3.3
p4dti-bugzilla-RELEASE.exe Bugzilla integration (self-extracting archive; Windows only). 3.4
kit p4dti-kit-RELEASE.tar.gz Integration kit (gzipped tar archive). 3.5
p4dti-kit-RELEASE.zip Integration kit (ZIP archive). 3.6
manuals readme.txt Installation instructions. 3.7
release-notes.txt Supported platforms, fixed defects, other release notes.
ag/... Copy of Administrator's Guide.
ug/... Copy of User's Guide.
ig/... Copy of Integrator's Guide
aag/... Copy of Advanced Administrator's Guide.

2.3. Running the build tool

Make sure your version sources are up to date by completing and submitting any work in progress and syncing //info.ravenbrook.com/project/p4dti/version/VERSION/.... Then go to the tool/ subdirectory and run:

python build.py OPTIONS

where the options are as follows:

-r, --release The release you want to build (for example, "1.2.3"). You must supply this option.
-c, --changelevel The changelevel from which you want to build the release (for example, "12345"). If you don't supply this option, the build script will use the current changelevel given by p4 counter change.
-t, --target The target you want to build; see the "Target" column in table 1. Specify multiple -t options if you want to build multiple targets.

For example, to build the Bugzilla integration and the online manuals for release 1.1.2 from the version 1.1 sources at changelevel 13579, run the command:

python build.py -r 1.1.2 -c 13579 -t bugzilla -t manuals

3. Product contents

3.1. Bugzilla tarball

The Bugzilla tarball must unpack into a directory called p4dti-bugzilla-RELEASE. It contains:

  1. readme.txt, release-notes.txt and license.txt.

  2. The replicator sources: code/replicator/*.py. The configuration file config.py must specify dt_name = "Bugzilla".

  3. The Administrator's Guide, the User's Guide, and the Advanced Administrator's Guide, with URLs converted appropriately (meaning that they refer to each other with relative links but refer to other files with links starting http://www.ravenbrook.com/).

  4. The Bugzilla start/stop script: packaging/linux/startup-script.

  5. A patch for Bugzilla 2.20.2 called bugzilla-2.20.2-patch, generated by

    ( BEFORE=`p4 where //info.ravenbrook.com/project/p4dti/import/2006-04-23/bugzilla-2.20.2/bugzilla-2.20.2 | cut -d ' ' -f 3`
      AFTER=`p4 where //info.ravenbrook.com/project/p4dti/version/VERSION/code/bugzilla-2.20.2 | cut -d ' ' -f 3`
      cd $AFTER &&
      diff -N -r -u $BEFORE . )
    
  6. A patch for Bugzilla 2.20.4 called bugzilla-2.20.4-patch, generated by

    ( BEFORE=`p4 where //info.ravenbrook.com/project/p4dti/import/2007-02-02/bugzilla-2.20.4/bugzilla-2.20.4 | cut -d ' ' -f 3`
      AFTER=`p4 where //info.ravenbrook.com/project/p4dti/version/VERSION/code/bugzilla-2.20.4 | cut -d ' ' -f 3`
      cd $AFTER &&
      diff -N -r -u $BEFORE . )
    
  7. A patch for Bugzilla 2.22 called bugzilla-2.22-patch, generated by

    ( BEFORE=`p4 where //info.ravenbrook.com/project/p4dti/import/2006-04-23/bugzilla-2.22/bugzilla-2.22 | cut -d ' ' -f 3`
      AFTER=`p4 where //info.ravenbrook.com/project/p4dti/version/VERSION/code/bugzilla-2.22 | cut -d ' ' -f 3`
      cd $AFTER &&
      diff -N -r -u $BEFORE . )
    
  8. A patch for Bugzilla 2.22.2 called bugzilla-2.22.2-patch, generated by

    ( BEFORE=`p4 where //info.ravenbrook.com/project/p4dti/import/2007-02-02/bugzilla-2.22.2/bugzilla-2.22.2 | cut -d ' ' -f 3`
      AFTER=`p4 where //info.ravenbrook.com/project/p4dti/version/VERSION/code/bugzilla-2.22.2 | cut -d ' ' -f 3`
      cd $AFTER &&
      diff -N -r -u $BEFORE . )
    
  9. A patch for Bugzilla 3.0 called bugzilla-3.0-patch, generated by

    ( BEFORE=`p4 where //info.ravenbrook.com/project/p4dti/import/2007-05-09/bugzilla-3.0/bugzilla-3.0 | cut -d ' ' -f 3`
      AFTER=`p4 where //info.ravenbrook.com/project/p4dti/version/VERSION/code/bugzilla-3.0 | cut -d ' ' -f 3`
      cd $AFTER &&
      diff -N -r -u $BEFORE . )
    

3.2. Bugzilla RPM

The Bugzilla RPM is described in detail in [FJMD 2001-02-13].

It must be built from the Bugzilla tarball (section 3.1 using the commands

echo "%_topdir $HOME/rpm" > $HOME/.rpmmacros
mkdir -p $HOME/rpm/{BUILD,SRPMS,RPMS/i386,SOURCES}
cp release/RELEASE/p4dti-bugzilla-RELEASE.tar.gz $HOME/rpm/SOURCES
rpm --define "packager YOUR-EMAIL" -ba version/VERSION/packaging/linux/p4dti.spec
cp $HOME/rpm/RPMS/i386/p4dti-RELEASE-1.i386.rpm release/RELEASE

3.3. Bugzilla ZIP archive

The Bugzilla ZIP archive must unpack into a directory called p4dti-RELEASE. It contains:

  1. readme.txt, release-notes.txt and license.txt.

  2. The replicator sources: code/replicator/*.py.

  3. The Administrator's Guide, the User's Guide, and the Advanced Administrator's Guide, with URLs converted appropriately (meaning that they refer to each other with relative links but refer to other files with links starting http://www.ravenbrook.com/).

  4. The event message file for Windows event logging: code/replicator/eventlog.dll, built using the Microsoft message compiler and Microsoft Visual C++. See [GDR 2001-09-12].

3.4. Bugzilla self-extracting archive

The Bugzilla self-extracting archive must unpack by default into the directory called C:\Program Files\p4dti-bugzilla-RELEASE. It contains the same contents as the Bugzilla ZIP archive (section 3.3).

3.5. Integration kit tarball

The Integration kit tarball must unpack into a directory called p4dti-kit-RELEASE. It must contain all files in the version sources, with URLs converted appropriately in XHTML documents (meaning that they refer to other documents in the integration kit with relative links but refer to documents not in the kit with links starting http://www.ravenbrook.com/). Non-binary files should have Unix-style line endings (LF).

3.6. Integration kit ZIP archive

Same as the integration kit tarball (section 3.5), different archiver, with Windows-style line endings (CR, LF).

3.7. Online copies of the manuals

The URLs in the Administrator's Guide, the Integrator's Guide, the User's Guide, and the Advanced Administrator's Guide must be converted appropriately (meaning that they refer to each other with relative links but refer to other files with links starting http://www.ravenbrook.com/).

A. References

[FJMD 2001-02-13] "Building rpms for p4dti"; Francis Davey; Ravenbrook Limited; 2001-02-13.
[GDR 2000-10-17a] "Release Build Procedure (Version 1.0)"; Gareth Rees; Ravenbrook Limited; 2000-10-17.
[GDR 2000-10-17b] "Release Build Procedure"; Gareth Rees; Ravenbrook Limited; 2000-10-17.
[GDR 2001-09-12] "Using the Windows event log"; Gareth Rees; Ravenbrook Limited; 2001-09-12.

B. Document History

2001-07-13 GDR Created.
2001-07-18 GDR The TeamTrack integration unpacks into a directory called P4DTI-RELEASE, as it says in the readme. Include p4dti.reg in TeamTrack integration. Corrected name of RPM.
2001-09-03 NB Added Bugzilla 2.14.
2001-09-12 GDR TeamTrack releases contain an event message file.
2001-09-26 GDR Noted need to edit config.py when building Bugzilla integration (see job000360).
2001-11-14 GDR Noted the inclusion of the Advanced Administrator's Guide.
2002-01-31 NB Added Bugzilla 2.14.1.
2002-07-19 NB Added notes about line endings for kit archives.
2003-11-03 NB Add Bugzilla 2.16.4.
2005-09-06 NB Updated to reflect supported Bugzilla versions.

This document is copyright © 2001 Perforce Software, Inc. All rights reserved.

Redistribution and use of this document in any form, with or without modification, is permitted provided that redistributions of this document retain the above copyright notice, this condition and the following disclaimer.

This document is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright holders and contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this document, even if advised of the possibility of such damage.

$Id: //info.ravenbrook.com/project/p4dti/branch/2008-05-06/unicode/design/build/index.html#2 $

Ravenbrook / Projects / Perforce Defect Tracking Integration / Master Product Sources / Design