OpenStep Folder Conventions

Although the OpenStep system runs on a full Solaris file system, the file system interface has adopted some conventions that make it easier for users to work with the file system:

• The File Viewer's default view shows all of the files available on the system, but the user can change the view and hide many of the system folders.
• OpenStep software creates some standard folders for OpenStep system software. It also establishes conventions for other software (including your own) that is installed at user locations.

The user's view of the file system begins with the root (/) folder. Inside the root folder, the OpenStep convention is to distinguish between software installed as part of the product and other software installed at a customer site, by creating and using the following folders:

• Home folder, for files the user creates and works with
• OpenStep folders, for software installed as part of an OpenStep installation, which include the developer tools, for users who install them.
• "Local" folders, for software installed at a customer site and available to all users
• "Personal" folders, for software installed by (or for) individual users
• A /net folder that represents network folders available to the computer

Home Folder

Traditionally, each user has a home folder that is identified with his or her login name, /home/username. Home folders of other users may also be visible in the File Viewer.

When typing in file names, users can specify their home folder as ~. For example, ~/openstep refers to the openstep folder in the user's home folder.

OpenStep Folders

The OpenStep folders contain documents, resources, and the applications that are bundled with OpenStep.

• /usr/openstep/Apps contains supported applications that are likely to be used by all OpenStep users. These are general-interest applications such as Edit, Preferences, Mail, Terminal and Preview.
• /usr/openstep/Developer holds applications and files used to develop OpenStep applications. Some of the folders that can appear in /usr/openstep/Developer are listed in Table 8-1.

Table 8-1 /usr/openstep/Developer

Folder Name	Contents of Folder
Apps	Holds applications used by developers. This folder might not exist on all systems. Project management, application construction, and other window-based programming tools belong here. Like all other applications in the four OpenStep folders, these applications can be run from the Workspace Manager. Compilers, debuggers, and profiling tools are typically located in /opt/SUNWspro/bin.
Demos	Contains programs that demonstrate the capabilities of OpenStep. These are not full applications and are not supported by Sun. However, they include games and utilities that users might find interesting.
Examples	Contains source code for example programs. This folder might not exist on all systems. Its folders contain source code that you can study and compile.

• /usr/openstep/Library contains resource files, which are organized into several folders. Not all files or folders are on every system.

Local Folders

Software not supplied by Sun and installed with OpenStep should not be installed in /usr/openstep. This software belongs in folders known as local folders. The following list describes local folders, their creation, and their use.

• Local folders are not included on the release disk. They are created when they are needed.

• The local folders local folders you can create and use are /usr/local/openstep/apps and /usr/local/openstep/Library.
• The local folders should not contain any files that are part of the OpenStep product. They should contain applications and other information available to all users at a local site. A new font available to all the users of your network, for example, should be installed in /usr/local/openstep/Library/Fonts.
• Any user who logs in to a computer or boots from it over a network has access to the contents of the computer's local folders.

Personal Folders

Users can use ~/openstep/Apps and ~/openstep/Library folders (not LocalLibrary or LocalApps) in their home folders for applications and information that they alone have access to. Users who develop utilities for their own use or purchase private copies of word processors or spreadsheets should install them in ~/openstep/Apps.

/net Folder

The /net folder gives the user access to file systems that are physically located on remote machines. Immediately below /net are folders that represent the servers visible to the current computer. The next level of folders represents the file systems on those machines that have been exported to the network. For example, /net/willow/export/misc is the misc file system on a server named willow.

---

Note - /net will only contain other folders if automounting is in effect on the current computer and the file systems it attempts to mount have been exported.

---

All the folders in the root (/) folder, including /net, are physically located on the disk that the user's machine was booted from.

Search Paths in OpenStep File System

This section covers the uses of search paths in the OpenStep file system. There is a standard Workspace Manager search path, and you can create a search path for your own application to use.

The Workspace Manager Search Path

When the Workspace Manager searches for executable files it looks in the folders specified in the search path, The default search path includes six folders:

~/openstep/Apps
/usr/local/openstep/Apps
/usr/openstep/Apps
/usr/openstep/Developer/Apps
/usr/openstep/Developer/Demos

The search path is used in three situations:

• Finding the icons to display for the files associated with a particular application
• Finding the application to start when a user double-clicks on a file
• Finding services offered by applications

Before using the search path to find the application to start up, Workspace Manager first looks in the dock. Each application icon in the dock represents a specific executable in a specific folder, and Workspace Manager assumes that the user prefers the version installed in the dock to any other versions that may be available.

If an application is not represented in the dock, the Workspace Manager next looks in the current working folder (the folder containing the file the user wants to open). If it fails to find the application there it uses the search path.

