We like to keep programming tools and related programs, examples, documents, etc away from the Windows default of "C:\Program Files" for several reasons.

Don't use whitespace in folder names! Many tools (still) consider whitespace in a file path to be a delimiter and will therefore not work in, or on, any folder tree with spaces in the folder names. Command line tools in general cannot tolerate white space and it's a hassle enclosing it in quotes or other gimmicks. White space in paths and file names is poor computer use and programming hygiene anyway, so we try to avoid it. In addition, why wade through more layers of folders than you need to? I want to see Ant, JDK, etc just one folder away from the drive root, not buried needlessly.

We generally divide our computer disks into at least two logical drives(or better yet, two physical drives) and use one for programming tools. This keeps frequently updated files out of the all-important Windows system files area, and lets us reorganize that whole drive as needed without fear of crippling the operation of the PC.

It's nice to be able to share build files with other PCs on our network or outside our company, so we try to use a common folder structure on each PC and mask the minor differences by using system environment variables. For example, JAVA_HOME points to the root folder of whatever Sun JDK is installed on that PC. So a reference to JAVA_HOME/bin will find the java tool executables on any PC in our office, or on any of our customers' systems.

There is a bit of a chicken-and-egg situation here. You want to set up Windows environment variables to create relative references to Java tools. For example JAVA_HOME should refer to the root folder of your JDK installation. For example, D:\j2sdk14. Then, you install some other files, or create other references, to sub-folders of this by using the JAVA_HOME reference. For example, you copy javaxcomm's win32com.dll to <JAVA_HOME>/bin. What's confusing is, in the process of installation you use these references. So do you

1. create all the system environment entries first, then install the tools?
2. create each tool's entries as you install each tool?
3. install all the tools first, then create all the entries?

It really doesn't matter which approach you take, since in the end they all produce the same result. My choice is 2 or 3, but do whatever you prefer.

I installed JDK 1.5 release 6 onto C:\JavaSoft\jdk1.5.0_06 so that I would not have whitespace in the default "Program Files" folder. Plus, I prefer to have all my java related tools in a common folder to make maintenance easier. Set a browser bookmark to the online javadocs, and/or download the docs file to your local disk. If you install JDK 1.4 be sure it is 1.4.1 or newer, as 1.4 had a bug which breaks cross-compilation.

If you wish you can also set one to the downloaded javadocs (if you also installed them).

Note that the JDK includes the Java Runtime Environment or JRE. You might already have one installed under a Windows folder. Some applications such as browsers insist on installing their own, too. To make your life simpler try to have as few different JREs as possible so that you know for sure which version of "java.exe" you are invoking. We'll make some system and environment settings a bit further on which will also help.

Javaxcomm is the standard serial communications package for all true Java hardware. It's required to use TINI's JavaKit. Javaxcomm runtime support is built into the aJile runtime but the documentation is not. Plus, you will want eventually want to run serial code on the PC, for which javaxcomm is required. So for all embedded Java systems, and use on the PC, you want to install this package.

I installed the javaxcomm files into a <JAVA_LIB>/commapi folder which for me is c:\java_lib\commapi. See environment variables for help setting this up.

Create a bookmark to the javaxcomm javadocs in your preferred browser.

Setting up javaxcomm drives almost everyone nuts at some point, so don't get discouraged if you have some trouble the first time. Note: there are errors in the javaxcomm instructions. Ignore them and follow these instead.

1. Read the PlatformSpecifc.html file, but just for background. It contains errors. Follow these instructions instead:
2. Copy win32com.dll to <JAVA_HOME>\bin
3. Copy comm.jar to <JAVA_HOME>\jre\lib (this is where the javaxcomm instructions are in error)
4. Copy javax.comm.properties to <JAVA_HOME>\jre\lib (this is where the javaxcomm instructions are in error)
5. Add comm.jar to your CLASSPATH. This entry looks like "%JAVA_HOME%\jre\lib\comm.jar;"

Note that comm.jar and javax.comm.properties must be installed under the \jre\ file tree, but win32comm.dll is installed in the JDK bin folder, which is also where javac, javadoc, etc tools are also installed. So you will need to have this <JAVA_HOME>\bin folder in your PATH environment variable anyway. It's perfectly OK to have some files in the JRE area (the only place they will work) and the DLL file in the JDK area (will work anywhere - this is just a more logical place than in the \jre\bin folder). For more details about this confusing mess, see the javaxcomm debugging page.

