2.2 Apple's JVM Directory Layout

Even if you're an experienced Java developer, it can be a bit difficult to understand exactly where and how the Apple JVM is installed and configured. Apple has carefully hidden some of its files and libraries to keep users from accidentally wiping out their data and to manage the complexity of upgrading the Mac OS X operating system.

Although its philosophy is unlike that of Windows, Mac OS X tries to maintain a high level of integration between the OS and the programs that run on it. Java is no exception, and the Apple JVM was created with integration and ease of upgrade in mind.

Begin your system tour by opening the Terminal application and going to your hard drive's root directory (or folder). The quickest way to get there is to open a new Finder window and click Computer in the toolbar, and then double-click on the Hard Drive icon. This is the Mac OS X "root" location, which is what you would see from the terminal by typing cd / and then ls:

[Wills-Laptop:/] wiverson% ls
AppleShare PDS            SimpleClass.java          etc
Applications              System                    mach
Desktop DB                TheVolumeSettingsFolder   mach.sym
Desktop DF                Trash                     mach_kernel
Desktop Folder            Users                     private
Developer                 Volumes                   sbin
IE Install Log File       automount                 tmp
Library                   bin                       usr
Network                   cores                     var
Office X SR1 Updater Log  dev
[Wills-Laptop:/] wiverson%

2.2.1 Libraries

You'll find a folder called Library immediately inside the root directory. This folder contains several default directories. When you install Mac OS X, these directories are created automatically so that the applications will have appropriate default directories available to them.

For Unix users, Mac OS X's default directory structure is similar to having /usr/local and /usr/local/bin created by default rather than forcing make or a configure script to handle the task.

Each user will also have a Library directory in their home directory. Items in the root Library directory are shared between users, whereas items in the users' Library directories are specific to each user.

Immediately inside the root Library directory, you will find a Java directory. Inside this directory, you'll find two folders: a Home directory (which is really an alias to another location) and an Extensions folder (which is a real directory).

2.2.1.1 Extensions

The Extensions directory is empty, and is one of several locations where you can drop JAR files that you want to make universally accessible. There is only one systemwide JVM, however; you may not want to make a library (for example, an XML parser) broadly accessible, as doing so might cause versioning conflicts with application expectations.

2.2.1.2 The core JVM

Inside the Home directory, you'll see a familiar layout if you've worked with other Java distributions. The bin directory contains all standard Java tools, such as javac and jar. You'll need to drop out to the Terminal to use these tools effectively. Double-clicking on these tools from the Finder won't give you anything but a strange error message.

If you're paying attention to the file descriptions, you may notice that the bin directory is a sham: all items in the directory actually point to files in a different location. To see these links, use the command ls -l from the Terminal.

2.2.2 The JavaVM.framework Directory

Navigate back to the root directory, and this time go to the /System/Library/Frameworks directory. Inside, you'll see many folders. For now, navigate inside the JavaVM.framework folder.

This directory might be listed just as JavaVM if you've turned off file extensions.

Now you'll see what appears to be yet another directory mostly filled with symbolic links (again, use ls -l to see the links). You may start to wonder when this house of mirrors will actually end, but all of this redirection is important to ensure the proper flexibility when the system JVM is updated. By setting up this structure, Mac OS X applications can be assigned preset locations for finding things, which simplifies operating system updates and upgrades.

Inside the /System/Library/Frameworks/JavaVM.framework/Versions directory, you'll find a link to the CurrentJDK directory, as well as a real folder (one that isn't a symbolic link) labeled 1.3.1 (as well as 1.2 and 1.3). By the time you read this book, you may have a different operating system update installed and see a different version of Java, such as 1.4 or even 1.5. The CurrentJDK directory will point to the currently used JVM, generally the latest version folder.

2.2.2.1 The "real" files

Open the /System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK directory. Now things will get more interesting. Instead of a JRE directory or a lib directory with rt.jar, you will find:

• A Classes directory containing a few JAR files

• A Libraries directory containing some Mac OS X native libraries

• A Commands directory containing the actual files for the items traditionally inside the Java bin directory (e.g., appletviewer, jar, java, javac, or javadoc)

2.2.2.2 Missing items

You'll notice that the traditional lib directory is missing, as are the property files you would typically expect to find.

To find the "missing" lib directory and property files, look in the JDK Home directory (/System/Library/Frameworks/JavaVM.framework/Versions/1.3.1/Home). You'll see a lib subdirectory, with all the files you would expect. Also notice that the items in the bin subdirectory point back to the /System/Library/Frameworks/JavaVM.framework/Versions/1.3.1/Commands directory. While you don't need to distinguish between real files and symbolic links in your programming, understanding the Mac OS X directory structure aids in getting the most out of Apple's JDK.

2.2.3 The Big Picture

You may want to explore JAR files and directories in different locations to better understand how the pieces fit together. Figure 2-1 shows this entire layout in pictorial form.

Figure 2-1. Apple's JVM layout

Another good way to understand the JVM directory layout is to use the JavaBrowser utility included in the Apple Developer Tools, as described in Chapter 3.

Apple's JVM layout may seem confusing, but it simplifies the use of the JDK. For example, by including the core java JVM executable on the path, you don't have to install it or worry about which version you have. You can just rely on the presence of certain paths (such as /Library/Java/Home/). Conversely, if you want multiple JVMs on your machine (for example, if you use a beta version of a future JDK), the default system JVM will be available in a pristine state. You can also point the CurrentJDK directory to another version and easily change the system's JDK.

For this very reason, I strongly advise you not to throw lots of directories into your system JVM classpath. Instead, consider application-specific scripts that set the classpath.

2.2.4 Handling Classpath Issues

For Java libraries that you wish to place on the classpath for all users, Apple recommends the /Library/Java/Extensions/ directory. If you wish to place the library only on a specific user's classpath, put the file in the ~/Library/Java/Extensions/ directory. This directory may not exist, so you or your software's installation program may need to create the directory before installing files within it.

Per the Apple documentation, the Java library search order is as follows:

You'll note that the user's home directory takes precedence over the other locations; this helps a developer working on a system to easily share a machine with other users and avoid classpath difficulties.