Programmers' Canvas Toolkit

Skills Required

• General knowledge of source-control concepts 
• Ability to modify XML documents via a text or XML editor
• If you want to build Java projects, knowledge of makefile concepts is needed (or, you can use your own scripts or ant)
• Some knowledge of Perl is helpful if you want to tweak the scripts

Credits

Please consult the credits

Machine Requirements

• Linux/Windows NT/2000/2003/XP
• Apache or IIS 4 or later - if you wish to use the Web application. (Apache support is fairly experimental and was contributed to the project)

Build Server is ACME, CVS Server is Tiger

Builds are performed on a machine named ACME in this documentation.  Please substitute the name of your build machine.

The CVS server is on a machine named Tiger in this documentation.  Please substitute the name of your CVS server.

Here's a run-down on the types of machines that you will need.  If you're strapped for machines you can run everything on a single windows machine, but it isn't recommended.   It is highly recommended that you put the CVS server on its own dedicated server.

1. Windows NT/2000/XP (Server or Workstation) build machine (server or workstation)
   • Java .class, JAR, and ZIP files exported by the build robot can be used on any platform
2. Windows NT/2000/XP Server running IIS
   • Can be used as newsgroup (NNTP) server {requires Windows 2000 or XP}
   • This can be the same machine as the build machine
3. Linux or Windows 2000/XP (Server or Workstation) CVS server
   • cvsnt runs on NT but Windows 2000 and XP are recommended, as it includes everything you need, including an NNTP server.  cvs for Windows is relatively new and therefore a Linux server is more reliable.  DevGuy uses cvsnt for their own development and it works great. 
   • Linux server can be used as newsgroup (NNTP) server

Getting Started

1. Admins: Install the CVS Server
2. Admins: Install DevGuy Products
3. All: Read the CVS Information
4. All: Install client tools
5. All: Read the Tools User Guide
6. All: Read the Development Environment description

CVS Commit (LogInfo) and Notify Scripts

These scripts send newsgroup or email notifications when files are modified.  Installation of the "loginfo" and "notify" scripts is described here.

Support

1. Read the FAQ
2. Click here to subscribe or unsubscribe to announcements
3. Read the Wiki
4. For bug reports, feature requests, and other needs, please use the Bulletin Board

• The toolkit project is hosted on SourceForge.
• Click here to view the CVS repository.
• See here for CVS details.

FAQ

• What are the machine requirements?
  • Windows 2000 Server or NT4 with option pack 4 (IIS)
  • [UNI]+X support is possible thanks to Perl script implementation but no serious effort has been put into it
  • Although the toolset has many built-in features to support Visual C++ projects, it will build anything as long as there is a makefile or command-line program for it (e.g., Java)
• What about bug tracking?
  • Try the open-source Bugzilla and Mantis
• How should I test the Build Robot?
  • When you're configuring the build robot for the first time, you should turn off CVS tagging by setting the element text in <ShouldTag> and <ShouldForceTag> in the build-options document to 0
• Can the toolkit build VS.NET projects?
  • The latest version runs devenv to build SLN and VCPROJ files 
  • If you only have the SDK, you can configure the build config file to run nmake.
• How mature is the toolkit?  How many companies actually use it?
  • The toolkit evolved over five years of off-and-on development.  It is currently in daily use.
  • The toolkit in its current form is in use at one location for building VC++ and Java code nightly.
  • Prior manifestations of the toolkit (all "one-offs") are in use by four other companies, although each installation has differing levels of functionality and they don't compare to the current state of the kit.
• Is the toolkit free?  Open-source?
  • The toolkit is completely free with no guarantees regarding support or reliability.  Any lost revenues or damage made to your system is not DevGuy's responsibility.
  • Click here for license details.
  • As far as open-source goes, you can change the scripts to suit your needs.  If you do something interesting, you can send it to host@devguy.com for possible inclusion in a future release.  You can also join the development team if you have a SourceForge account.
• Is the toolkit limited to one build machine?
  Similar to:  Does the build robot and the IIS server have to run on the same machine?
  • Absolutely not.  Any machine can be a build machine by virtue of installing and running the build scripts on it.
  • You will probably want to have one website that contains the build artifacts from all types of builds.  In order to have multiple build machines writing artifacts to one website you will need to share the build folder.  The location of this folder it defaults to c:\inetpub\wwwroot\builds can be changed via the build options file, so the actual folder you need to share depends on that configuration file.
• My web server doesn't have a lot of free disk space for build artifacts.  Can I put the artifacts on a different machine?
  Similar to:  Does the build robot and the IIS server have to run on the same machine?
  • Build artifacts can be stored on a different machine from the IIS server.
  • Web pages point to build artifacts using a URL of your choice.  The files can be stored on another web server, in which case the URL would use the http protocol, or on a file server, in which case the URL would use the file protocol.
  • The build robot needs write access to the folder that the build artifacts will be written to.  This folder needs to be shared on the network.  Also configure the build options file properly.
