Volume Number: 13 (1997)
Issue Number: 9
Column Tag: Viewpoint

A Cool Rhapsody Web Site & Navigating the OPENSTEP Doc

by Dave Mark, ©1997, All Rights Reserved

Hopefully, by the time you read this column, you've got a brand-spanking-new version of Rhapsody humming along on your Power Macintosh. My fingers are crossed! Either way, be sure to check out John Norstad's excellent Rhapsody web site at http://charlotte.acns.nwu.edu/jln/wwdc97.html.

The name of the site is the "1997 Apple Worldwide Developers Conference (WWDC) NUMUG Trip Report, A Rhapsodic Adventure". Don't let the name fool you. This site is much more than a WWDC rehash. First, it does an excellent job of reviewing the conference from a technical perspective, but it goes further than that. It presents a truly understandable picture of Rhapsody from soup to nuts.

The site starts off with a brief introduction, then launches into a discusssion of Apple's dual OS strategy (Mac OS lives!) and delivery schedules. This is followed by John's "good news, bad news, good news" perspective on Apple's problems. Next is a detailed Rhapsody Architecture Overview, complete with architecture diagrams to help you keep things straight and a discussion of Apple's cross platform strategy.

John graciously allowed me to include some of the material from his site in this column. Obviously, by the time you read this, the story will have changed somewhat. I encourage you to visit John's site and get the latest and greatest. And, if you see John at a conference (he goes to all of them), be sure to thank him for a job well done.

As you know by now, Apple's new Macintosh architecture includes a Blue Box, which represents the classic Mac OS rehosted on the Rhapsody core OS, and a Yellow Box, which represents the new, OPENSTEP based technology, also hosted on the Rhapsody core OS. Here's some of what John had to say about the Blue Box:

"Blue provides much better compatibility than Copland. For example, almost all extensions work fine in Blue. Copland would have broken all extensions.

Playing with Blue in the lab was actually quite boring, since it was almost indistinguishable from a plain Mac running Tempo. That's the whole point, but it was still boring!

In terms of compatibility for old Mac OS software, the transition from Mac OS to Rhapsody should be very similar to the very successful transition from 68K to PowerPC several years ago. Most software will "just work". There will be a few problems and exceptions, but they should be minor.

The only old software that will break under Blue are programs which talk directly to hardware without going through the Device Manager, some kinds of extensions which patch File Manager traps and expect to be able to intercept all file system I/O (Yellow Box file I/O to shared disk volumes will not be intercepted by these kinds of Blue Box patches), and any other software that modifies or relies on the internals of shared system services.

Blue is not an emulator of any kind. It is mostly an exact copy of today's Mac OS, bug-for-bug, feature-for-feature, just rehosted on the new core OS. Most programs should run just as fast as they do on Mac OS, or perhaps only a little bit slower. Some operations will even run faster, due to performance improvements in the core OS.

Blue is very similar to MAE (the "Macintosh Application Environment"), an Apple product which lets you run Mac software on unix systems. Blue is simpler than MAE because it does not require a PowerPC emulator. Blue uses a RAM-based ROM image. There's no hardware ROM.

There is no preemptive multitasking or protected memory inside the Blue Box. A Blue application that crashes can still take down the entire Blue Box, just like an errant application on Mac OS can take down the entire Mac. An errant Blue application, however, cannot crash the core OS or Yellow Box. In Rhapsody, if a Blue crash occurs, you can easily and quickly reboot just the Blue Box, without having to restart the entire computer.

To the Mac OS running inside Blue, it appears as if virtual memory is turned off on a Mac with 1 gigabyte of memory! The core OS does virtual memory operations behind the scenes, but this is mostly transparent to the Blue Box. There are two important benefits of this new scheme:

• No more worries about memory fragmentation!
• You can set memory partition sizes very large with no ill-effects for most applications.

The Blue Box will also provide improved stability via "guard pages". These are special virtual memory pages that are marked read-only and are placed at the beginning and end of each program's stack and heap. In the regular Mac OS, programs sometimes "run off the end" of their stack or heap when writing memory, and end up trashing memory belonging to the system or other programs. This often causes bad crashes. In Blue, such a misbehaving program will crash, but it won't take down other programs or the whole Blue Box along with it.

