Developers Guide

Contents

• Introduction
• Copyright
• System Requirements for Developers
• The Build System
• Configuration Files
• Bug Reports and Feedback
• Related OpenMMS Documents

This developers guide provides an introduction for administrators who wish to compile an OpenMMS model different from the one contained in the distribution or Java programmers who wish to modify or extend the OpenMMS toolkit. This document assumes that such developers are already familiar with the information presented in the OpenMMS Overview.

Only the general design and overall principles of the build system are described here. For additional information about specific packages or classes, programmers should consult the OpenMMS API Specification.

All portions of the OpenMMS Toolkit are released under the UCSD Copyright.

OpenMMS was developed on Sun Solaris, a dialect of the Unix operating system. It has also been compiled and tested on Linux. While no other OS platforms have been tested for development work, other than basic Unix commands, only a Java compiler, the GNU gmake utility and an IDL-to-Java compiler are required. Consequently, setting up an OpenMMS programming environment on other Unix systems should not be difficult. The complete list of tools and runtime utilities required for program development are defined as variables in the config/localdefs.gmake file discussed below (Configuration Files).

Links on where to find the needed development tools are provided in the Overview section on Additional Information.

Note that GNU refers to their build utility as make, which may cause confusion with the standard Unix "make" utility. On many systems the "GNU Make" utility is often installed as gmake. It is referred to as "gmake" in the OpenMMS documentation (and elsewhere) to make this necessary distinction explicit. The following assumes that the reader is familiar with the concepts and operation of this utility. Documentation on the open-source gmake utility is available from GNU.

The actual specification of how to build the OpenMMS system is contained in the set of Makefiles distributed throughout the OpenMMS directory hierarchy. In each directory beginning with at the top level, gmake reads the Makefile in that directory, uses the commands specified in the Makefile to compile and build any targets that are out of date and need to be built, and then recursively builds the subdirectories specified in the Makefile. The Makefile in each of the subdirectories is read and the process repeated.

Targets and Models

A build of the OpenMMS system begins in the top-level openmms directory with the unix command:

% gmake <Build_Target>

Where <Build_Target> identifies which OpenMMS model is to be created. Five Build_Targets: "Std", "Dev", "Compact", "Full" and "Test" are available at this time, plus the special Build_Target "clean". The default build target of "Std" is used if none is specified on the command line.

At any given time, there is a one-to-one correspondence between Model Names and Build Targets. However so that particular Models can remain fixed, while the "Standard" (Std) and "Development" (Dev) Build_Targets evolve, these two concepts have been decoupled. The following list shows the relationships at the present time.

  BUILD_TARGET    MODEL_NAME      mms/meta/TransRoot-subclass

  Std     -->     LSR-1.0         StdRootTrans.java
  Test    -->     Test-2.4        TestRootTrans.java
  Dev     -->     Dev-3.3         DevRootTrans.java
  Compact -->     Compact-1.1     CompactRootTrans.java
  Full    -->     All-1.0         AllRootTrans.java

Adding or Removing Structures (Tables) or Fields (Columns)

It is possible to modify any of the OpenMMS models. However, please do not modify any model that has a name beginning with the prefix LSR. This is to insure compatibility with the standard Corba specification adopted by the Object Management Group (See OMG specification formal/2002-05-01 ). If you wish to create a model similar to this interface, copy the file StdRootTrans.java to another filename and change the string returned by the method getModelIdentifier() so that it does not begin with the prefix "LSR".

A Corba Structure corresponds to a collection of columns in a relational database table. Each such table must map to an mmCIF category defined by one of the dictionaries. Similarly Corba fields correspond to single columns and must map to an mmCIF item definition. Two mmCIF dictionaries: cif_mm_V2.0.3.dic and pdbx_exchange.dic are included with the OpenMMS distribution in the openmms/dicts directory. Other mmCIF dictionaries can also be found at the web site http://pdb.rutgers.edu/mmcif/.

