Setting up a development tree

We also include notes about various configuration management issues.

Parallel Trees

Browsing your tree from the web

1. Create a directory for your private webpages:

   mkdir ~/public_html/private
   

   An alternative name is ~/public_html/local
2. Create a link to a .htaccess file that limits access:

   cd ~/public_html/private
   ln -s /usr/local/apache/htaccess/ohmCluster .htaccess
   

3. Create any links you want from that directory.

   ln -s ~/ptII .
   

Renaming Actors

1. copy the .java file to the new directory.
2. Remove the file from the makefile in the old directory
3. Remove the file from the cvs repository in the old directory

   cvs delete -f Foo.java
   cvs commit -m "Moved Foo to new directory blah" Foo.java makefile
   

4. Edit the .java file in the new directory and change the package and the comment at the top if necessary.
5. Add the new file to the makefile in the new directory
6. Compile the new file
7. Add the new file to CVS and commit the change to the makefile

   cd blah
   cvs add Foo.java
   cvs commit -m "Moved Foo from oldblah directory" Foo.java makefile
   

8. Move any tests from the old test directory by doing the copy - cvs delete - edit - cvs add - commit cycle as above
9. Run the tests in both the old and new directory
10. Fix up the Vergil palettes in each directory
11. Update the glimpse index and then search for instances of the actor name and fix it:

    cd $PTII
    make glimpse
    glimpse -H $PTII Foo
    

12. Update the framemaker documentation
13. Check the nightly build the next day for errors

External Packages

Packages that are large or have restricted copyrights (such as GPL) should go into ptII/vendors.

Large packages should optionally be placed in a separate repository and a directory in $PTII/vendors should be created that contains a README.txt file that describes how to obtain the package (either by download or by using cvs).
For example, JHDL is a large package that is used by the code generator.
$PTII/vendors/jhdl/README.txt would desribe how to get JHDL. In this case, it says to use cvs so that $PTII/vendors/jhdl/ptjhdllib is created.
$PTII/configure would then be modified to look $PTII/vendors/jhdl/ptjhdllib for the pieces that it needs.

Build-time considerations

The primary method is to look for a directory that contains the external package. Another method is to compile a program that uses the package and see if it works. Usually, all you need to do is to try to compile a file that imports the package. The javasound and java3d portions of configure.in try to compile files from $PTII/conf that contain the appropriate import statements.

Below is a rough outline of the steps necessary to add a package. by looking for a directory. In general, your best bet is to find a similar package that has already been added and mimic that setup.

1. Edit $PTII/mk/ptII.mk.in and add three variables for your package:

   # KVM is the JDK for PalmOS, see
   # http://java.sun.com/products/kvm
   KVM_CLASSES = @KVM_CLASSES@
   
   # Directory that contains the kvm used by PalmOS
   KVM_DIR = @KVM_DIR@
   
   # Set to kvm and used in $PTII/ptolemy/makefile if the PalmOS KVM was found
   PTKVM_DIR =	@PTKVM_DIR@
   

2. Edit $PTII/configure.in and add a new section for your package. It is easiest to copy a section for an existing package. There are many small design decisions to be made here:
   Check to be sure that the package is actually required.
   configure.in can be used for small Ptolemy II trees that might not have all the source code, so be sure to check that the external package is actually needed.
   What happens if the package is not present?
   Print a useful message stating what this package is used for and where to get it.
   External packages that we cannot ship should go in $PTII/vendors. See $PTII/vendors/README.txt for information about naming conventions. The configure script should look in $PTII/vendors for the external package
3. Run

   cd $PTII
   rm -f config.status config.cache; autoconf; ./configure
   

   until you get the settings in ptII.mk right.
4. If you Ptolemy II code requires that the package be present at compile time, then place your .java files in a subdirectory with the same name as the package, and use the PTKVM_DIR makefile variable in the makefile above your package to determine whether make runs in your Ptolemy II code.

   For example, $PTII/ptolemy/apps/kvm requires that kvm be present to compile. configure sets the PTKVM_DIR makefile variable to kvm if the kvm package was found. $PTIIptolemy/apps/makefile uses PTKVM_DIR in the DIRS variable to select whether make goes into the kvm subdirectory:

   # $PTII/configure looks for various packages and sets variables
   # in $PTII/mk/ptII.mk if these packages are found, otherwise
   # the variables are empty
   #
   # PTKVM_DIR is set to kvm by configure if the kvm runtime was found
   # PTLEGO_DIR is set to lego if the commapi was found.
   # PTWABA_DIR is set to waba if waba was found
   #
   DIRS =		 agilent $(PTKVM_DIR) $(PTLEGO_DIR) $(PTWABA_DIR)
   

5. In the makefile where you actually compile the .java files that use the package, use KVM_CLASSES to set the CLASSPATH:

   CLASSPATH="$(ROOT)$(CLASSPATHSEPARATOR)$(KVM_CLASSES)"
   

   If you need access to a binary in the external package tree, use the KVM_DIR makefile variable

Run-time considerations

ptinvoke.in issues

Also, you will need to update $PTII/.classpath.default and $PTII/.classpath.in for Eclipse users.

In Kepler, you will need to modify these files:

• kepler/build-area/resources/eclipse/PtolemyClasspath
• kepler/build-area/resources/idea/PtolemyModule
• kepler/build-area/settings/ptolemy-excludes

Last Updated: $Date: 2009-12-07 12:49:42 -0800 (Mon, 07 Dec 2009) $