Several people asked about the following obvious idea: How about having multiple Blue Boxes? This would give some of the benefits of preemptive multitasking and protected memory to Mac OS programs. Apple's answer is that there are problems that would have to be solved. For example, each copy of the Blue Box expects to have exclusive write access to desktop database files. Also, the memory footprint would be rather outrageous. While it might be possible to do this in the future, it is unlikely that this feature will be included in Rhapsody's Unified Release.

In summary, the Blue Box provides excellent compatibility for Mac OS software, comparable performance to the regular Mac OS, even better performance in some cases, and somewhat better stability.

Here's a snippet from John's discussion of the Yellow Box.

In addition to its OPENSTEP foundation, the Yellow Box includes the following advanced technologies from NeXT.

• Multi-user system with security. Rhapsody can be used as a single-user system much like today's Mac OS, or you can have multiple unix usernames and passwords with unix file security. Yes Virginia, you'll be able to telnet to your Rhapsody box!
• PDO = Portable Distributed Objects. A state-of-the-art system for distributed computing. Objects running in separate processes on separate computers can send each other messages almost as effortlessly as they do when they are in the same program. One of the NeXT engineers who designed and implemented PDO presented at the conference sessions. I'm quite impressed by PDO.
• EOF = Enterprise Object Framework. EOF provides an object interface to all of the major commercial database products. It's important in the enterprise market.
• WebObjects. This is a system for rapid development of web pages, CGI gateways, and web server plug-ins.

The Yellow Box will also incorporate several major technologies from Apple:

• The QuickTime media layer (QTML): QuickTime, QuickDraw 3D, and QuickTime VR.
• QuickDraw GX typography.
• ColorSync.
• Scripting. At WWDC, Apple hadn't decided exactly what the scripting language would look like (AppleScript or otherwise), but they promised Apple events and a ubiquitous scripting system integrated into the OPENSTEP classes. After WWDC, the trade press reported that Apple decided to support AppleScript in the Yellow Box.
• V-TWIN search engine.

Applications running in the Yellow Box enjoy the full benefits of all the services provided by the Mach kernel, including preemptive multitasking and protected memory. We'll talk about this more later when we go into more detail about the core OS.

The previous two sections represent the tip of the iceberg as far as this site goes. There are sections on Yellow and Blue integration, Rhapsody advanced look and feel, technical issues to be resolved and, of course, the site will be updated by the time this issue hits the street. Spend the time to go through the entire site. Again, that URL is http://charlotte.acns.nwu.edu/jln/wwdc97.html.

One of the most important features of OPENSTEP that will likely make its way into Rhapsody is OPENSTEP's documentation system, known as the Librarian (old time NeXT programmers know the Librarian as the "Digital Librarian" -- Librarian is the current term).

On the dock, look for an icon that looks like a series of six books, one next to the other (Figure 1). If you don't have the Librarian in your dock, you'll find the application in the directory /NextApps/Librarian.app.

Figure 1. The Librarian icon. The Librarian application is found in /NextApps/Librarian.app.

• Launch the Librarian application.

The window that appears (Figure 2) is known as a bookshelf. A bookshelf is a collection of indexable, searchable documents. A series of examples will make this clear.

Figure 2. The bookshelf window that appears when the Librarian is opened.

• In the Librarian application, select Open... from the Bookshelf menu.
• Navigate all the way up and into the directory /NextLibrary/Bookshelves.

The /NextLibrary directory is the default place for storing system resources such as application preferences. Since unix is a multi-user OS, there's also a way to store preference-type files on a per user basis, in the user's home directory in a subdirectory called Library. For example, the global bookshelves are in /NextLibrary/Bookshelves/, your own bookshelf is in /me/Library/Bookshelves/.

By default, you'll find 4 bookshelf files in the /NextLibrary/Bookshelves directory (see Figure 3): DevTools.bshlf, EntrepriseObjects.bshlf, NextDeveloper.bshlf, and SysAdmin.bshlf.

Figure 3. The four bookshelves in the /NextLibrary/Bookshelves/ directory.

• In Librarian's Open dialog, select DevTools.bshlf and click the Open button.

The DevTools bookshelf window will appear (Figure 4). In the top half of the window, you'll see 7 icons. Each icon represents a directory somewhere on your hard drive. The documents in that directory combine to make up a book. The Librarian can be used to search a book or set of books, based on a variety of criteria. If a book's directory contains any sub-directories, the docs and directories in those sub-directories are part of the tree that makes up the book.