The search path begins with ~/openstep/Apps, since any user-installed applications would be there. /usr/local/openstep/Apps is next because it contains sitewide software. If nothing is found in the user and site folders, /usr/openstep/Apps, /usr/openstep/Developer/Apps, and /usr/openstep/Developer/Demos, which contain Sun-supplied software, are searched. This search order ensures that any user-installed software is found before (and overrides) the sitewide software, and the sitewide software is found before (and overrides) Sun-supplied OpenStep software.

Users can alter the default search path by setting a value for the Application Paths parameter in their defaults database.

Application Search Paths

If your application needs to look up data that could be in more than one place on the system it should use an ordered search path similar to the Workspace Manager search path. Three functions, NSStandardApplicationPaths(), NSStandardLibraryPaths, and NSStandardFontPaths, provide a programmatic interface to ordered search paths. Applications that use these functions can avoid hard-coded search paths.

File Name Extensions in OpenStep File System

This section covers the uses of extensions in the OpenStep file system, including extensions reserved for the Workspace Manager and custom extensions for your own applications.

Workspace Manager Extensions

OpenStep applications use file name extensions to identify different types of files. The extensions consist of the last period (.) in the file name and the characters that follow it. Mail, for example, uses the extension .mbox to identify its mailboxes. Typical names for mailboxes are Active.mbox and Outgoing.mbox.

The Workspace Manager also uses file name extensions to associate document files with applications. Every application that defines its own data file format appends an identifying extension to the names of its document files.

Custom Application Extensions

Your application should use a unique file name extension to identify its documents. The characters that follow the period can include only alphabetic and numeric characters. Your extensions must include at least three characters; extensions of fewer than three characters are reserved for OpenStep files. The extension .example is acceptable, but .eg is not, because it has only two characters after the period.

File Packages in OpenStep File System

A file package is a folder which looks like a single file in the File Viewer. Because users do not normally look inside file packages (unless they explicitly open it as a folder), they are not likely to alter or reorganize their contents.

Applications should create a file package when they work with groups of files that must be kept together. If, for example, your application displays information that is stored in independent text files, or if it makes use of a private utility program, or if it just loads archived objects from Interface Builder .nib files, you may want to keep these auxiliary files in close proximity to the main application executable file. A file package (with the .app file name extension) is the way to do this.

Similarly, if your application creates documents that are split into more than one file--for example, if text is in one file and artwork in another--these files can also be grouped in file packages.

File packages for documents should have the file name extension used for the application's document files. When a word processor uses a file package to store a document and its artwork, the file package should have the same extension as a text-only document stored in a single file.

Opening and naming the individual files within a document file package is entirely the application's responsibility.

Displaying File Names

When file names are displayed in browsers, users can see the complete path leading to the file. In other situations, as document window title bars, text strings are used to represent the file's name and path. In these situations, the correct format for the filename is as follows:

jobRecords  --  /net/servername/export/records

The file name should be followed by two spaces, an em dash, two more spaces, and then the path.

When there is not enough space to display the full file name--as in a menu command--you can shorten the path to the minimum that differentiates the file. The part of the path you don't show should be replaced with three dots.

For example, if a file called jobRecords is listed in a limited space, you can display it as:

jobRecords

If two files called jobRecords are listed in limited space, you might display them as:

jobRecords  --  .../records
jobRecords  --  .../backup

Files and Folders That Your Application Creates

Applications frequently create, manage and save files and folders that are not explicitly created by their users. When an application creates several files to store a single document, they should be grouped in a file package (see the preceding section for more information). In other situations, when the files hold information about the current state of an application, templates, or similar information, the file names and locations the application uses for them depend on whether users need direct access.

The guiding principle here is that the user's home folder belongs to the user. Applications should not put anything in the home folder that belongs to an application rather than the user. When the application must create unrequested files and folders, it should put them where the user can find them but where they are not likely to get in the user's way.

• If the user never needs direct access to the files or folders, they should be placed in a folder named ~/.openstep/.AppInfo. If an application needs to create many such files, it should create a folder in ~/.openstep/.AppInfo and store them there. If MyApp creates many unrequested files, it should put them in a folder named ~/.openstep/.AppInfo/MyApp. (If the ~/.openstep/.AppInfo folder does not already exist, the application can create it.)
• If the user might work with the unrequested files or folders independently of the application that creates them (for example, template files), the files and folders should be placed under ~/openstep/Library. The names assigned to these files and folders should let users know which applications they belong to.

---

Note - You should generally use the defaults system instead of files to store small amounts of data. The functions supporting the defaults system are described in the OpenStep General Reference manual.

---