INSTANTIATIONS

VA Smalltalk Installer Beta

11/15/2012

This document describes the Beta VA Smalltalk product and documentation installers and gives instructions regarding the improved installation process including a description of new Environments tool which creating and organizing multiple development configurations

Contents How is it different? ............................................................................................................................ 3

One setup program that can install both Client and Manager Library. .................... 3

Documentation is in a separate installation package ...................................................... 3

File Locations .................................................................................................................................. 3

Overview of Installation .................................................................................................................. 4

Installation Configurations ........................................................................................................ 4

Installing VA Smalltalk on Windows .......................................................................................... 5

Installation Preparation .............................................................................................................. 5

Download and execute VA Smalltalk 8.6.exe ...................................................................... 5

Installation results ........................................................................................................................ 6

Getting Started creating Development Environments (Starting an Image) ........... 6

Documentation Installation ........................................................................................................... 7

Uninstalling .......................................................................................................................................... 7

Troubleshooting ................................................................................................................................. 8

Two known problems with uninstalling have shown up during our testing. ............. 8

Environments User Guide .................................................................................................................... 8

First Time Launch .............................................................................................................................. 8

Creating a New Environment ...................................................................................................... 10

Working with an Existing Environment in the List............................................................ 13

Exit Environments .......................................................................................................................... 14

Overriding Environments System Settings ............................................................................ 15

Welcome to the Beta for our new Installer and Environments Tool for Version 8.6!

The new installer is for Windows operating systems only. We plan for the new Environments tool to be available for Linux with the release of version 8.6.

How is it different?

One setup program that can install both Client and Manager Library.

The installer is based on InstallShield and is intended to simplify the installation by making it possible to install both Client and Manager Library at the same time. We have retained the capability of installing only the Client or only the Manager Library (for team development environments) by using InstallShield's custom install type capabilities. The new Environments tool provides a simple user interface for creating and managing one or more development environments. When the product is installed, shortcuts to launch Environments will be placed on the desktop and the Start menu rather than shortcuts to directly start up a development image. Once you launch Environments, it is very easy to get an image up and running.

Documentation is in a separate installation package

Due to the size of our documentation and the fact that the documentation is readily available online, we have split it out into a separate package. The documentation installer is also based on InstallShield Installing the Documentation is very simple. Download and execute the VA Documentation 8.6 Setup.exe.

File Locations

To be compliant with Windows UAC, the new installer places our read-only files into the Program Files directory. The root directory of VA Smalltalk is %ProgramFiles%\Instantiations\VA Smalltalk\8.6 (32-bit systems) %ProgramFiles(x86)%\Instantiations\VA Smalltalk\8.6 (64-bit systems) . Note that the bin directory no longer exists in the VA Smalltalk root directory; .exe, .dll, and necessary supporting files are in the root directory. Because it is a read-write file, the manager library will be installed to a shared location, which is specified by the %ALLUSERSPROFILE% environment variable. This variable resolves to different locations on different windows versions:

Windows XP; %systemdrive%\All Users\ApplicationData Windows Vista and later: %systemdrive%\ProgramData

Since development environments belong to a single user, they must be placed in a directory to which you have read/write access. By default, this directory is: %USERPROFILE%\Instantiations\VA Smalltalk\8.6

The new Environments tool helps you to set up a development environment (including image, ini and other user modifiable files) in a directory structure you choose. Documentation is installed in the VA Smalltalk root directory under the subfolder help.

Overview of Installation

VA Smalltalk conceptually consists of two major pieces: The Client, which is all the code --- the image, virtual machine, and supporting programs and files (bitmaps, localized messages, etc.) -- that is needed to run VA Smalltalk and connect to the code repository. The Manager Library, which is the code repository for code we ship with VA Smalltalk and the code you develop together with the programs that provide access to the Manager Library.

Installation Configurations

Developers work with VA Smalltalk in two ways -- standalone or in a team development configuration. In a team development configuration, the system administrator installs the manager library in a networked location and runs a server named EMSRV, which allows multiple connections to the manager library. Each developer installs a client on his/her machines and configures the client to connect to the central manager by changing the ini file for the image. In a standalone configuration, one developer works with his/her own copy of the manager library, usually on the same machine as the client. The simplest way to connect to the manager library in this case is to use what is called File I/O, in which case it isn't necessary to run EMSRV. If you use File I/O only one connection at a time to the library manager is allowed. The installation will be configured for File I/O access by default. The new Environments tool establishes a VA Smalltalk development environment; that is, it provides copies of shipped files and an interface to configure the ini file to change the manager library location.