1. Add the environment variables referenced above: JAVA_HOME, JAVA_LIB, and classpath.
2. Also the <JAVA_HOME>/bin folder must be in your PATH in order to access the "java" command. To be safe, make this the first entry in your path, so that you don't unintentionally invoke other "java.exe" which may exist on your system.
3. Add BlackBox.jar to your classpath, temporarily. Do this at a DOS command prompt by typing (or you can copy and paste this line)::
   set CLASSPATH=%JAVA_LIB%\commapi\samples\BlackBox\BlackBox.jar;%CLASSPATH%
   Note that the javaxcomm instructions in PlatformSpecifc.html have an error - the example is located in samples\BlackBox, *not* samples\Blackbox ("BlackBox" has two uppercase Bs). Java and Java tools are generally case-sensitive so this is important.
4. Now at a command prompt type
   java BlackBox
   and you should see the BlackBox example start and show ownership of COM1.
5. If BlackBox did not start and you instead saw a cryptic error message (it seems to happen to me everytime I install these tools on a new PC), this javaxcomm debugging page may help.

I installed into d:\eclipse. Do not install Eclipse into a "Program Files" folder on any drive, or into a path containing any whitespace! If you do, the whitespace can cause other tools to fail, if they will be accessing folders within the Eclipse install.

If you only installed the Eclipse runtime, you will also need to install the JDT runtime files. They unZIP into the plugins subfolder of eclipse.

1. Change the Window>Preferences>Java>Installed JREs to refer to the <JAVA_HOME>/JRE folder instead of the default which Eclipse used when it was installed. After you do this, Eclipse will ask for a full rebuild of any open projects. This is OK.
2. Add the tools.jar to the Preferences->Ant->Runtime classpath. See Ant Tips and Eclipse Ant Tips for why and how to do this.
3. Use System Environment Variables and Eclipse Classpath Variables to make your buid.xml files truly portable, maintainable and reusable.

1. Rename the Eclipse Ant plugin folder to something else so that it doesn't get accessed, here's what I did: C:\eclipse\plugins\org.apache.ant_1.6.5_UseExternalAntInstead
2. Be sure you have a system environment variable ANT_HOME pointing to your Ant install such as C:\apache-ant-1.6.1
3. Add the Ant bin folder to your system path so you can execute Ant from the command line, adding this to your path: %ANT_HOME%\bin;
4. Tell Eclipse you are using this "external" Ant for all Ant operations. This is done in the Eclipse main menu Window->Preferences->Ant->Runtime. Click on the Ant Home button and browse to the same folder assigned to the ANT_HOME environment variable.
5. Add a confirmation message to the init target in all your ant builds:
   <echo message="ANT_HOME is set to = ${env.ANT_HOME}"/>
   which will tell you at every build that the correct version of Ant is being invoked.
6. Now test both the Eclipse Ant and command line Ant to see that you indeed are using the same Ant executables in both cases.

You will want TINIAnt (only if you will be using TINI) and Netcomponents (for the FTP task, useful with TINI and SNAP). See the details and links in the Ant tools page. I installed the whole TiniAnt zip file into its own default folder, so I'd have the Javadocs for it. Then I copied just TiniAnt.jar into the Ant lib subfolder. I extracted and copied just the NetComponents.jar file from the Netcomponents ZIP file into the Ant lib subfolder.

2006 Jul 31 - Netcomponents is replaced by Jakarta Commons Net, current version is commons-net 1.4.1. I unzipped both it and Tini Ant under a "JavaSoft" parent folder and then copied the TiniAnt.jar and commons-net-1.4.1.jar into the Ant /lib subfolder.