To rephrase this, a bookshelf is made up of a series of books. Each book represents a tree of documents contained within a specified directory.

Figure 4. The DevTools bookshelf window.

Librarian allows you to build an index for a book. The index makes searching the book significantly faster than a search of the book without an index. You can tell if a book has an index by looking at the book's icon in the bookshelf window. If the icon has a yellow dot with an upper-case "I" in the upper-left corner, the book is indexed. A solid yellow dot indicates that while the book itself is not indexed, it is part of a book that IS indexed. In other words, the book's directory is somewhere in the tree of an indexed book. Books within books. Cool!

If a book's icon has no yellow dot at all, the book is not pre-indexed, and searches are done in a much slower, grep-like fashion. Basically, if you plan on searching a book on a regular basis, make sure the book (or its ancestry) is indexed.

• In the DevTools bookshelf window, double-click the Tools Reference icon.

The Target Inspector window appears (Figure 5). The Target Inspector allows you to modify the attributes of the selected book. Notice that the name of the book, Tools Reference, appears in bold next to the book's icon towards the top of the Inspector window. Underneath the icon and book name is a path, showing you how to get to the book's directory. Note that this is a partial path name. In this case, the full path was /NextLibrary/Documentation/NextDev/Reference/DevTools. Note that the name of the book isn't necessarily the same as the name of its directory.

Figure 5. The Target Inspector window, showing the index information.

• Select Indexing from the Target Inspector's popup menu.

An Index pane will appear in the center of the window and a Periodic Update pane will appear in the bottom of the window. There are three buttons in the index panel: Set Up, Delete, and Update. Use these to create a new index, to delete an existing index, and to update an index, making sure it reflects the current content's of the book's directory. Note that updating an index is much faster than deleting and recreating an index.

You can't create an index for a directory that is part of another index. Then again, why would you since an index already exists!

The Periodic Update checkbox lets you specify that the system should update your index automatically, every X minutes or X hours. This is really nice if you've indexed a project's source code (good idea!) and want to update your source code index every night, for example!

• Go back to the DevTools.bshlf window.
• Double-click the ReleaseNotes icon.

This will bring up the inspector window. Note that the Set Up button is disabled (this book already has an index) and that the Delete button is enabled. DO NOT delete this index. It is a useful one to have. If you do have the time and the inclination, go ahead and delete the index and then click the Set Up button to recreate it. This will give you a sense of how long this can take.

Note that you can shift-click to select multiple icons in a bookshelf window. Index commands apply to all the selected books.

• Back in the DevTools bookshelf window, shift-click to select all 7 book icons.
• Click the List Titles button.

Underneath the text field, Librarian will tell you how many titles it found. In my case, the Librarian found 199 documents inside all 7 directories.

• Type the word "action" in the text field, then click the Search button or hit enter/return.

You'll find around 38 documents, each of which contains the word action. Very fast search, eh? The two popups underneath the text field allow you to constrain your search. You can search "In Contents" or "In File Name". The second popup lets you search using Word, Prefix, Within, Literal, and Expression. For the moment, Word is fast, the others are a bit slower.

• Close the bookshelf window.

• In Librarian, select New from the Bookshelf menu.

A new empty bookshelf window will appear.

• Go to the Workspace application, into a File Viewer window, and navigate to the directory /NextLibrary/Frameworks.

The AppKit and Foundation frameworks have associated documentation which is already indexed. We're going to add these indexes to this new bookshelf.

• In your File Viewer, continue descending into AppKit framework/Resources/English.lproj/Documentation/Concepts.
• Back in Librarian, drag the new bookshelf window so you can see it and the File Viewer at the same time.
• In the File Viewer, drag the Concepts icon from the shelf into the top portion of the new bookshelf window.
• Repeat this for the Reference and ReleaseNotes directories.

Congratulations -- you've just created a bookshelf containing three books. Note that all three directories are already indexed.

Why create a bookshelf? Remember, each book is basically an indexable, searchable representation of all the documents in a specific directory. You can build a book based on a directory filled with 100 source code files. Want to search the source code in that directory? Use the Librarian's Search button to search the book's index at blazingly fast speeds. As you make your way through the rest of the column, you'll see what I mean. But there's no substitute for actually trying this out for yourself.

• In Librarian, select Save from the Bookshelf menu.