Many fields defined in the dictionaries are missing from the various model definitions. However, it is fairly straight forward to add any field you are interested in to model. mmCIF is designed to be very extensible and you can add entirely new fields in a new dictionary that you define (you could then modify whatever software created the mmCIF data files so they would include your new fields and then this data would be automaticly loaded into the database by the program pdbase.

To see how these fields are added, examine the code in any of the "*RootTrans.java" files in the openmms/src/mms/meta directory. At present these include the files: AllRootTrans.java, DevRootTrans.java, StdRootTrans.java, CompactRootTrans.java and TestRootTrans.java. All of these subclass the RootTrans class. Which one of these is used depends on which model you build.

For example to build the entire openmms source tree for the "Dev" model you would use the top level command

% gmake Dev

in the openmms directory, which would cause the DevRootTrans.java class to be used to define the model. If for example you wanted to remove the temp_esd column from the CELL_MEASUREMENT table you would just comment out the lines:

//   ft = new FieldTrans("temp_esd");
//   strk.add(ft);

located in the method:

 public void do_CELL_MEASUREMENT(ModuleTrans cmod, ModuleTrans[] modQual)
   {    
...
   }

To add a field you would simple add the new FieldTrans lines to a table e.g.

   ft = new FieldTrans("pdbx_details");
   strk.add(ft)

in the method:

    public void do_EXPTL_CRYSTAL_GROW(ModuleTrans cmod, ModuleTrans[] modQual)

The RootTrans.java class contains definitions which are common to all of the models. Individual models such as that defined by the DevRootTrans.java subclass, define specific structures and fields for a particular build target.

Compiling OpenMMS

It is important to distinguish between what are referred to as Initial builds vs. Incremental builds. These have the following characteristics.

Initial Builds

• After the source code in a "SourceOnly" distribution is untarred, or following a "gmake clean" in the top-level openmms, the first gmake done in this top-level directory is an Initial Build.

• An Initial Build can only be done by executing gmake in the openmms directory.

• Once an Initial build is done, the Build_Target (Model_Name) is fixed. The model can then only be changed by doing a top-level "gmake clean" followed by a new Initial build.

• After an Initial build is done, all subsequent gmakes are Incremental builds until a "gmake clean" is done in the openmms directory.

Incremental Builds

• An incremental build may be done in the top-level openmms directory or any of its subdirectories that contain a Makefile.

• Incremental builds will build the current working directory and the subdirectories below it as specified in the Makefile.

• An incremental build can be started by executing gmake with no arguments; the build target will default to the one used in the last Initial build. If a target is specified on the gmake command line, it must match that specified in the last Initial Build or gmake will exit with the error: "No rule to make target ... ".

The name of the target specified in the last Initial Build is stored in the file log/build_target. If this file is removed or its contents are modified, all bets are off regarding the subsequent results. This file is removed following a successful top-level "gmake clean". The configuration files discussed below make the contents of this file available to the Makefiles in the variable $(BUILD_TARGET).

It should be noted that a top-level clean is quite extensive in it effect. This is necessary to remove any model dependent information. This includes removing all compiled class files, all IDL, SQL and XML, and all derived Java code in subdirectories of src/mms/deriv.

Care should be taken not to leave any important files in the src/mms/deriv, classes or docs/api directories since they will subsequently be removed and lost during the next "gmake clean".

Both Initial builds and Incremental builds can be started in the openmms top-level directory. In either case, a complete record of the most recent top-level openmms build is saved in the file log/MAKE.LOG. Similarly the record of the output generated by the most recent top-level openmms "gmake clean" is stored in log/CLEAN.LOG.

In order to make the Makefiles easier to write and maintain, the common variables and function definitions have been factored into four gmake "configuration" files located in the config directory.

localdefs.gmake
The configuration file config/localdefs.gmake is the most important file for setting up a new OpenMMS development environment. The variables in this file define the location of the Java and IDL compilers, the local directory where mmCIF data files are kept and the absolute path of some standard Unix commands. Once the variables in this file are defined correctly for the local machine, the entire OpenMMS should compile and build without any other modification.

A typical Makefile file is src/mms/util/Makefile. Using a shell command, the $(TOP_DIR) variable is set at the beginning of each Makefile to the absolute path of the "root" of the OpenMMS tree (the openmms directory). Near the top of each Makefile is the statement:

include $(TOP_DIR)/config/openmms.gmake

The file config/openmms.gmake in turn includes the two configuration files config/localdefs.gmake and config/stddefs.gmake. Near the bottom of each Makefile is the statement:

include $(TOP_DIR)/config/rules.gmake

These configure files define a many variables that are used in the Makefiles. They also define the rules for making various intermediate targets and the order in which they should be made.

In the middle of the Makefile the four variables:

Package        = ...
Sources        = ...
Dependencies   = ...
Build_Subdirs  = ...

are defined. These variables are used by in the four configuration files to specify the following:

Package

Defines where in the classes directory this package should be installed

Sources

Defines all the source files that need to be compiled

Dependencies

Defines which other files the sources are dependent upon. If any dependent files are newer that the source files, the sources will be recompiled.

Build_Subdirs

Defines which subdirectories of the current directory also contains Makefiles and should be built. These subdirectories will be built in the order they appear in this list.

Send mail to: info@rcsb.org

The Documentation Index lists all documentation included with this OpenMMS release.

The OpenMMS API Specification provides brief descriptions of the OpenMMS packages, classes and interfaces.

The OpenMMS Overview - Additional Information section lists several URLs with related information.