Setting the class path

The explanation below is an abbreviation of Sun's tutorial page: http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/classpath.html

Synopsis

The class path is the path that the Java runtime environment searches for classes and other resource files.
The class search path (more commonly known by the shorter name, "class path") can be set using either:

the -classpath option when calling an SDK tool (the preferred method)
the CLASSPATH environment variable.

The -classpath option is preferred; you can set it individually for each application without affecting other applications and without other applications modifying its value.

% sdkTool-classpathclasspath1:classpath2...

where sdkTool is A command-line tool, such as java, javac, or javadoc.

classpath1:classpath2

For a .jar or .zip file that contains .class files, the class path ends with the name of the .zip or .jar file.

For .class files in an unnamed package, the class path ends with the directory that contains the .class files.

For .class files in a named package, the class path ends with the directory that contains the "root" package (the first package in the full package name).

Multiple path entries are separated by colons.
The default class path is the current directory.
Using the -classpath command-line option overrides that default: If you want to include the current directory in the search path, include "." in the settings.

Description

The class path tells the SDK tools and applications where to find third-party and user-defined classes.
The class path needs to find any classes you've compiled with the javac compiler.
Change the class path by using the SDK tools' -classpath option when you invoke the JVM or other SDK tools.
Classes can be stored either in directories (folders) or in archive files.

Using the SDK tools' -classpath option

The Java tools java, jdb, javac, and javah have a -classpath option which replaces the path or paths specified by the CLASSPATH environment variable while the tool runs.

This is the recommended option for changing class path settings, because each application can have the class path it needs without interfering with any other application.

The runtime tool java has a -cp option, as well. This option is an abbreviation for -classpath.

Understanding the class path and package names

Java classes are organized into packages which are mapped to directories in the file system.
When you specify a package name, you specify the whole package name -- never part of it. For example, the package name for java.awt.Button is always specified as java.awt.

For example, suppose you want the Java runtime to find a class named Cool.class in the package utility.myapp.
If the path to that directory is /java/MyClasses/utility/myapp, you set the class path so that it contains /java/MyClasses.
To run that app, you could use the following JVM command:

% java -classpath /java/MyClasses utility.myapp.Cool

When the app runs, the JVM uses the class path settings to find any other classes defined in the utility.myapp package that are used by the Cool class.
It is not possible, for example, to set the class path so it contains /java/MyClasses/utility and use the command java myapp.Cool. The class would not be found.

(The package name is part of the class and cannot be modified, except by recompiling the class.)

Note: An interesting consequence of the package specification mechanism is that files which are part of the same package may actually exist in different directories. The package name will be the same for each class, but the path to each file may start from a different directory in the class path.

Folders and archive files

When classes are stored in a directory (folder), like /java/MyClasses/utility/myapp, the class path entry points to the directory that contains the first element of the package name. (In this case, /java/MyClasses, since the package name is utility.myapp.)
When classes are stored in an archive file (a .zip or .jar file) the class path entry is the path to and including the .zip or .jar file.
For example, to use a class library that is in a .jar file, the command would look something like this:

% java -classpath /java/MyClasses/myclasses.jar utility.myapp.Cool

Multiple specifications

To find class files in the directory /java/MyClasses as well as classes in /java/OtherClasses, you set the class path to:

% java -classpath /java/MyClasses:/java/OtherClasses ...

Specification order

The Java interpreter looks for classes in the directories in the order they appear in the class path variable.
In the example above, the Java interpreter first looks for a needed class in the directory /java/MyClasses.
Only if it doesn't find a class with the proper name in that directory does the interpreter look in the /java/OtherClasses directory.