Installing Omnis Studio 4.1 on Mac OS X

In order to be able to use the Graph2 component on Mac OS X machines, Omnis Studio must know where to look for certain resources. The way this was implemented for this component on the Mac OS X platform is to use a dynamic library, which Omnis Studio itself must call to access property declarations, functions and methods for Graph2. This library is found within a directory named "dylib" within the Omnis Studio installation directory. But, for whatever reason, Omnis Studio must use an environment variable (named DYLD_LIBRARY_PATH) to point to the location of that folder, rather than just looking within its own root directory. While this is somewhat unusual on Mac OS X (only one other program out of the hundreds I have installed on my primary computer required the creation of an environment variable in this same manner), there are standards established for just this situation.

The environment variable is established by making an entry in a property list (XML) file named environment.plist. This file is held in an invisible directory named .MacOSX (note the punctuation that is part of this name - the full stop character at the beginning of the name makes the file invisible by default) within the main directory for the current user. If this directory and file already exist, the installer for Omnis Studio 4.1 creates the variable DYLD_LIBRARY_PATH and populates it with the full pathname of the dylib directory file for the current installation. If the variable already exists, its value is simply updated with that information. Here is how that result might look when viewed using the Property List Editor program that is part of the Xcode developer package (which is included with every copy of Mac OS X):

Contents of environment.plist

If either the .MacOSX directory or the environment.plist file do not already exist for the current user, there could be some installation issues. While the installation script is programmed to create the invisible directory .MacOSX for the current user if it does not already exist, it does not appear to do so on all machines. The same applies to the environment.plist file that must be contained in that directory. In either of these cases, early version 4.1 installers hung with 1 item left to install and a message that said "Searching...". Cancelling such an installation would uninstall everything (unhappily), but aborting it (using a Forced Quit) would leave the new version of Omnis Studio installed - apparently intact, except that the environment variable required by Graph2 would not be established because the installation script got caught in some kind of loop looking for .MacOSX and environment.plist. Again, this did not happen on every machine, but it did affect many people. I do not know whether the exact problem was ever identified or fixed.

The manual fix is to create this directory by hand using the Terminal program, then create the file using Property List Editor and move it into the invisible directory, again using Terminal. Reinstalling Omnis Studio 4.1 will create and populate the DYLD_LIBRARY_PATH variable, or it can be created and populated manually before moving the .plist file into position. Here are the steps:

Open Terminal and check whether .MacOSX already exists for the current user. (In the following steps, the string <cr> means "press the Return key. Do not type this string literally.) Terminal starts us at the current user's root directory, so we only have to type:

ls -a <cr>

The command ls means "list directory contents". The -a option means "Include directory entries whose names begin with a dot (invisible items)". If the .MacOSX directory does not appear in the list, we can create it using:

mkdir .MacOSX

Once we have a .MacOSX directory, we can check to see whether it contains the environment.plist file. (It won't if we just created it, of course.) We can do this using:

ls .MacOSX

Here we specified the directory for which we want to view the contents. We are only interested in visible files this time, so we did not include the -a option:

Directory listings in the Terminal window

If the file does exist (it will most likely be the only visible file in that directory), we just have to reinstall Omnis Studio (but only if trying to use the Graph2 component is causing Omnis Studio to crash). If not, we have to create one. We can do this using the Property List Editor program. (You did install Xcode on your machine, right?)

When we first launch Property List Editor, we see a window named "untitled". Here is what that looks like:

New untitled property list

All we really need to do is create a root node and then save the file as environment.plist at some convenient location. We will then use Terminal to move it into our invisible directory. Our task is simple: Just click the New Root pushbutton to create a root node in our property list file. The result looks like:

Untitled property list with root dictionary

This is all that the Omnis Studio Installer application needs to carry out its final task. The item named Root is automatically assigned a class type of Dictionary, which is what we want it to be. If we wanted to manually create our variable entry as well, we must click the disclosure triangle next to Root and then select that line. The pushbutton we clicked to create the Root entry is now enabled and redrawn to display the label New Child. If we click this, an entry labeled New item is created within Root and is selected for us to replace the name with one of our own choosing. We would give this the name DYLD_LIBRARY_PATH. But we would then have to give it a Value that is the exact and complete pathname of the dylib directory within an Omnis Studio 4.1 folder on our computer. It is probably better to let the installer program do all this for us!

New item under Root

We still need to save the file. We use the Save item from the File menu for this and fill in the dialog that appears.

Save property list dialog

We give the file the name environment.plist. I chose to save this file to the Desktop directory to make my copy process simple. We must also make sure that we choose the XML Property List File format, although this should be the default. We then click the Save button.

We now return to the Terminal program. Whether we left it open or had to relaunch it, we should still be at the root level for the current user account. This means that both the Desktop directory where our property list file is located and the .MacOSX director where we want to put it are directly within the current directory - so we can use relative references in naming the source and target paths for the move. All we have to do is type:

mv Desktop/environment.plist .MacOSX <cr>

This uses the mv or "move files" command. We specify the path to the file we wish to move and the path to the directory we wish to receive that file. The file name will be automatically assigned as the name of the source file, so we don't have to repeat that. This will remove the original file from the Desktop directory as part of the process. If we prefer to instead copy the file so that the original remains where it is, we could use the cp, or "copy files", command instead - with exactly the same syntax. Our main concern is to get this file into the invisible directory where the installer can update the DYLD_LIBRARY_PATH variable and where Omnis Studio can find that variable so we can use the Graph2 component without crashing Omnis Studio.

But even when we get this installation problem fixed, we can still have difficulties. Remember what happens with the installer program and what Omnis Studio needs: The installer program updates the DYLD_LIBRARY_PATH variable with the path to the most recently installed copy of Omnis Studio 4.1 (or later). If this becomes invalid, Omnis Studio will no longer be able to use Graph2. Consider the following scenario:

Let's say that we have successfully installed a Developer copy of Omnis Studio and we have created a library that uses the Graph2 component. Now we want to test it using a Runtime copy of Omnis Studio, so we install that as well. The DYLD_LIBRARY_PATH environment variable now contains the full pathname of the dylib directory in our Runtime installation, since that was the most recently installed copy of Omnis Studio.

Now suppose that we have satisfied ourselves that the library works properly with the Runtime. Perhaps we decide to remove the Runtime installation to give ourselves more room on the hard drive. Bad move! The path stored in DYLD_LIBRARY_PATH no longer exists! Any further attempts to use even a design window containing Graph2 will result in a crash of Omnis Studio! And this is on the machine of a developer, who at least (now) knows how to handle the problem.

This very scenario happened to me while on the road teaching a class recently. I did not sort out the problem and its cause until after the class was finished and I was on the way home. Too bad, because there were some great things I had discovered about Graph2 that I wanted to demonstrate to those students!

Consider our end users. If a user so much as renames the Omnis Studio directory installed on their computer, they will face the same problem. DYLD_LIBRARY_PATH does not store an alias that is dynamically updated - it stores a static string. I mention this to prepare you for tech support calls as a possible source of trouble to check. I don't want to discourage you from using this component, though, because I am discovering more useful things about it all the time!