VisualWorks(R) 7.6 Preview System Loader ReadMe Copyright Cyncom Systems, Inc. 2007. All rights reserved. UNIVERAL STARTUP SCRIPT FOR UNIX-BASED PLATFORMS In this release we are providing a preview of an new loader for Unix-based platforms. The loader is written as a standard shell script, which allows it to launch VW on virtually any Unix-based platform. This opens up the possibility of having a centrally managed site-wide installation of an arbitrary set of VW versions allowing users to simply run their images as executables without any user specific setup required. The loader determines which version of VW and which specific VM is needed to run the image, based on the information provided in the INI file. The INI file is also simplified, often requiring only a single entry for each VW version, to serve any Unix-based platform for which a VM is available. The following example shows an entry for the aug07.3 build of VW 7.5.1 (useful for active participants of the vw-dev program): 75 01 16 06 /opt/VisualWorks/vw7.5.1/aug07.3 INSTALLATION AND CONFIGURATION The loader consists of two files that must reside in the same directory (e.g., /opt/VisualWorks/bin): - VisualWorks.sh - the shell script itself - VisualWorks.ini - links image version signatures to the locations of corresponding VW installations Symbolic links can be used instead of physical colocation, if a separate location is preferred. The initial bytes of any VW image contain an executable expression that expects an executable named "visual" to be present in the system path, and it runs this executable with the image file as the image parameter. Consequently, to invoke the loader it is necessary to make VisualWorks.sh play the role of the "visual" executable. Two ways to achieve this are: - Create a symbolic link named 'visual' that points to VisualWorks.sh. Make sure the 'visual' link is in your PATH. For, if the shell is installed in /opt/VisualWorks/bin, execute: >cd ~/bin; ln -s /opt/VisualWorks/bin/VisualWorks.sh visual - Rename the VisualWorks.sh file to 'visual' and ensure that the directory (e.g., /opt/VisualWorks/bin) is in your PATH. Also, any image that you wish to launch this way needs to be itself marked as executable: >chmod u+x visual.im Then it can be run as any other system command >./visual.im THE INI FILE The VisualWorks.ini file must be in the same directory as the VisualWorks.sh script, either physically or using a symbolic link. The format of entries are of one of the following: X X [VM-path?]VW-installation-path X X X X [VM-path?]VW-installation-path X X X X represents the 4-byte image signature. The first and second bytes in the image signature are always significant. The third and fourth bytes are always zero for public releases, and so can be omitted. That is, an entry starting with 75 01 00 00 is the same as an entry starting with 75 01 Images built during the development cycle (available to vw-dev) have all four bytes non-zero, and the signature changes with each build. Accordingly, a new entry matching all four bytes must be added to the INI file for each build. The [VM-path?] part is optional, but is necessary in order to use a specific VM, such as a debug, an assert, or a custom VM. The ? must be included, as a separator between the two paths. The VW-installation-path is the path to the VisualWorks installation, and is assigned to the $VISUALWORKS system variable upon startup. Without an explicit VM specified, the loader searches for an executable "visual" VM on this path, in subdirectories of $VISUALWORKS/bin/. HOW ENTRIES ARE SEACHED The loader searches the INI file for entries that match the VI signature. Each matching entry is tried in the order it appears in the INI file. So, for an installation with multiple versions of production releases of VisualWorks may include: 73 00 /opt/vw7.3 73 01 /opt/vw7.3.1 74 00 /opt/vw7.4 74 01 /opt/vw7.4.1 75 00 /opt/vw7.5 76 00 /opt/vw7.6 If the optional VM path is specified, only that exact VM will be tried, for that entry. To accommodate non-standard locations for VMs for different platforms, it is permissible to have multiple entries for the same image signature, each specifying a VM for a different platform. The entries will be tried in sequence until the correct VM for the current platform is found. So, 75 01 /opt/vw7.5.1/bin/linux86/debug/vwlinux86dbg?/opt/vw7.5.1 75 01 /opt/vw7.5.1/bin/linux86/visual?/opt/vw7.5.1 will try to use the debug VM first, and if that fails the production VM will be tried. This is why the script works across different platforms. Suppose the INI file contains: 75 01 /opt/vw7.5.1/bin/linux86/vwlinux86gui?/opt/vw7.5.1 75 01 /opt/vw7.5.1/bin/solaris/visual?/opt/vw7.5.1 75 01 /opt/vw7.5.1 If the script is run on solaris, the linux86 entry is tried first, and fails, so the the solaris entry is tried, and succeeds. If the script is run on AIX, the first two entries are tried, and fail, so the script searches for any working VM using the third entry. OTHER FEATURES 1) If you run an image from the VW installation hierarchy (e.g., ~vw/image/visual.im) then the loader uses the right VM without requiring an INI entry. 2) There is also a start of an INI entry generator. Just run: #> visual -ne /path/to/vw/image/visual.im >> VisualWorks.ini for a clean image in the original 'image' directory in the installation. Changes original - 11/29/07 mk/ph/bb