HOWTO Build ZipTie

This HOWTO will show you how to setup the entire ZipTie development environment. Building ZipTie requires scarcely more than extracting the source and typing ant dist dbreset in the Build project directory. But we assume that you're building the source because you want to work with the source, and therefore you'll want to setup the development environment. Hence this HOWTO.

If all you want to do is browse the source, you can access the repository on the web at http://fisheye.ziptie.org/.

• Ant version 1.7 or above. Download from here http://ant.apache.org/bindownload.cgi
• Java 5 or Java 6 (currently we recommend Java 5 because there are changes to your environment needed to make ZipTie compile under Java 6)
• Perl 5.8.8 or above
• Eclipse 3.3+

Eclipse is not stictly required, but all of these instructions are given in terms of using Eclipse.

The following only applies if you are running a version of java 6 prior to 1.6.0_04. In 1.6.0_04, sun packaged JAXB v 2.1 instead of JAXB 2.0.

If Java 6 is being used to compile the ZipTie source code, then the manual installation of two JAR files are required: jaxb-api.jar and jaxws-api.jar. This is due to Sun including backlevel versions of libraries in the JDK that ZipTie depends on for the Web Services component. ZipTie uses JAXB 2.1, while JDK6 ships JAXB 2.0.

To install the jaxb-api.jar and jaxws-api.jar, do the following:

1. Within the jre\lib directory of your JDK6 install, create a new directory called endorsed
2. Navigate to the org.ziptie.zap.metro\lib directory in your ZipTie directory.
3. Copy the jaxb-api.jar and jaxws-api.jar files from the org.ziptie.zap.metro\lib directory to the jre\lib\endorsed directory in your JDK6 installation.

You will notice an error like this if you do not have the jaxb-api.jar and jaxws-api.jar files properly installed:

C:\Dev\ziptie\HEAD\Build\build.xml:119: The following error occurred while executing this line:
C:\Dev\ziptie\HEAD\org.ziptie.provider.scheduler\build.xml:8: The following error occurred while executing this line:
C:\Dev\ziptie\HEAD\Build\buildCG.xml:87: You are running on JDK6 which comes with JAX-WS 2.0 API, but this tool requires
JAX-WS 2.1 API. Use the endorsed standards override mechanism (http://java.sun.com/javase/6/docs/technotes/guides/standards/), or set xendorsed="true" on <wsgen>.

Total time: 5 seconds
C:\Dev\ziptie\HEAD\Build>java -version
java version "1.6.0_02"
Java(TM) SE Runtime Environment (build 1.6.0_02-b06)
Java HotSpot(TM) Client VM (build 1.6.0_02-b06, mixed mode, sharing)

To actually work with the source you will need to extract it from our CVS repository.

For command line users the CVSROOT variable would look like :pserver:anonymous@cvs.ziptie.org:/usr/local/cvsroot. ZipTie is composed of many projects, but all of the ones necessary to build the distribution are encapsulated in the ziptie module alias. If you “check out” the ziptie module, you will get all of the projects necessary to build ZipTie.

The first thing to do is create a new Eclipse workspace. Once in that workspace, open the CVS Repository perspective and right-click in the left navigation area and choose New → Repository Location…. You should get a dialog similar to the following dialog, fill it out with the values listed above (and shown in the image):

Once connected, expand the repository entry in the tree and then expand the HEAD node. You should see a list of projects. Scroll down and find the project called ziptie, which is an alias (“super-project”) that is comprised of the proper set of projects in the repository. Once you find the ziptie project, right-click on it and select checkout as shown in the screen capture below:

Depending on the speed of your connection, the checkout will take anywhere from a few minutes to half and hour or so.

Before you go on to compiling, follow these steps to configure your Eclipse workspace for ZipTie development.

Go to Window→Preferences→Plug-in Development→Target Platform and change the Location to point at workspace/TargetPlatform/eclipse

The ZipTie team uses specific code style setting in Eclipse to format our code. Formatting with this template should result in a file that is compliant with the ZipTie Coding Standard as well as complying with the enforcement rules of Checkstyle. All files should be formatted with these settings (Shift-Ctrl-F in Eclipse).

The import file for the coding style is located in the Build project in the /conf directory.

The ZipTie team uses the following code template. It ensures that all files have the appropriate Mozilla Public License (MPL 1.1) banner at the top, as well as other minor formatting tweaks.

The import file for the coding template is located in the Build project in the /conf directory.

This is the Eclipse plugin for the Checkstyle project, and provides enforcement of our code style settings as well as the ZipTie Coding Standard. In Eclipse, go to Help→Software Updates→Find and install… to install the eclipse-cs plugin.

eclipse_cs update site: http://eclipse-cs.sourceforge.net/update

After installing the plugins, follow these instructions to configure:

• If a method overrides a parent's method, you should remove whatever comment it has. Then position your cursor on the method name and press CTRL-ALT-J to automatically add the appropriate comment. It will add a comment like this: /** {@inheritDoc} */
• Empty blocks are not allowed. In almost every case you can: 'continue' or 'break' if in a loop, 'return', or log something. If you can't do any of these, think about restructuring the code. If you still can't eliminate it, let me know (mailto:brett@ziptie.org).
• We have the following maximums set:
  • Line length: 160 characters
  • File length: 2000 lines
  • Method length: 160 lines (if it's longer than this, you should refactor the code. we will entertain raising this to 180 lines)
  • Max parameters: 7
• See this link if you can't figure out the error/warning: http://checkstyle.sourceforge.net/config.html#Modules
• JavaDoc is required on all public methods. Use CTRL-ALT-J on the method name to get the best boiler-plate to work from.
• The “Magic Number” warning can perhaps be the most annoying to deal with. This occurs when you use something like “23” or “1000” in a method. Sometimes the reader of the code can't understand where the value came from or what it means (sometimes they can). The fix for this is to define a constant (select the number, right-click → Refactor → Extract Constant). In this case, probably DEFAULT_TELNET_PORT = 23, and ONE_SECOND = 1000 (or maybe TIMEOUT_MILLIS = 1000).

The ZipTie development team uses the FindBugs plugin.

FindBugs Eclipse update site: http://findbugs.cs.umd.edu/eclipse

The ZipTie development team has started using the Metrics plugin. We are experimenting with this tool and do not currently have guidelines about its use. Use it to inform your development, but feel free to ignore some of it's warnings. Additionally, this is a plugin that you should Disable (in the project settings) when you're not looking for it's advice – it is very expensive to run. You will need to clean build after Enabling it.

Metrics Plugin: http://sourceforge.net/projects/metrics

Unfortunately, this tool does not provide for import/export of settings so here are our recommendations:

Metrics Preferences → Safe Ranges

Some of these metrics, in this author's opinion, are fairly meaningless at worst or hard to quantify a “good” range for at best.

See this link for a discussion of the metrics: http://open.ncsu.edu/se/tutorials/metrics/index.html#section4_0

You can do the full build from the “Build” directory by executing the command below:

 ant clean dist dbreset

If your “ant dist dbreset” runs out of perm gen space, increase it by setting the following environment variable.

 
 ANT_OPTS = '-Xmx960m -XX:MaxPermSize=128m -XX:PermSize=64m'

For Windows developers: if mxmlc (located in <workspace>\TargetPlatform\flex\bin) returns fatal error saying that it could not find JVM (Error: could not find a JVM.) probably you'll have to set JVM in the jvm.config located in the same folder.

 
 java.home=C:/<JDK_ROOT>/jre

IMPORTANT: USE FORWARDING SLASHES.

If this setting does not resolve the issue uninstall JRE (if you have one installed).