Build automation design

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:

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:

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

B. Document History

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.