Developing ADTPro

The build system for ADTPro actually uses several components that are not readily visible. The full list looks like this:

  • Apache Ant - orchestrates the build process
  • Java SDK - compiles Java-based server
  • cc65 - a multiplatform toolchain with a nice 6502 macro assembler
  • rxtx - multiplatform Java serial library
  • Maven - optional; builds these web pages
  • Apple Pascal - optional project to build the Apple /// VSDRIVE driver

The main Ant build.xml script in ADTPro's CVS repository calls upon these tools to go from source files to distributable packages. Well, with the exception of the Maven website stuff - that's not part of the main build script, mostly because that's a step most people wouldn't ever want to do, and if it were there - they'd need to have Maven installed.

Everyone has their favorite integrated development environment (IDE). I happen to use Eclipse, so I'll provide setup information for that. Other IDEs are similar, and surely address your own pet peeves. This page happens to show screenshots of a Windows setup, but there's nothing particularly Windows-ey about the build process. It should run on any platform that can support all of the build tools. I have tested it myself on Windows, Mac OSX, and SuSE Linux.

Table of Contents:

Starting from Scratch

Let's assume you have a clean machine and want to make this thing build. The minimum amount of work you'd go through to do so:

  • Download and install Eclipse from http://www.eclipse.org
  • Download and install a full Java JDK if your Eclipse distribution doesn't come with one
  • Download and install the cc65 toolchain from http://www.cc65.org - you only need the one for your development platform (Windows, OS/2, Linux - not the 8-bit support modules)

Downloading/Importing the ADTPro Project

Connect Eclipse to the ADTPro CVS repository on Sourceforge by going through the next few configuration dialogs in Eclipse.

  • From the Eclipse IDE: File->New->Project, then: CVS->Projects from CVS:
  • Fill in the CVS repository info:
  • Pick, or type in, adtpro for the module name:
  • Check it out to the workspace:

You now have the entire ADTPro project checked out to your workspace, and it probably looks angry (see the red X marks):

The problem is that the Java code can't automatically compile in the workspace because the project needs to resolve a support jar right away: Ant.jar. So, we need to go into the project properties and tell it where to find it.

Configuring the Project Properties

Resolving the external jar dependencies is easiest to do by right-clicking on the top-level "adtpro [adtpro.cvs.sourceforge.net]" object in the package explorer, then picking Build Path->Configure Build Path... from the context menu. The Java Build Path dialog box will come up; then click on the Libraries tab:

Now, we need to build "User Libraries" to match ANT_JAR. Click on the "Add Libarary..." button, and select the "User Library" item when the "Add Library" dialog box comes up:

Click on the "Next" button, and the Add Libarary/User Library dialog box comes up:

Click on the "User Libraries..." button, and the Preferences/User Libraries dialog box comes up:

Click on the "New..." button, and the "New User Library" dialog box comes up:

Now we'll fill in ANT_JAR. Type ANT_JAR in as the name, and hit the "OK" button. The Preferences/User Libraries dialog box will come back up, and will now have the ANT_JAR user library name in it:

Click on the "Add JARs..." button, and the "JAR Selection" dialog box will come up. Navigate to where you have an ant.jar file in your local filesystem. The very Eclipse you're using now will have one in its eclipse/plugins/org.apache.ant_1.6.5/lib directory:

Click the "Open" button. That will associate your ant.jar with the ANT_JAR user library:

The main Eclipse window should no longer show any red errors, though it may still have yellow warnings (depending on how tidy the repository happens to be right then).

Configuring the Build Script

In the Package Explorer, expand the build section. Look for the file named ADTProBuild-default.properties. You want to make a copy of that and rename it ADTProBuild.properties and customize it for your location. The easiest way to do that is to click on ADTProBuild-default.properties, then hit Ctrl-C, then Ctrl-V. That will copy and paste the file into the build directory, and demand you rename it all at the same time:

Double-click on your new ADTProBuild.properties file. You will need to point the assemblerPath variable to where you have the cc65 toolchain bin directory installed. The full line should look something like this, assuming you unzipped cc65 into a directory named cc65:

<property name="assemblerPath" value="/usr/local/cc65/bin" />

The value you specify in ADTProBuild.properties will override all others, so you can keep this local file to tailor your local build and not affect other developers.

Starting a Build

All that's left to do now is hit the shiny build button. Right-click on the build.xml file in the Package Explorer, pick Run As...->Ant Build, and all the magic should happen:

The "BUILD SUCCESSFUL" message is the indication of success, obviously enough. You can start subsequent builds now that the first one happened by just clicking on the little suitcase button:

The build output goes to the place where your Eclipse workspace directory is. The exact location will appear in the console output. In the Eclipse picture above, you can see the path listed in the [zip] line. The build output will consist of the server .jar file, the ADTPro client contained on a .dsk file, the DOS ADT client contained on another .dsk file, and a .zip file of the complete distribution package.

Building Without an IDE

If you would like to build ADTPro without the aid of an IDE at all, there are a few environmental things you will need to do by hand that they typically do for you automatically. You will still need the toolsets listed at the top of the page (except Maven and the Apple /// build).

Ant will marshal the tools and produce the build for you. In order to just type ant in the build directory, though, there are a few things it needs to know:

  • Copy the file named ADTProBuild-default.properties to ADTProBuild.properties and customize it for your location. You will need to point the assemblerPath variable to where you have the cc65 toolchain bin directory installed. The full line should look something like this, assuming you unzipped cc65 into a directory named cc65:

    <property name="assemblerPath" value="/usr/local/cc65/bin" />

    The value you specify in ADTProBuild.properties will override all others, and is not checked in to CVS; so you can keep this local file to tailor your local build and not affect other developers.

  • Your CLASSPATH environment variable must be configured to point to an ant.jar library; that would typically be something like this: apache-ant-1.3.0\lib\ant.jar. Just look around at where your Ant installation is, and you'll be able to find your local ant.jar file.
  • CLASSPATH must be configured to know where ADTPro itself will reside; the build actually relies on the AppleDump utility that must first be compiled with javac before Ant can take over the rest of the build. That location would typically look something like this; however it will be based on exactly where you checked out the ADTPro project: \src\checkout\adtpro-by-hand
  • The AppleDump utility must be built. If the CLASSPATH is set up correctly, all that will be required is this command, as run from the directory where the project is checked out: javac org\adtpro\utilities\AppleDump.java

So, an example of how this sequence of events might look in practice:

cd \src\checkout\adtpro-by-hand
set CLASSPATH=%CLASSPATH%;\dev\ant\apache-ant-1.8.2\lib\ant.jar;\src\checkout\adtpro-by-hand
javac org\adtpro\utilities\AppleDump.java
cd build
ant

Once your CLASSPATH environment variable knows where to find ant.jar and AppleDump.class, you can just run ant from within the build directory from then on.