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

IMPORTANT!
You must configure the X11 server correctly to use VisualWorks
under X11.  See section I. below.

ENGINE DOCUMENTATION

I.   Configuring X11
II.  Starting an image
III. Shared and dynamic libraries on Mac OS X
IV.  Using the debug version of the Object Engine
V.   Features and known limitations
VI.  Troubleshooting



I. Configuring X11
-------------------

0. Install the X11 windows server if it has not already been 
   installed.  This is included on the MacOSX install disks. Find 
   the X11.pkg and double click to launch the installer.

1. Set the DISPLAY environment variable to a sensible value.

   a. To use the graphical environment
      i.   create the directory ~/.MacOSX
      ii.  copy the file environment.plist to ~/.MacOSX
      iii. logout and login again

   b. To use the terminal environment, set the environment in the 
      standard manner for the bash shell:
      i.   add the following two lines to ~/.profile

             DISPLAY=0:0
             export DISPLAY

           If you are launching with a double click, you need to set 
           the DISPLAY variable with an environment.plist file in 
           the directory ~/.MacOSX.

      ii.  close the old terminal and open a new one

2. Start the X11 window server, by double-clicking on X11.app 
   found in /Applications/Utilities.

3. Start the VisualWorks object engine (see section II. below), either
   a. From a terminal as a "vanilla" X application:
      i.   cd to visual.app/Contents/MacOS
      ii.  Execute vwmacxx11gui with the image as a command line 
           argument:

              ./vwmacxx11gui ~/vw7.3/image/visual.im

   b. From a terminal as a bundled application, execute on the 
      command line:

              open visual.app

   c. Double clicking visual.app in the Finder
   d. Dropping an image on visual.app 


II. Starting an image
---------------------

There are four (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


III. 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.


IV. 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.


V. 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 two languages, English 
   and German.  If your Mac is set to use German as its default language, 
   then the menu bar will be in German. All other language settings 
   will default to the English menu bar.  Feel free to add other 
   localized menu bars.  When starting a standard image, the menu bar 
   contains some disabled menu items.  This is correct and intended. 
   More menu bar items are activated after installing MacOSXExtra.  
   As a standard menu configuration, 'Help->VisualWorks Help' 
   will open the 'Welcome.pdf' document. Set AcrobatReader as your 
   default application for PDF files to enable navigation to all
   VisualWorks manuals.

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.3 '{ VISUALWORKS = /<YourPathGoesHere>/vw7.3 }'

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.


VI. Troubleshooting
-------------------

The object engine reports errors on stdout. 

If launch from a terminal session, you will see errors reported 
in the terminal used to launch the object engine. 

If you are launching from the Finder, open 
/Applications/Utilities/Console.app. All error messages will be 
written to the console for applications launched from the Finder.

The typical error you will see if DISPLAY is not set, is an inability
to connect to the X11 server.




6/6/06     eem
11/04/03   js/bb
11/1/04    bb
11/14/05   bb
5/23/06    bb
4/9/07     bb
2/1/08     js