Though you can save the bookshelf wherever you like, stick to the standard and save it in your home directory in the Library/Bookshelves subdirectory. I saved mine in the directory /me/Library/Bookshelves/. When you enter a name for the new bookshelf, if you leave off the .bshlf, Librarian will tack it on for you.

In the unix universe (and NEXTSTEP is based on unix), a single machine can support multiple users, each of whom has their own account. Each user also has their own home directory. On my machine, my home directory is /me. If your home directory was /usr/puckett, you'd likely store your bookshelves in /usr/puckett/Library/Bookshelves.

Suppose we wanted to search the AppKit bookshelf we just created to learn how to create a new application.

• In the AppKit bookshelf window, select all three icons.
• Type the word application in the text field.
• Click the Search button. (I found around 200 matches.)
• Select In File Names from the left popup and do the Search again.

By selecting In File Names (as opposed to In Content), we've limited the search to documents with the word application in the title. Sometimes In Content will prove to be a better search and other times In File Names will work better.

In this case, searching In File Names produced only 2 matches. Much better! Don't worry if your numbers are different than mine. After all, we are likely running different versions of OPENSTEP on different machines with different configurations. The point is, if your search returns too many hits, try contraining the search in some way.

• We've just created and searched an AppKit bookshelf. Repeat the above procedure to create a FoundationKit bookshelf in the same directory.

In broad terms, the AppKit is all the interface related classes and the FoundationKit is non-interface related classes, such as File handling, Exception handling, NS Object, etc. To really see the difference, build the FoundationKit bookshelf and do a List Titles. Double-click on any title you like and it will open in Librarian.

• To add man pages to a bookshelf, go to myhost/NextLibrary/Documentation/ManPages/.
• Drag icon off shelf into bookshelf window. Voila. Searchable man pages.

Note the nr icon to the left of the document name. That means the doc is an nroff file. If the icon has a c it is a .c file. There are icons for rtf, folders, and lots of others. Just as it would on your Mac, when you double-click a title or icon, the appropriate application will be launched (or brought to the front) and the document will be opened. If you double-click a directory, the Workspace will pop to the front and a new File Viewer will open for that directory.

• Back in Librarian, create a new bookshelf.
• In a File VIewer, find /NextDeveloper/Examples.
• Drag the Examples icon to the bookshelf window.
• In the File Viewer, find /NextDeveloper/Examples/AppKit/TextEdit.
• Drag its icon to the bookshelf. Drag any others you like.

Note that TextEdit has solid yellow circle while Examples has a Shift-I circle. Examples is the directory with the index and the ancestor directory to TextEdit. TextEdit searches use the Examples index. Even so, TextEdit searches will only find files in the TextEdit area. The search won't be quite as fast as if it had its own index, but the search will still be pretty fast!

• Save your new bookshelf.

So now we've got a bookshelf with a bunch of interesting sample source code. Suppose you wanted to find out how to save a document. You know that this source code does that.

• Select the TextEdit icon, type SaveDocument (one word) in the text field, then click Search.

The search returns three documents. The routine we want is in Document.m.

• Double-click AppKit/TextEdit/Document.m.

Librarian will open the file for you. You can click the Find button several times to find the SaveDocument routine. If you scroll down a bit to an else clause, you'll find the term textStorage. To search on this term, select it, copy it, then paste it into your bookshelf text area and click the Search button. This is not as nice as ProjectBuilder or CodeWarrior's find facility, but it is a very nice way to explore, to get your head around a new concept.

• In a File Viewer window, navigate into /NextDeveloper/Examples/AppKit and select the AppKit icon.
• Select Target from the Services/Librarian submenu.

Librarian comes forward and creates a new bookshelf window containing the AppKit directory. That's it! You are now ready to search.

• Launch the Edit application.
• Create a new window, type the word textstorage, and select it.
• Select Search from the Services/Librarian submenu.

Librarian comes forward, and the frontmost bookshelf is searched for textstorage using the selected indexes. How cool is that? Notice that the Librarian submenu also features Update Index, which lets you update the index of the directory containing the file you are editing (which is really nice if you are editing source code!)

This is the easy way to use bookshelves. More importantly, you've just had your first taste of OPENSTEP's services facility. In this case, the Librarian offered a series of services such as target and search, and Update Index. We'll get into Services in detail in a future column. But for now, why not use the Librarian to do a little research on Services yourself!