Note: EMSRV may be used in a standalone configuration if you wish to have multiple images connecting to the manager simultaneously. Use the Environments tool to reconfigure for using EMSRV.

Installing VA Smalltalk on Windows

Installing VA Smalltalk consists of Performing installation preparation Downloading and executing the installer Creation of development environments is a separate step accomplished using the Environments tool after the installation wizard has finished.

Installation Preparation

Before beginning the installation of VA Smalltalk, do the following: Stop any running VA Smalltalk images If EMSRV is running from the directory to be updated, stop EMSRV. If you are using VA Smalltalk on a DBCS system, you must use the ABTRULES.DBC file instead of the default US-English ABTRULES.NLS provided by the system. The ABTRULES.DBC file contains additional codepage conversion tables needed for the DBCS environment. You can find this file in your VA Smalltalk NLS directory. Back up the ABTRULES.NLS file to ABTRULES.BAK, and then rename ABTRULES.DBC to ABTRULES.NLS.

Download and execute VA Smalltalk 8.6.exe

Standalone Installation

After accepting the license agreement, you will be presented with a choice of a Typical or Custom Installation.

If you want to work in a standalone configuration with your library manager on your local machine, select Typical. All necessary files for the Client will be copied to the Program Files directory. The manager will be installed in the %ALLUSERSPROFILE% directory on your local machine.

Team Development Installation

If you are working in a team configuration and want to set up just a client or manager, select Custom. The Custom dialog allows you to select the Client or Manager feature.

The Client feature includes all files except the library manager.

The Manager feature installs the manager in %ALLUSERSPROFILE% directory, and the team development tools -- emadmin, emsrv, and the importer -- in the VA Smalltalk root installation directory.

Note: You do not need to reboot your machine after installation.

Installation results

In order to keep the installation process simple, the installer makes many decisions about locations and permissions of files. Specifically, the location of and permissions on the Manager Library are predetermined.

Manager Library Location

There is no choice of directories -- the manager is always installed down the path pointed to by the %ALLUSERSPROFILE% environment variable. If you wish to move the manager library to a different location, you can do so as an administrator after the installation and set up the necessary user access permissions. The Client ini files will not reflect this change, so developers on your team will need to make this adjustment in the ini file after they install the Client using the Environments tool.

Permissions on Library Manager (Windows Vista and later)

The manager is installed with full access for administrators and the Users group. An administrator will need to manually create permissions for other users and /or user groups.

Shortcuts to the Environments Tool

Shortcuts are placed on the Start Menu in Start>>VA Smalltalk 8.6, and on the Desktop.

Getting Started creating Development Environments (Starting an Image)

If you are working in a standalone configuration, your next step is to start the Environments tool using one of the shortcuts created during installation.

In a team development configuration, EMSRV must be configured and started by the system administrator before you can connect to the manager library. To configure and start EMSRV for Windows, refer to the online documentation here:

http://www.instantiations.com/docs/852/wwhelp/wwhimpl/js/html/wwhelp.htm - href=ig/instgd54.html

Team developers can use the Environments tool to configure their development image for connecting to the manager. Once EMSRV is running, they can connect to the central library.

Starting Environments

You can launch it from shortcuts on the Desktop or the Start Menu. There is a brief guide to its use in the Environments User Guide section. Note: If you have changed the way you access the Library (mgr86.dat) or changed the Library location from when you installed VA Smalltalk, you should update the abt.ini file located in the newimage860 folder before starting up Environments.

Documentation Installation

The documentation will be installed in the Program Files directory under the VA Smalltalk Root Directory in the help subdirectory. %ProgramFiles%\Instantiations\VA Smalltalk\8.6 (32-bit systems) or %ProgramFiles(x86)%\Instantiations\VA Smalltalk\8.6 (64-bit systems)

A shortcut will be placed on the Start Menu under VA Smalltalk 8.6.

Uninstalling

Uninstall VA Smalltalk 8.6 (Product and Documentation) using the Control Panel.

