VisualWorks(R) 7.6 Mac OS X Universal Object Engine ReadMe
Copyright Cincom Systems, Inc. 2008. All rights reserved.

For installation instructions for this release, refer to the
VisualWorks Installation Guide (Install.pdf) in the root
VisualWorks directory.  For a description of the object
engines, refer to the VisualWorks Application Developer's
Guide (doc/AppDevGuide.pdf).

ENGINE DOCUMENTATION

I.   Starting an image
II.  Shared and dynamic libraries on Mac OS X
III. Using the debug version of the Object Engine
IV.  Features and known limitations
V.   More platform integration with MacOSXExtra


I. Starting an image
---------------------

There are five (5) principle ways of starting the object engine.

1. Double click on the VisualWorks application.

   Using the Finder, double click on the application, visual.app.
   (Your finder may suppress the display of file extensions, in
   that event, the application will be simple named, visual.)
   A dialog box will appear allowing the user to choose the 
   startup image. Press the open button to confirm.

2. Double click on a VisualWorks image.

   This requires the VisualWorks image in question to have a 
   VW-Document icon.  Double clicking the VisualWorks image icon 
   will cause the registered VisualWorks object engine to startup.

   To set the object engine to use when opening an image:
   Select an image file. Use Command-i (Apple-i) to open an inspector
   on the image file. Expand the tab labeled "Open with:". Use the 
   popup menu to select which object engine should start that image. 
   You may also push the "Change All..." button in order to change all 
   images to be associated with that particular object engine.

3. Drag a VisualWorks image and drop it on the VisualWorks application.

   This has the same requirement as above. Simply drag an image 
   over the object engine and let go.

4. Use a shell command line to start the object engine with a specific image.

   From a terminal window execute the following command

      user% open -a visual.app <image name> 

5. Use a shell command line to start the object engine with specific oe flags.

   If you wish to start an object engine with specific object engine flags,
   then the following command line will do the trick.

      visual.app/Contents/MacOS/visual <options> [<image name>]

   For example, to see the object engine version information (-v):

      $(VISUALWORKS)/bin/macx/visual.app/Contents/MacOS/visual -v visual.im


II. Shared and dynamic libraries on Mac OS X
--------------------------------------------

The Mac OS X runtime architecture uses a dynamic linker/loader to load 
all executables.  Thus, all applications, frameworks, plugins and 
shared libraries are built on this mechanism.

When an application is statically linked against a shared library, 
commands to load the library at runtime and resolve its symbols are 
loaded into the executable. However, the client process may choose 
to defer the decision of whether or not to load the library till runtime.

Mac OS X has built all of the standard unix libraries as shared libraries.

Mac OS X also has the notion of a bundle. Actually, the documentation 
refers to bundles with two different, though related meanings.

   a) the actual file that contains executable code
   b) a file package that consists of a file hierarchy 
      containing the executable code and its related resources

Almost always, Mac OS X documentation refers to the latter definition 
of the term. In this discussion, we refer to the first definition. 
Shared libraries may be built as bundles.  Libraries built specifically 
as bundles may be loaded and unloaded at runtime.

Key points:

1. Shared libraries, such as the Oracle8 client library, may be bound 
   to an image at runtime. Once bound, these libraries remain bound 
   for the duration of the application session.

2. Dynamic libraries built as bundles may be bound and unbound 
   from the image at runtime, as the program design allows. 

3. File packages of a library and its resources, also called bundles, may
   be created to aggregate an application, a framework of Objective-C classes,
   or a framework of C functions such as the Carbon compatibility framework.


III. Using the debug version of the Object Engine
-------------------------------------------------

Updated information about and instructions for using the debug 
engines for all platforms is maintained at:

    http://wiki.cs.uiuc.edu/VisualWorks/debugging+at+the+virtual+machine+level
    
Please refer to this web site for information about these engines.


IV. Features and known limitations
----------------------------------

Incomplete Implementations:
 - MacOS Aliases are not recognized as files or directories
 - only image files have a special MacOS X icon

Further topics:

1. The 'VisualWorks' main menu is available in English only.  There is 
   no German option at this time, as there was if prior releases.

2. Environment variables are implemented as entries in the UserDefaults
   database.  Each user has his own UserDefaults database where, e.g.,
   the variable VISUALWORKS is stored, if set.  Because the UserDefaults
   database is only written on a clean application quit, VisualWorks
   sometimes misses this database operation.  You can set the
   define manually from a Terminal:

      user% defaults write com.cincom.vw7.2 '{ VISUALWORKS = /<YourPathGoesHere>/vw7.2 }'

3. All UnixVMs are currently  not stripped. This is intended for 
   'vwmacxast' and 'vwmacxdbg' for debugging purposes. The standard 
   UnixVM 'visual' is not stripped in order to support DLLCC.

4. File locking has been fixed by MacOS X 10.2.


V. More platform integration with MacOSXExtra
---------------------------------------------

This parcel contains additional code for platform integration into 
the MacOS X operating system.

1. Host menu bar item linking to VisualWorks actions.
   For more information look at InputStates class method:

      setMenuDispatchTable

   for setting up your own 'menu item tag => method' mappings.
   Look into MacOSXSystemSupports class method:

      enableMenuBarItems

   for setting up (enable/disable/reset) those menu bar items.
   Look into the InputState instance protocol 
   'private macosx dispatching' for example methods triggered by
   menu bar item events.

2. Access documents dropped onto the VM icon, either on startup 
   of the image or during operation.  For more info look into 
   MacOSSystemSupports class methods:

   - getInitialDocument
       for info on how the first document is fetched 
       on #returnFromSnapshot,

   - simpleDocumentHandling
       to see how subsequent document events can be caught, 
       and how the VM can be configured to accept additional 
       document types.

   In a development image, every startup will print the name of an 
   additional document dropped onto the VM into the Transcript.

After loading this parcel on MacOS X, the additional menu bar integration 
is initialized.

The following menu item setup is installed:

   VisualWorks->About VisualWorks
     Opens the standard AboutVisualWorksDialog.
   
   VisualWorks->Preferences...
      Opens the settings tool,

   VisualWorks->Quit
      Opens the standard save/exit dialog,

   Help->Topics
      Opens the help browser, and loads the help system if not present.


6/6/06     eem
11/04/03   js/bb 
11/1/04    bb    
11/14/05   bb
5/23/06    bb
4/13/07    bb
02/01/08   js