• Do I have to tag files after every build?
  • No, but if you don't tag the files, the checkin comments feature won't work correctly.  The build robot generates the check-in comments log using tags.  So you will see the same check-ins until you tag the files again.  It is common to only tag once a week or after a release build.
• How do I set up two sets of parallel builds -- one for development and one for release?
  • Modify c:\inetpub\wwwroot\build\build_types.xml to reference both build directories
  • Create two build robot options files, both of which use build/build.xml as a template.
    • Specify different <Configuration> s - e.g., one file uses the "Debug" build target and the other uses the "Release" build target
    • Specify different <ChangeLogInfoFile> s
    • Specify different <WebPath> s and <WebSubdir> s
    • Specify different <BuildStampPrefix> s
    • If you want each type of build to have its own incrementing build number, specify different <BuildNumberFile> s
  • See also the configuration file descriptions
  • The build robot gathers check-in comments separately for each type of build.  The comments for a single check-in will appear on both web pages for the Debug and Release builds.
• I don't want to build anything but instead want to extract files from CVS nightly and post them to a web server.  How do I do it?
  • The <BuildDoc> document has <Source> elements but no <Build> elements (at least for the specified configurations, if any)
  • See the SQL files example in the Packaging Document for how to copy the files
• I get an NNTP error (503 connection timed out) in the build robot output
  • This message seems to always appear but it doesn't seem to indicate a real error
• How do I run makefiles?
  • See the description of the Build document which is described on the Build Robot page
  • Here is a sample <Build> element.
    <!-- The build robot recognizes 'makefile' and
     files having .mak extension.  It sends
     the specified filename to the program 'make'
-->
<Build>source/c/widget/makefile
  <!-- Only build this for the Win32 Release Configuration -->
  <Configuration>Win32 Release</Configuration>
  <Targets>clean release</Targets>
  <!-- When building multiple configurations, build artifacts
       must be packaged up after building each configuration,
       because build artifacts are written to the same output
       directory.
  -->
  <Sequence/>
</Build>
• How do I run external scripts?
  • See the description of the Build document which is described on the Build Robot page
  • In order to capture warnings and errors, you should write a specialized script that can do so
    • A generic script, genericOutputParser.pl, can be found in the 'pl' directory
  • Here is a sample <Build> element:
    <Build>c:\installer.bat
  <ScriptIsOutsideSandbox/>
  <!-- This is the current directory when the command executes -->
  <Path>source/install/main</Path>
  <!-- Do this once regardless of the number of configurations -->
  <Once/>
</Build>
• How should I handle branches?
  • The build robot options file, which uses build/build.xml as a template, specifies the branch tag for all retrieved modules.
  • You can branch the constants.h file (or whichever file you specify in the build options document) so your builds can have different product versions, etc..
    • Specify the <Tag> in a <Source> element in the build document
  • See also the configuration file descriptions
  • If you want to specify the revision tag on a per-module basis, modify or add <Source> tags in build/build_all.xml.
  • Note that the build number is an absolute value.  It increments with each build, regardless of branches
  • Here's what I do.  I usually copy an existing build options document and modify the following tags:
    1. MajorBuildDescription
    2. BuildDescription
    3. Branch -- Specify the name of the branch
    4. BuildStampPrefix -- I usually put the branch name in the build stamp
    5. BuildNumberFile -- each branch should have its own build number file if you want build numbers on different branches to increment independently
    6. ChangeLogInfoFile -- each branch can have its own change info file, but since this file can also be branched, it's up to you
    7. WebSubdir -- I put builds from different branches in different web subdirectories
• I want to make Setup.exe (which is built nightly) available via the build web page, but I don't want to put it in a zip file
  • See the Packaging document
• How do I build from two physically separate CVS repositories?
  • Currently, you must run two builds.  There are two options:
    1. The first build generates artifacts that the second build uses (e.g., jar files)
    2. The second build "overlays" the first build
       • The sandbox isn't cleaned before running the second build
       • This requires the CVS modules in both repositories to not have overlapping module names because otherwise CVS will not permit this
       • You can use the <UseLastBuildStamp> in the build-options document to tag files in both directories identically (the second build will not create a new build stamp).
• How do I run two builds back-to-back and tag them using the same CVS tag?
  • Specify the same <CVSTag> in the build-options document
  • Or, for the second build, specify <UseLastBuildStamp> in the build-options document.  This will generate a unique CVS tag.

Change History for the Programmers' Canvas Toolkit

The installation programs contained herein require Microsoft Installer 2.0.  The setup programs will install Microsoft Installer 2.0 if it is not present.  If Microsoft Installer 2.0 is not yet installed, Terminal Services must be in Remote administration mode rather than Application server mode.  Before installing anything it is advised that you create an Emergency Repair Disk.  Failure to heed all of this advice can result in a hosed machine that must be reformatted.  In no circumstances shall DevGuy be held liable for any damage to your machine made directly or indirectly by the installation programs.

• Release Announcements
• Release Notes

(c) 2003 DevGuy.com