DiGIR Development Setup Guide

This document is provided to aid a developer in setting up his/her machine for doing development on the DiGIR Portal. Some of the items are recommendations while others are requirements. The document centers on the setup for developing on a Windows machine and was drafted during setup on a Windows 2000 Professional (with service pack 2) machine in specific. Also, an assumption is made that the developer has working knowledge of their own operating system, the internet, and development tools in general.

1. First and foremost, DiGIR is an established project on SourceForge.net. You will want to familiarize yourself with SourceForge and with the DiGIR materials on the SourceForge site.

2. It is also assumed that you've already done an install, as instructed in the DiGIR Portal Installation Instructions. If you have not done so, you will need to do so now. This will establish the necessary directory structure in which to work, as well as provide all the required software and libraries.

3. As a developer, you will need to register on SourceForge and be able to access the code repository. You should follow the documentation provided by SourceForge to get access to the repository. Some quick recommendations that might ease the process and differ from the doc:

   • Install Cygwin. Doing so allows you to acquire all the utilities mentioned in the above documentation from one place. Pay close attention and ensure you install the following utilities:
     • cvs
     • ssh (contained within the open-ssh package)
     • scp
     • make
     • optionally, vim (or another editor, such as nano, which will be easier for a novice)
     Cygwin installation tips:
     • Run Cygwin's setup.exe specifying "Download from Internet"
     • Create a directory specificly to be used as your "Local Package Directory".
     • Select a "Download Site" that you are familiar with. If you are not familiar with any of them, choose a .edu or .gov site. For speedier download, try not to choose a site in another country.
     • When choosing packages, sometimes its easier to find things by changing the view. This is done by clicking "View".
     • You do not need to download the src files.
     • After downloading packages, you must rerun setup.exe but specify "Install from Local Directory" and specify your "Local Package Directory" you created when asked.
     • After your installation is completed, you will want to modify your PATH environment variable to contain the cygwin bin directory (where the executables are stored).
     • You can rerun setup.exe and grab more packages and install them. There is no limit to the number of times you may need or want to run setup.exe.
     If you install Cygwin, it may not be necessary to set up the /etc/passwd file as directed in the SourceForge documentation. Also, Cygwin provides a command-line cvs client. You may use a GUI client if you prefer, but they are often cumbersome and can be more difficult to configure, especially for use with SourceForge, which requires ssh to authenticate.

   This is really the hardest part of getting set up to do development, but once you have your environment set up, it should be smooth sailing.

4. After all the necessary utilities are installed, you will want to checkout the src, web and xml packages from SourceForge. You should do this in your established %DIGIR_HOME%/src directory. For further information on how to do this, refer to the "How to check out source via SSH" section of the documentation on SourceForge. A brief overview:

   • cd %DIGIR_HOME%/src
   • cvs -d:ext:loginname@cvs.digir.sourceforge.net:/cvsroot/digir co directoryname where directoryname is either java, web or xml

5. The current Portal software is written in Java and uses a servlet/jsp architecture running under Tomcat. All the required libraries, such as logkit, uddi, soap, xalan, etc. are already provided for you in the %DIGIR_HOME%/lib directory. A shared makefile (makefile_main.mk) establishes your CLASSPATH for you whenever running make in any of the package directories. For your reference, the files in the lib directory are:

   • xerces.jar obtained from a Jakarta Tomcat 4.0.3 install
   • logkit-1_0_1.jar obtained from a Avalon Logkit 1.0.1 install
   • xalan.jar obtained from a XALAN-Java 2.4.D1 install
   • xml-apis.jar obtained from a XALAN-Java 2.4.D1 install
   • soap.jar obtained from a Apache SOAP 2.2 install
   • uddi.jar obtained from a UDDI4J 1.0.3 install
   Note we are using the xerces.jar that came with the Standard install of Jakarta Tomcat. Also, SOAP is required by UDDI. Lastly, the latest version(s) of UDDI4J underwent a complete package naming change and are not backwardly compatible, therefore, until the portal upgrades to accomodate this change, one should continue to use verion 1.0.3 of UDDI4J.

   You do not need to download and install any of these packages as they have already been provided for you in the DiGIR_Portal_Env.zip file. This was done because they are tested, known to be compatible, and also provides you with a certain level of stability.

6. Makefiles are provided to build the application. You will find a Makefile in the web directory which simply copies the front end files into the appropriate place within your DiGIR directory structure. All files in the web directory are used by the presentation layer of the portal. The java directory contains source for both the presentation and engine layers. You will find the following packages in the java directory:

   • org.calacademy.digir.engine
   • org.calacademy.digir.presentation
   • org.calacademy.digir.common
   • org.calacademy.digir.util
   In the directories for each of these packages exists a Makefile that will build and install the application files in the appropriate DiGIR webapp space. The common and util packages are used by both the engine and presentation packages and therefore you will find they're makefiles slightly more elaborate. Lastly, at the topmost level in the java directory is a Makefile that simply invokes the make file for each of the packages listed above. This enables you to build the entire application at once. Also note, each makefile provides a "clean" option. If you are not familiar with make, please refer to the GNU make documentation.

   A brief overview of how to make a code change:

   1. cd to the directory containing the file of interest
   2. edit and save the source file
   3. run make (by typing make on the command line
   4. debug as necessary
   5. test the change in the running application

A recap of the environment variables that should have been set: CYGWIN_HOME - location of the Cygwin install (e.g. C:\cygwin) CVSROOT - username@cvs.digir.sourceforge.net:/cvsroot/digir CVS_RSH - ssh JAVA_HOME - location of Java 2 install (e.g. C:\j2sdk1.4.0) CATALINA_HOME - location of Tomcat install (e.g. C:\jakarta-tomcat-4.0.3) PATH - append %CYGWIN_HOME%\bin;%JAVA_HOME\bin%; DIGIR_HOME - set to the install of the DiGIR_Portal_Env.zip directory