Last updated: Thursday 10.05.2001 11:10:41 EEST
1 Introduction
2 Implementation platform
2.1 Development environment
2.2 Required libraries
3 Build environment
3.1 Directory structure
3.2 Makefile-based build system
4 To-Do list
4.1 Main application framework
4.2 GXL model subsystem
4.3 Visualization subsystem
4.4 User interface subsystem
5 Miscellaneous notes
Appendices
A Bugfixes and enhancements made to Jazz source code.
B Instruction for setting up CVS and using it.
Purpose of this document is to give information needed to continue working on Venice and maintaining it. This document describes the implementation platform and build environment of Venice. Also points for further improvements are listed.
Venice is developed on JAVA2 platform in Linux environment. JAVA2 Development Kit 1.3.0 or newer is required. Basic UNIX utilities such as find and rm are needed by build system.
Venice uses following external libraries:
This chapter describes the source code directory structure and the build system which can be used to build VENICE.
After extracting the downloadable venice source archive, the following main directories can be found:
venice-src/ |-- jazz `-- venice
The main level source directory (venice-src/) includes the needed external libraries and different files needed by the build system:
Directory venice/ contains the actual VENICE source code as .java-files.
Directory jazz/ contains modified source code for Jazz graphics library. Modifications are bug fixes which either VENICE or JAZZ team has done and Jazz team has adopted them and they will be included in next Jazz release. Jazz has its own build system which is described in README files in jazz-directory. See Appendix A for information on changes made to the Jazz library.
Also other changes to Jazz were made than bug fixes. Modified versions of Zoom and Selection event handlers are in venice-directory. It has not been discussed if these will be included in future Jazz releases.
VENICE build system is based on use of UNIX make tool. The following make targets are defined in the Makefile:
Target | Description |
venice-only.jar | Build venice-only.jar which contains only the class files for venice and no class files for required libraries. Runnable using command 'java -jar venice-only.jar' if required libraries are present in the same directory. |
venice.jar | Build venice.jar which contains everything in venice-only.jar PLUS all required libraries including Jazz and JAXP. Runnable using command 'java -jar venice.jar'. |
javadocs | Build javadocs for the project at location specified in Makefile. |
proto | Build venice.jar and copies it to location specified in Makefile for web access. |
clean | Cleans the build directory from compiled class files and backup files. |
This sections lists points for further improvements in VENICE.
Visualization subsystem implements a debug menu. Different debug functions of visualization subsystem can be accessed through the menu. These include a scenegraph browser which can be used to analyze Jazz scenegraph structure. These functions can be accesed via the debug menu in the menubar.
Visualization components also implements a debugDump() method. When this method is called, debug information about node is printed. This method can be accessed by selecting a node in Jazz canvas and then activating the pop-up menu.
ZNode's updateBounds()-method was modified to prevent unnecessary node events. Unnecessary node events resulted in unacceptable performance in VENICE.
Code was modified in the following way:
Index: src/edu/umd/cs/jazz/ZNode.java =================================================================== RCS file: /home/group/venice/project/cvsroot/venice-src/jazz/src/edu/umd/cs/jazz/ZNode.java,v retrieving revision 1.1.1.1 retrieving revision 1.2 diff -u -r1.1.1.1 -r1.2 --- src/edu/umd/cs/jazz/ZNode.java 2001/05/03 16:50:48 1.1.1.1 +++ src/edu/umd/cs/jazz/ZNode.java 2001/05/06 14:49:19 1.2 @@ -748,9 +748,23 @@ protected void updateBounds() { // XXX should check to see if our bounds actualy change, if // not then stop forwarding the event up the tree. + + // Checking code added, hopefully it's right + // Hannu Laurila, 2001-05-06 + + ZBounds myOldBounds = null; + if (bounds != null) + myOldBounds = new ZBounds(bounds); + computeBounds(); + + // if bounds did not change, return without event percolation + if (myOldBounds != null && myOldBounds.equals(bounds)) + return; + percolateEventUpSceneGraph(ZNodeEvent.createBoundsChangedEvent(this)); percolateEventUpSceneGraph(ZNodeEvent.createGlobalBoundsChangedEvent(this)); + if (parent != null) { boolean hadListener = hasNodeListener; hasNodeListener = false; @@ -1032,4 +1046,4 @@ trimToSize(); // Remove extra unused array elements out.defaultWriteObject(); } -} \ No newline at end of file +}
repaint() calls were added to ZVisualLeaf's addVisualComponent/removeVisualComponent methods. This fix was needed for correct repainting of interface labels.
Code was modified in the following way:
Index: src/edu/umd/cs/jazz/ZVisualLeaf.java =================================================================== RCS file: /home/group/venice/project/cvsroot/venice-src/jazz/src/edu/umd/cs/jazz/ZVisualLeaf.java,v retrieving revision 1.1.1.1 retrieving revision 1.2 diff -u -r1.1.1.1 -r1.2 --- src/edu/umd/cs/jazz/ZVisualLeaf.java 2001/05/03 16:51:01 1.1.1.1 +++ src/edu/umd/cs/jazz/ZVisualLeaf.java 2001/05/07 07:15:08 1.2 @@ -96,6 +96,7 @@ visualComponent.addParent(this); updateVolatility(); reshape(); + repaint(); } /** @@ -137,6 +138,7 @@ visualComponent.removeParent(this); updateVolatility(); reshape(); + repaint(); } /** @@ -449,4 +451,4 @@ trimToSize(); // Remove extra unused array elements out.defaultWriteObject(); } -} \ No newline at end of file +}
ZLine was modified to prevent a null pointer exception on deserialization.
Code was modified in the following way:
Index: src/edu/umd/cs/jazz/component/ZLine.java =================================================================== RCS file: /home/group/venice/project/cvsroot/venice-src/jazz/src/edu/umd/cs/jazz/component/ZLine.java,v retrieving revision 1.1.1.1 retrieving revision 1.2 diff -u -r1.1.1.1 -r1.2 --- src/edu/umd/cs/jazz/component/ZLine.java 2001/05/03 16:51:07 1.1.1.1 +++ src/edu/umd/cs/jazz/component/ZLine.java 2001/05/03 17:13:53 1.2 @@ -173,6 +173,6 @@ x2 = in.readDouble(); y2 = in.readDouble(); - setLine(x1, y1, x2, y2); + getLine().setLine(x1, y1, x2, y2); } -} \ No newline at end of file +}
In this chapter is included information on how we used CVS during the project. This information might be useful for setting up a CVS system for further development of the system.
Project Venice: Instructions for using CVS ------------------------------------------ Per-user initialization: Add the following line to a suitable place in your .profile file in your home directory: export CVSROOT=/home/group/venice/project/cvsroot If you plan to work on the project on CSL-1 machines, you need also to set PATH and MANPATH because they don't have CVS in the default path. export PATH=$PATH:/opt/cvs/bin export MANPATH=$MANPATH:/opt/cvs/man IT IS RECOMMENDED TO WORK ON VENICE ONLY ON CSL-2 MACHINES! JAVA2 1.3 does not work on CSL-1 and also the CVS version installed on CSL-2 machines is more recent. To begin working on project source code: 1. Check out the project 'venice-src' from the repository: cd # (go to your own home directory) cvs checkout venice-src 2. You'll find venice source code in the venice-src directory. 3. Muddle with the code. Notice that you may have multiple checkouted copies of the source code. Preparing to add a file to the source code tree: 1. Create and write the file you are going to put to the repository: cd ~/venice-src/venice emacs File.java 2. Mark the file to be added on next commit: cvs add File.java Removing a file from the source code tree: 1. Delete the file from your working directory: cd ~/venice-src/venice rm File.java 2. Mark the file to ba removed from the repository on next commit: cvs remove File.java (Same using only one command: 'cvs remove -f File.java') Updating your working directory to have the latest stuff in the repository: Issue the commands: cd ~/venice-src cvs update Beware, that cvs will try to solve conflicts by merging differences between individual files. This happens if you have modified locally a file for which there is now a newer version in the repository than the version you have modified. Dry-run using 'cvs -n update'. Commiting your work to the repository: Your work is not visible to others before you commit it to the repository using the following commands: cd ~/venice-src cvs commit The command prompts you for a log message. Please describe your updates. NOTE: Please be sure that the version in your directory compiles cleanly before committing it! Preferably, first do a 'cvs update', then compile and now if it compiles, 'cvs commit'. Releasing your checkouted version: Issue the following commands: cd # (go home) cvs release -d venice-src The directory will be deleted. If you have modified files which you have not committed, you will be warned. It is not necessary to release your checkouted version very often. But please use 'cvs release' instead of 'rm -r' so that cvs history and status information will be correct. Please understand that this only releases your own working copy of the project - the files are not removed from the repository! Tagging a version: A version can be tagged using 'cvs tag' command. The tagged version can later be retrieved using the tag. To tag current version as VENICE_M1, issue the following commands: cd ~/venice-src cvs tag VENICE_M1 Importing vendor sources to VENICE tree: The jazz sources were imported to VENICE source tree because we needed to do some modifications and bug fixes to them. CVS has features for tracking third-party sources. The import was done using the following command: cvs import -m "Import of JAZZ 1.1" venice-src/jazz \ CS_UMD_EDU_DIST JAZZ_1_1 After this, a checkouted copy was updated using 'cvs update -d'. Because jazz source tree includes also binary files, the following command was issued in ~/venice-src/jazz: find . -name "*.jpeg" -o -name "*.jpg" -o \ -name "*.gif" -o -name "*.jar" \ | xargs -n1 cvs admin -kb This flags the binary files in Jazz source tree so CVS knows about them. Because something might have got wrong already in the initial import, the following was done: cd ~/venice-src diff -ur jazz ~/tmp/jazz-1.1/jazz-1.1/ No problems were found! More information on the matter can be found from CVS Manual: http://cvshome.org/docs/manual/cvs_13.html More information: www.cvshome.org http://www.cs.helsinki.fi/u/kpalaaks/ohtu/CVS.html http://www.cs.helsinki.fi/group/chromos/cvsohje.html cvs --help cvs --help-commands cvs --help commandname http://www.cvshome.org/docs/manual/index.html Appendix A: How to repository was set up The repository was setup in the following way: 1. Perform the per-use initialization steps described in the beginning of the document. 2. Set up the CVS repository with good permissions: mkdir $CVSROOT chgrp venice $CVSROOT chmod 2770 $CVSROOT cvs init 3. Initial import of the sources: cd /home/group/venice/project/src cvs import venice-src DEFAULT_VENDOR DEFAULT_RELEASE Appendix B: Working on the project remotely using ssh. You can work on the project on your home Linux machine (for other platforms, see www.cvshome.org) if you can access melkinpaasi.cs.helsinki.fi using SSH. (We can't use melkki because cvs software installed at /opt/cvs does not include CVS server functionality needed here). 1. Install CVS software on your Linux machine. It is shipped with almost every distribution and it is usually automatically in the path so there is no need to set PATH or MANPATH. 2. Put the following in your .cshrc (tcsh): setenv CVSROOT :ext:hlaurila@melkinpaasi.cs.helsinki.fi:/home/group/venice/project/cvsroot setenv CVS_RSH ssh setenv CVS_SERVER /usr/bin/cvs (substitute hlaurila with your own username) These commands are for tcsh. If you use BASH, use appropriate syntax (export VARNAME=value) and put the commands in .profile instead. 3. Now use cvs like you would use at CS machines. If you find the continuos asking of password by SSH annoying, please set up your SSH connection to use RSA authentication. (see manual pages for ssh, ssh-keygen and ssh-agent).