CLASSPATH

The CLASSPATH environment variable tells the Java Virtual Machine and other Java applications (for example, the Java tools located in the jdk1.1.x/bin directory) where to find the class libraries, including user-defined class libraries.

SYNOPSIS

The CLASSPATH environment variable is set with the setenv command. Using setenv at the command line changes the current value of CLASSPATH. You can also use setenv in your startup file to specify a CLASSPATH at startup. The format is:

   setenv CLASSPATH path1:path2 ...

where a path to a .zip or .jar file must terminate with the filename, and a path to a .class file must terminate with the directory name. The Java interpreter will search the paths for a class by name and load the first one it finds.

DESCRIPTION

The CLASSPATH tells the Java Virtual Machine and other Java applications and tools where to find the class libraries. The class libraries that the CLASSPATH points to may be the JDK classes (contained in the classes.zip file in the lib directory) and/or any classes that you want to use.

Default class path

If the CLASSPATH environment varialbe is not set, the following default class path will be used:

   .:[bin]/../classes:[bin]/../lib/classes.zip

The dot, ., represents the current directory. The symbol [bin] stands for the absolute path to the jdk1.1.x/bin directory. Therefore, if you keep the bin and lib directories at the same directory level, the Java executables will find the JDK classes (contained in the classes.zip file). Note that the default class path also includes a path to a classes directory on the same directory level as bin and lib. You can put your own (unzipped) class files in a classes directory that you create, and the Java executables will be able to find them with the default CLASSPATH.

You should also be aware that some third-party applications that use the Java Virtual Machine may modify your CLASSPATH environment variable.

Setting CLASSPATH

You need to set the CLASSPATH if you move the JDK's classes.zip file or if you want to load a class library that's not in a location specified by the default CLASSPATH. To set CLASSPATH, use the setenv command.

Note that when you set the CLASSPATH environment variable, the current directory is no longer automatically placed on the class path.

Classes can be saved either in individual class files, such as MyClass.class, or in groups in a file such as classes.zip or classes.jar. When specifying a path to a .zip or .jar file, you must end the path with the filename. When specifying a path to .class files, that path should end with the directory containing the .class files. For example, if you have class files in the directory /home/MyClasses, you could set the CLASSPATH with the following:

   setenv CLASSPATH /home/MyClasses

If you also wanted to include the path /home/OtherClasses, you could use the command:

   setenv CLASSPATH /home/MyClasses:/home/OtherClasses

Note that the two paths are separated by a colon. Because the current directory is not automatically considered to be on the class path when the CLASSPATH environment variable is set, you might want to explicitly add the current directory to CLASSPATH:

   setenv CLASSPATH .:/home/MyClasses:/home/OtherClasses

The order in which you specify multiple directories in the CLASSPATH variable is important. The Java interpreter will look for classes in the directories in the order they appear in the CLASSPATH variable. In the example above, the Java interpreter will first look for a needed class in the directory /home/MyClasses. Only if it doesn't find a class with the proper name in that directory will the interpreter look in the /home/OtherClasses directory.

If you want to use a class library that is in a zipped file, you must include the name of that file in the CLASSPATH, for example:

   setenv CLASSPATH /home/MyClasses/myclasses.zip

If you want the CLASSPATH to point to class files that belong to a package, you should specify a path name that includes the path to the directory one level above the directory having the name of your package. For example, suppose you want the Java interpreter to be able to find classes in the package mypackage. If the path to the mypackage directory is /home/MyClasses/mypackage, you would set the CLASSPATH variable as follows:

   setenv CLASSPATH /home/MyClasses

Unsetting CLASSPATH

If your CLASSPATH environment variable has been set to a value that is not correct, or if your startup file or script is setting an incorrect path, you can unset CLASSPATH by using:

   unsetenv CLASSPATH

This command unsets only CLASSPATH's current value. You should also delete or modify the lines in your startup file that may be setting an incorrect CLASSPATH.

The Java Runtime Environment (JRE) and CLASSPATH

The wrappers that invoke the Java Runtime Environment (JRE) unset the CLASSPATH variable before starting the Java interpreter. The reason is simple: there might be several Java applications installed on the machine. If you or someone else previously installed a Java development tool that modified the .cshrc or .login script, then CLASSPATH may point at a JDK1.0.2-based Java runtime. If such a CLASSPATH were left intact when the Java interpreter is invoked, then it will be loading 1.0.2 classes. If your app relies on 1.1 features, it will fail. Just as bad, it's unlikely that the classes for your app will even be found in that CLASSPATH. Unsetting CLASSPATH before invoking the JRE interpreter sanitizes your application against unpredictable results.

The default CLASSPATH used by the JRE is:

   [jre_path]/lib/rt.jar:[jre_path]/lib/i18n.jar:[jre_path]/lib/classes.jar:[jre_path]/lib/classes.zip:[jre_path]/classes

where [jre_path] is the absolute path of the jre1.1.x directory (it has bin and lib directories underneath it). The files rt.jar and i18n.jar are used to hold the runtime's (required) core classes and (optional) internationalization classes. While you can store the classes specific to your application in either [jre_path]/lib/classes.jar or as individual class files in the [jre_path]/classes subdirectory, it is better to keep the JRE separate from your application and use CLASSPATH to point the interpreter to your application's class files.

Using both JDK 1.0.2 and JDK 1.1.x

If you want to develop in both JDK 1.0.2 and JDK 1.1.x, you must set CLASSPATH separately for each one. To use both JDKs simultaneously, you can run them from separate shell windows each having its own value for CLASSPATH. If you are running only one at a time, you can write a batch script to switch the value of CLASSPATH as appropriate.

The Java tools' -classpath option

Some of the Java tools such as java, javac, and javah have a -classpath option which can be used to override the path or paths specified by the CLASSPATH environment variable.