Setting up a development tree

This page describes how local developers setup parallel development trees. The information below is primarily for use by developers at U.C. Berkeley. Remote sites doing Ptolemy II development may want to emulate the U.C. Berkeley developer setup.

We also include notes about various configuration management issues.

Parallel Trees
Renaming Actors
External Packages

Parallel Trees

Currently, the Subversion (SVN) Repository for the Ptolemy II tree is on repo.eecs.berkeley.edu. The Ptolemy II Subversion repository is world-readable. Write access to the Ptolemy Subversion Repository is by invitation only. We consider software releases a form of publication, so we would like to be sure our software is of suitable quality.

Instructions for setting up your parallel tree can be found at http://chess.eecs.berkeley.edu/ptexternal/.

Renaming Actors

Below are the steps necessary to rename an actor:

Use svn to move the file:
```
	  svn mv foo/Bar.java bif/Boo.java
	
```
Remove the file from the makefile in the old directory (foo/makefile)
Add the file to the makefile in the old directory (bar/makefile)
Edit the .java file in the new directory and change the package and the comment at the top if necessary.
Compile the new file.

Check in the change

	  snv commit -m "Moved Bar from foo to bif and renamed it to Boo." foo/Bar.java bif/boo.java foo/makefile bif/makefile

Move any tests from the old test directory with svn mv.
Run the tests in both the old and new directory.
If present, then update the .xml files that name the actor in each directory.
Check the nightly build the next day for errors.

External Packages

Ptolemy II uses various external, third party packages.

There are several types of external, third party packages

Third party packages that we include in $PTII/lib. These packages are freely available, not too large and have BSD compatibile license. These packages are distributed with Ptolemy II releases.
Third party packages that are checked in to the tree under $PTII/vendors. These packages may have more restrictive licenses, be large, or are of limited use. These packages are not distributed with the Ptolemy II release.
Packages with commercial or GPL licenses. These are never checked in to the tree. The $PTII/configure looks for these packages in places like $PTII/vendors.

Not all users will have these packages installed, so the build and runtime environment needs to allow users to build with and without the external packages and to have the external packages in different locations.

Packages that are large or have restricted copyrights (such as GPL) should go into ptII/vendors. In general, do not add GPL'd code to the repository. See What is the copyright and license? in the Ptolemy II FAQ.

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 version control (cvs, svn, git etc.).

Build-time considerations

Adding a third-party package involves changes in several places:

Typically, Ptolemy Java classes that use a third party package go into directory that is named for the package.
$PTII/configure, which creates configuration files for make, ant and Eclipse,
Third party packages may need to be excluded from Kepler.
Maven, which reads in $PTII/pom.xml.

Each of the above is described below.

Adding a directory

The Ptolemy Java classes that use a third party package typically go into a directory that shares the name of the package. The reason is that it is helpful to group dependencies so that if a configuration does not need to use functionality provided by a third party package, then it is easy to exclude.

For details, see the Checklist for creating a new directory at the end of the Ptolemy Coding Style document.

configure.in

During development, we use GNU autoconf to read in $PTII/configure.in to generate $PTII/configure. During the build process, users run $PTII/configure which reads in $PTII/mk/ptII.mk.in and substitutes in makefile variables and creates $PTII/mk/ptII.mk.

In addition, $PTII/configure reads in $PTII/build.xml.in and produces $PTII/build.xml, which is used by ant and the nightly build.

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.

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@

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.
  In configure.in, lines like
```
	      updateClasspath "$CALTROP_DIR/ptCal.jar"
	    
```
  update both the ant and Eclipse classpaths.
- 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.

Run

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

until you get the settings in ptII.mk right.

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)
	
```
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 ant and Eclipse and be sure those builds work.
Create a package-license.htm file that describes the copyright and license for the third party package. This file should be in the same directory as the Java class that uses the third party package.
Ptolemy II includes a system to determine what third party packages are used by a particular configuration. To see the list of packages, follow the copyright links on the Help | About page. When adding a third party package, update $PTII/ptolemy/actor/gui/GenerateCopyrights.java and add the class name of the primary class of the third party package and the path to the package-license.htm file. in GenerateCopyrights.java add something like:
```
	  _addIfPresent(copyrightsMap, "com.sun.jna.Pointer",
	  "lib/jna-license.htm");
	
```
Add a similar line for your jar file and test that it works by compiling, invoking Vergil and selecting Help | About
In addition, the new directory should be added to the following places:

$PTII/.classpath.default

This directory is used by Eclipse users who can't run ./configure. If the jar file is in $PTII/lib, then add it to the list of jar files. If the jar file is in vendors or elsewhere, then exclude the directory.

$PTII/doc/makefile

configure typically sets a XXX_PACKAGES makefile variable in $PTII/mk/ptII.mk that lists the Ptolemy packages that are compiled. This variable XXX_PACKAGES variable is passed to javadoc to generate documentation. Typically, the package is added to the ALLPACKAGES variable.
Optionally, the directory can be added to these locations for use in WebStart and the installers.

$PTII/mk/jnlp.mk

This make file fragment is included in $PTII/makefile and WebStart. Typically, the jar file for the ptolemy directory is added under FULL_ONLY_JNLP_JARS

adm/gen-N.M/ptIIN_M_devel_setup_windows.xml

This file is used by the installer. Updating it is optional.

Kepler

Since Kepler uses Ptolemy II, it is best to update the Kepler files that exclude Ptolemy II third party directories. See https://kepler-project.org/developers/reference/update-ptolemy-third-party-package-dependencies

To check your work, download and build Kepler under Eclipse.

Maven

In addition, the dependency must be added to $PTII/pom.xml so that maven knows about it.

Search the web for the the xml code necessary to add the the dependency. For most packages, searching for maven packagename will find the xml.
Add the xml to $PTII/pom.xml
Run mvn compile

If there is no public Maven repository for the jar, then it will need to be added to http://chess.eecs.berkeley.edu/ptexternal/src/maven/. See How do I update workgroup pages using SVN?

Run-time considerations

When configure runs, it also reads in $PTII/bin/ptinvoke.in and generates $PTII/bin/ptinvoke. When make is run in the bin directory, ptinvoke is copied to the various startup scripts like vergil and ptolemy. Note that all the startup scripts share a common body and use a switch statement to select the appropriate jar files at runtime.

ptinvoke.in issues:

In general, do not add external packages to the ptolemy switch section. The ptolemy command should not require non-standard packages that we do not ship. The right solution is to add another switch section that uses your package.
If you want to create a new startup script, add a section to the switch statement and edit $PTII/bin/makefile.

Last Updated: $Date: 2014-10-23 21:17:40 -0700 (Thu, 23 Oct 2014) $