I installed into C:\JavaSoft\jdk1.5.0_06. So I set a system environment variable JAVA_HOME with the value C:\JavaSoft\jdk1.5.0_06 (no trailing backslash for reasons which will be apparent soon). In XPPro this is Settings->Control Panel->System->Advanced->Environment Variables. You wil want to add some or all of the variables listed below. (Use your own values here, I'm just listing mine as a reference). I set all these as system rather than user variables since multiple users will want to access all the Java tools installed. But you could make these user variables so that someone else could log into a given PC and set up their own environment.

Don't include variables which don't apply to you --if you are using only JStamp, JStik, or SaJe then you don't need TINI or SNAP tools or their environment variables. Note that none of these paths contain white space! White space still breaks many utilities and tools, so don't use it in any system paths (class paths, windows system paths, etc).

On a recent new XP Pro system (my office workstation) I set all these as System Variables, since anyone who uses this PC will also want access to the same tools I've installed. You can, of course, make some of these paths User variables if you expect different users to desire different system configurations.

JAVA_HOME value= C:\JavaSoft\jdk1.5.0_06
ANT_HOME value= C:\apache-ant-1.6.1<< older versions were jakarta-antxxx
AJILE_HOME value= C:\aJile
AJILE_CLDC value= C:\aJile\Runtime_cldc << I just changed this part of my builds
JAVA_LIB value= d:\java_lib
CLASSPATH value = %AJILE_CLDC%;%TINI_HOME%\bin;%CLASSPATH%
PATH value= %ANT_HOME%\bin;%JAVA_HOME%\bin; {rest of your path}
SNAP_HOME value= C:\snap0.7.1
TINI_HOME= C:\tini1.11

Note that I only have the value of a given variable hard-coded *once*. Thereafter I refer to it with the symbolic reference such as %JAVA_HOME%. Also note that I have added my new variables ahead of any existing classpath or path entries. The current Windows classpath is the symbolic reference %CLASSPATH%.

That's it. You do not need to reboot your PC. All *new* command prompt windows will inherit these values.

1. System environment variables can refer to User variables but not vice-versa.
2. Include a '.' in your CLASSPATH variable so that you always have a reference to the current/default folder. Failure to do this will prevent you from running a packaged class from the package root folder.

1. create file path references in *one* easily maintained place
2. help prevent tool version clashes and confusion
3. create system environment variables which you can access from the command line, batch files, and Ant
4. eliminate all hard coded paths in your Ant build files and batch files. This makes your Ant build files truly portable around your office network, on a portable notebook PC, etc. It also enables sharing build files with customers. Any hardcoded values such as IP addresses, passwords, etc (which you may not want to share anyway) can be moved into a single, small properties file.

1. Eclipse project files include absolute paths, so Eclipse projects are not portable. However, your Ant build files can be. Maybe Eclipse projects could be portable if you religiously use Eclipse Classpath Variables. We'll update you on this as time (and each new Eclipse version) rolls on.
2. JemBuilder project files also include absolute paths. We don't know how to make these relative.

For clarity I have trimmed off unrelated information and truncated the path and classpath:

D:\>set
AJILE_HOME=D:\aJile
ANT_HOME=D:\apache-ant-1.5.4
CLASSPATH=D:\j2sdk14\lib;D:\j2sdk14\lib\comm.jar;
JAVA_HOME=D:\j2sdk14
JAVA_LIB=D:\java_lib
Path=D:\apache-ant-1.5.4\bin;D:\j2sdk14\bin;
SNAP_HOME=D:\snap0.7.1
TINI_HOME=D:\tini1.11

Now see if the system can find the PC's JVM:

D:\>java -version
java version "1.4.1_01"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1_01-b01)
Java HotSpot(TM) Client VM (build 1.4.1_01-b01, mixed mode)

And Ant:

D:\>ant -version
Apache Ant version 1.5.4 compiled on August 12 2003

Save yourself and others a ton of wasted time and headaches. Create a virtual drive to serve as the root of all your java projects. Do this so that all your Eclipse and Ant project files are truly portable. If all members of a project team follow these guidelines, all your Eclipse .classpath files, and Ant build.xml files will be usable by everyone on the team with no changes! There will be no hard-coded paths such as "D:/aJile/Runtime_cldc/Rts.jar"

It's a simple system and doesn't take much time to set up. Even if you are a development team of one and/or have multiple development computers (I have desktop PCs at the office and a notebook for home and travel) this is a huge timesaver. All my Eclipse .classpath files, Ant build.xml, and many aJile .ajp files move between computers with little or no editting. This saves hours on multi-package projects such as JCX.

In the folder C:\Documents and Settings\All Users\Start Menu\Programs\Startup create a batch file such as "MapDriveP.bat" which contains this line:
subst p: c:/projects
This batch file will execute every time your notebook starts up. Now on your notebook you can refer to your Java projects root with "P:\"

Eclipse includes built-in support for CVS. Configure this by either 1) adding a new repository in the CVS Repository Browsing perspective, or 2) Eclipse main menu Window->Preferences->Team->CVS.

You can refer to a repository with an alias or a hardcoded IP address. If you want to use an alias, usually a text string, instead of a hardcoded IP address for a CVS repository, add it to the "hosts" file in C:\WINDOWS\system32\drivers\etc.

Java.net uses pserver, others may use ssh.