Programmers' Canvas Toolkit Development Environment

27 Feb 2003 00:42

Directories
Environment Variables
Newsgroups
Use Subst
Adding New Projects and Java Archives
Makefiles [Java Projects]
thirdparty.jar
Creating a New Local Sandbox
Clean Sandbox Tasks for Java Developers
Clean Sandbox Tasks for COM Developers
Running Builds Manually

Directories

These are DevGuy's recommendations but you can organize your projects how ever you like.  The toolkit doesn't care.

  • Click here to view the directory tree
  • Configuration files for the toolkit and VC++ DSW and SLN files are in build
  • Java code is in source/java
  • VC++ code and COM IDL projects are under source/c
  • Shared XML files such as documents and schemas are in source/xml
  • HTML, GIFs, etc. are stored under source/web
  • TLB files for internal projects are stored in source/tlb - generally, tlb files are not checked in -- they are generated by VC++ projects
  • Files from third parties are stored in thirdparty.  The exception are IDL or TLB files which are stored in source/tlb. 
  • Java build targets are stored under output.  All Java code is stored in output/java/all.jar, which is created by the build robot.
  • VC++ build targets are stored in a directory where the source code resides.
  • All third party Java code is stored in output/java/thirdpartyjar.jar.  This makes the classpath smaller and prevents CYGWIN make from crashing.

Location of Test Projects:

Test can be written in Java, C++, VB Script, Perl, JScript, whatever.

  • Tests in C should be stored under source/c
  • Tests in Java should be stored under source/java
  • Tests in Script should be stored under source/scripts
  • If you want scripts to get tagged with a build you need to tell the Build Robot to load the projects

Environment Variables

Please see here

Newsgroups

CVS and the build robot post messages to the following newsgroups.  In most installations, the NNTP server runs on the CVS machine tiger.
  • engineering.checkins - CVS checkins (optional, notifications can also be sent via email)
  • engineering.builds - (nightly) build notifications

Use Subst on Windows [recommendation]

Use the Win32 subst command to create a virtual drive.  You can point environment variables to the virtual drive.  Then you can redirect the drive with subst /d to work on a different source tree.  It's easier than changing environment variables (e.g., ROOTDIR) and it affects all running applications without needing to reboot.

subst v: d:\sandbox\june6

Here's how to point the drive to a different directory: 
subst /d v:
subst v: d:\sandbox\june7

Subst only affects the active Windows session.  Subst can cause problems with ASP code, system services, perfmon, event log, etc..  You'll get errors such as "class not registered" and "unable to load performance dll."  The problem is that the registry points to the V: drive but the executing code doesn't have a V: drive.  These problems occur when code executes as a different user such as the local SYSTEM account.

To fix this problem you need to execute subst within a system service.  The best way to do this is to use Arcana Scheduler.  The Arcana Scheduler system service can run any command-line program.  Arcana can also be told to execute subst when the system starts, so you will always have a V: drive even after you reboot.

You can also use the "at" command.  Run at -help from the command line.

Adding New Projects and Java Archives

See also the build XML documentation.

  • For new VC++ projects, add the project to build/all.dsw
  • For new Java projects, copy the makefile from the CVS build directory.  See the makefile instructions.
  • For Java projects modify the makefile in the parent directory to build the new project.  See the makefile instructions.
  • After adding a jar or zip to the thirdparty directory, change build/thirdpartyjar.txt.  Then run make thirdpartyjar.  You will also need to tell the build robot about the new file by modifying build/build_all.xml.
  • If you tag your files via CVS and submit this tag to the build robot, you can continue modifying code without breaking the builds.  If you do this, modify the file build/build_all.xml and specify the CVS tag inside a <Source> element.  See the tag naming conventions.

Building Java and other Code via Makefiles

  • Makefiles and make-related environment variables must contain forward slashes as directory separators, even on Win32
  • The makefile architecture assumes certain files are in the "build" CVS module, e.g., build/Predefs.makefile, makefile, and build/Postdefs.makefile.  The files are located in this archive.
  • Makefiles are used to build Java projects, run arbitrary commands, preprocess code, create setup programs, etc.
  • To build Java code, run a command prompt, navigate to a directory under source/java, and enter 'make'.  This command will build all Java code in the current directory and any sub-directories (if you modify the makefile correctly).
  • Makefile targets are listed below.  You can also enter make help for a listing of the targets.
  • The makefiles support Java by default.  Modify build/PostDefs.makefile to add additional make targets.
  • See the GNU makefile docs for creating and modifying makefiles.
  • Every directory under source/java should have a file named makefile.  Entering "make" from any sub-directory builds the Java files in that directory as well as sub-directories.
  • Every basic makefile consists of the following:

ifeq ($(DEVGUY_BUILDDIR),)
DEVGUY_BUILDDIR=build
endif
BUILDDIR=$(ROOTDIR)/$(DEVGUY_BUILDDIR)

include $(BUILDDIR)/PreDefs.makefile
include $(BUILDDIR)/PostDefs.makefile

For builds prior to 1.6.5, use:

include $(ROOTDIR)/build/PreDefs.makefile
include $(ROOTDIR)/build/PostDefs.makefile
  • If a directory contains sub-directories, the makefile can build the projects in the sub-directories.  Each sub-directory must be listed separately on its own line.  Note that the identical list of sub-directories is given twice -- once in debugall and once in releaseall.  The following example builds the projects in the foo and bar subdirectories:

    ifeq ($(DEVGUY_BUILDDIR),)
    DEVGUY_BUILDDIR=build
    endif
    BUILDDIR=$(ROOTDIR)/$(DEVGUY_BUILDDIR)

    include $(BUILDDIR)/PreDefs.makefile
    include $(BUILDDIR)/PostDefs.makefile

    debugall:
            $(MAKE) -C foo alldebug
            $(MAKE) -C bar alldebug
    releaseall:
            $(MAKE) -C foo allrelease
            $(MAKE) -C bar allrelease

  • Modules that have circular dependencies must be built more than once.  Use $(TRYMAKE) on build attempts that you know will fail.  $(TRYMAKE) causes the build robot to ignore error messages whereas errors cause $(MAKE) to stop the build process.  Use $(MAKE) on the final build attempt in order to catch unexpected errors.  The following example builds the project in the foo directory twice:

ifeq ($(DEVGUY_BUILDDIR),)
DEVGUY_BUILDDIR=build
endif
BUILDDIR=$(ROOTDIR)/$(DEVGUY_BUILDDIR)

include $(BUILDDIR)/PreDefs.makefile
include $(BUILDDIR)/PostDefs.makefile

debugall:
        $(TRYMAKE) -C foo alldebug
        $(MAKE)    -C foo alldebug
releaseall:
        $(TRYMAKE) -C foo allrelease
        $(MAKE)    -C foo allrelease

  • The following targets are supported:
    all [default] Build all projects for Debug recursively
    classpath Creates two files:  classpath and classpath.bat both of which contain the classpath that is used to build all java projects.
    clean Erase all class files in the output directory
    debug Build debug class files - only in the current directory
    debugall Build all projects for Debug recursively (same as all target)
    directories Create %ROOTDIR%/output directory - same as output target
    help Output this help text
    info Display makefile debug information
    jar Create %ROOTDIR%/output/java/all.jar.  This jar file will contain all .class files under %ROOTDIR%/output/java.
    javadoc Create javadoc documentation
    javarelease Build release class files - only in the current directory
    javadebug Build debug class files - only in the current directory
    output Create output directory - same as directories target
    release Build release class files - only in the current directory
    releaseall Build all projects for Release recursively
    sqljdebug For Oracle SQLJ files.  Build debug class files - only in the current directory
    sqljrelease For Oracle SQLJ files.  Build release class files - only in the current directory
    thirdpartyjar Builds %ROOTDIR%/output/java/thirdparty.jar using the build/thirdpartyjar.txt file

thirdparty.jar

All required third party jar and zips are checked in under thirdparty.  All third party zips and jars are aggregated into one jar file output/java/thirdparty.jar, which makes machine configuration a lot simpler and also avoids crashes in CYGWIN.  This file is produced nightly by the build robot.  It can be created manually via make thirdpartyjar.  The file build/thirdpartyjar.txt is used to create the output/java/thirdparty.jar file.

Creating a New Local Sandbox

  • On Windows, create a substituted drive that points to your sandbox
    subst v: c:\source
  • Go to the root directory of your sandbox
    v:
    cd \
  • Enter cvs co .
  • The above command gets everything.  If you want to get individual modules, you are certainly welcome to.  But please make sure to checkout the 'build' module from v:\.

Clean Sandbox Tasks for Java Developers

These examples assume that the sandbox is located at v:\

The first thing Java developers should do after creating a clean "sandbox" (see the above section) and downloading code from CVS is:

  1. v:
  2. cd \build
  3. make output thirdpartyjar

To test the Java makefiles further, enter:

  1. v:
  2. cd \source\java
  3. make debug
    This compiles the Java files in the source/java directory only

Clean Sandbox Tasks for COM Developers

After creating a clean "sandbox" (see the above section) and downloading code from CVS, COM developers need to create TLB files and register them.  These examples assume that the sandbox is located at v:\

  1. v:
  2. cd \build
  3. mktlb

The build robot packages each nightly build in two Zip files.  One Zip file contains DLLs and TLBs.  The other "Debug" Zip file contains PDB (VC++ debugger) files in addition to DLLs and TLBs.

Developers will generally want to extract the files from the debug ZIP archive.  Be sure to extract to v:\ using folder names.  Then do the following: 

  1. v:
  2. cd \source\c
  3. regall.pl . Debug
  4. Or, use
    regall.pl . Release
    To register the release DLLs
  5. cd \source\tlb
  6. regall.pl .

Steps 4 and 5 may be optional -- if you get errors when creating COM objects, be sure you have performed these two steps.

Running Builds Manually

  • Manually run a VC++ build
    • Open the file build/all.dsw
  • Manually run a Java build
    • Change your current directory to the source/java directory
    • Enter make to build release classes
    • Enter make debugall to build debug classes