Files that will remain after uninstalling: The manager library will not be removed to prevent you from accidentally deleting saved work. All files created by Environments will remain for the same reason. Environments creates files in the following directories %APPDDATA%\Instantiations\VA Smalltalk\8.6 (private storage ) %USERPROFILE%\My Documents\Instantiations\VA Smalltalk\8.6 (user's files) Files and directories may not be removed if you have an explorer window open in one of the directories affected or it is locked by some other process,

Troubleshooting

Two known problems with uninstalling have shown up during our testing.

Below are the symptoms and how to solve the issue. 1. An error dialog from Windows Installer appears with the text: "Error opening installation log file. Verify that the specified log file location exists and is writable. Microsoft has confirmed this to be a problem with Windows 7 Professional. To work around this issue, stop and restart the Explorer.exe process using Task Manager. 2. An error with Windows Installer appears with Error 1301 and various messages. The directory specified in the error is currently open in Windows Explorer. Several possible causes of this error are: The directory specified in the error is currently open in Windows Explorer. This locks the location and prevents the installation from being able to access it. Another application or utility, such as a virus scanner, is currently locking the directory specified in the error message. The user performing the installation does not have sufficient security privileges to access the directory specified in the error message.

Environments User Guide Environments is a tool for creating and organizing multiple development configurations, referred to as environments. Many developers keep multiple customized copies of the VA Smalltalk development environment (different images configured and saved for different projects). Environments allows you to work with all of them from a single user interface.

Environments will create a top-level directory in which to store your images and supporting files. Each time you create an environment, the tool will copy all necessary files from the installation directory into a subdirectory of the top-level directory.

Environments has plenty of built-in help via hover help. Most buttons and fields have help available. Just hold your mouse over the control; a bubble will pop up with information on it.

First Time Launch

The first time you launch Environments, you will see a dialog that will ask you if you want to create a new Environment.

Figure 1: first time startup

Environments will create a top-level directory in which to store your images and supporting files. This directory defaults to: %USERPROFILE%\My Documents\Instantiations\VA Smalltalk\8.6.

If you don’t want to use the default development image path defined above, click No to set the system settings by hand. For more information on how to manually change the tool’s system settings, see "Overriding Environments System Settings" If you want to use the default development image path defined above, click Yes. The next form you see is the Create New Environment form

Creating a New Environment

Figure 2: Create New Environment Form

Select a name for your Environment -- this name will appear in the Main Environments List Form and will also be the name of the subdirectory created under the top-level directory.

Select whether you want a full (VA Smalltalk) or minimal (IBMST) development environment -- nearly all the time you will want full so you have access to all the development tools.

The next section of the form is where you configure your environment for File I/O or EMSRV. The default values are based on the settings found in the abt.ini file located in the newimage860 folder. Leave the Server Name blank for File I/O. To run with EMSRV, enter the server name the manager resides on. Localhost indicates the manager resides on the same machine as the environment. For

either configuration, specify the full path to the manager library you want this environment to connect to when you start up its image. Note:

If you want to copy other files to work with from the VA Smalltalk root

directory, click the Show optional items arrow button to navigate to the Copy optional files dialog. This dialog gives you the option of copying any files you may want locally so that you can modify them. Currently you can select the message catalog files, IC packaging files, and Xml files.

Once you have made your selections, press the Hide optional items button to navigate back to the Create New Environments dialog and then press the Done button.

The Environments tool will create the new environment folder and copy all required and optional files to it. The copy of the abt.ini file will reflect any changes made to the library access settings as well as any path changes required due to optional file selections. At this point, you have a complete development environment to work with; Environments will navigate to the Main Environments List Form:

Figure 3: Main Environments List Form with single image

To start your new image, select the Environment in the list and then click the launch button.. Tip: If you double-click on the left side of an Environment in the list, you will activate the launch operation.

Working with an Existing Environment in the List

Figure 4: Main Environments List Form with single image

When you select an Environment in the list, a row of buttons will appear to the right of the Environment name:

navigates to the Edit Environment form so you can view/modify the Environment’s settings.

opens an Explorer view on the selected Environment’s folder.

copies a fresh copy of the Environment’s selected image type file to the Environment’s folder. If there is an existing image file in the Environment’s folder, it will be copied to a .bak version of the file before being replaced.

creates a shortcut on the desktop that will start the selected Environment image. The shortcut will be given the same name as the selected Environment.

deletes the selected Environment. When pressed, a confirmation dialog will be displayed that also allows you to (optionally) delete all of the folder(s) and files associated with the Environment.

Exit Environments

Click the Windows close button in the upper right corner to exit Environments.

Overriding Environments System Settings

Figure 5: Main Environments List Form with no images

To change the systems settings, press the - -in the upper right corner to open the Systems Settings form.

Figure 6: System Settings form

The System Settings form allows you to change where Environments places the development image folders and where it looks for the installation tree. Either Done or Cancel bring you back to the Main Environments List Form.