Application Deployment Wizard

The Application Deployment Wizard (ADW) dialog provides a step-by-step approach to deploying a Dolphin image as an executable file. The Application Deployment process involves stripping redundant classes and methods from an image before saving this out in the Microsoft Windows executable file format. There are a number of options available for the image stripping process and the wizard takes you through the configuration of these.

You can start the ADW from any of the Dolphin development tools using the Tools/Application Deployment Wizard menu command. Usually you will want to start the wizard from the Package Browser in order to perform package based application deployment. However, it is also possible to perform non-packaged deployment by calling up the ADW from any of the other development tools.

As you progress through the wizard's steps you will be configuring an ImageStripper object whose job it is to perform the deployment process. If you are performing package based deployment then this ImageStripper will be saved along with the package and may be reused each time you choose to deploy any executable from this package.

The wizard displays the following steps.

Step 1

Here you should choose the name of the executable file to which your application will be deployed.

Since the eventual application will be executing in a run-time environment it is not appropriate for it to use the standard DevelopmentSessionManager that is present in the development image. Normally an instance of RuntimeSessionManager is installed instead. However, if you are performing class based deployment (and in some other circumstances) then you may wish to install a different subclass of RuntimeSessionManager that you've written yourself. If this is the case you can choose it from the drop-down list on this page.

Step 2

The Strip redundant classes option is only available if you are performing package based deployment. With this option checked, the ImageStripper will attempt to find the network of all classes that are referenced from the contents of the root package. All other classes, that do not have instances or are not included in the set of required classes defined by ImageStripper>>requiredClasses, will be forcibly removed from the image.

Tip: this process only takes note of references from the root package's classes, methods and resources but not from the scripts.

If your application does not execute correctly then the problem may be that, for some reason, too many classes have been stripped from the image. Determining the underlying cause of this can be quite tricky and often turning off the Strip redundant classes option is a simple solution that may work. The end result will, of course, be a larger deployed executable.

Step 3

The Strip redundant methods option will inform the ImageStripper to remove all the methods from the image whose selectors are not referenced by any other method. Note that, because Smalltalk is a dynamically bound language, it is not possible to accurately determine whether a method will actually be called. For this reason, the redundant method stripping process errs on the side of caution and will leave methods in the image that can never be called simply because they have the same selector as one that can.

When removing redundant methods, the operation takes place in several passes and the image is scanned repeatedly until no further methods can be removed. Choosing this option will significantly increase the time taken to strip the image and, therefore, during initial deployment testing you may like to turn it off.

If you choose to Strip redundant methods then you must be aware that any methods that do not appear to be referenced by others may be inadvertently removed. A typical situation where this might occur is in the use of a #perform: that takes a composed symbol as its argument. For example, ValueAspectAdaptors will compose their "set" selector by appending a $: to their specified "get" selector. In these cases the ImageStripper might incorrectly remove the setter methods even though they can still be called. By choosing the option to Preserve aspects set methods you inform the ImageStripper that all methods ending in a $:, that are paired with similarly named methods without the $:, are to be retained.

Tip: the ImageStripper is incapable of determining selectors that may be referenced from within resources. For example, if you have set up an adapter block inside a view resource which attempts to call a method which is not referenced elsewhere, then you should add this method to the "must not strip" category to prevent it from being inadvertently removed.

Tip: note that all methods in the "commands" category are also explicitly preserved by the ImageStripper. Such methods are very often referenced from menus held by view resources.

Step 4

Normally, the ExternalStructure subclasses allow for the ability to define accessors in their templates but not actually compile these into methods. Accesses are trapped by a #doesNotUnderstand override and interpreted approprately. This was previously done to save space in the image at the cost of poorer performance. However, with the advent of the ImageStripper, it is nearly always a disadvantage not to compile all the accessor methods for these structures, both in terms of speed and space.

Choose the Compile ExternalStructures option to force compilation of all of the structure templates in the image. This will allow all the templates to be disposed of and all the classes in the AspectDescriptor hierarchy to be completely removed. You should find, if you have chosen to Strip redundant methods, that many of the generated accessor methods will be removed anyway.

Step 5

Choose Strip class information to remove the (usually) redundant meta-information held by the classes in the image. This will cause the ImageStripper to drop class pools, shared pools, class comments and instance variable names. If your application makes use of any of this information then don't check this option.

The Strip duplicate strings option will cause all references to string literals that compare equal to be folded into one. There should be no disadvantage to choosing this option.

If you find you are having difficulty getting your application to run properly then check Write log file in order to have the ImageStripper generate a log of all the classes and methods that it removes. This may be useful for tracking down whether some things have been unexpectedly removed. The log is sent to a file with the same name as the executable but with a .log extension.

Step 6

Press Deploy to proceed with the image strip and deployment process.

Tip: if the button is not enabled, then most likely you have forgotten to enter an executable name in Step 1.

The deployment may take several minutes depending on the speed of your machine and the ImageStripper options that you've selected. A progress dialog will be displayed during the operation. When complete the image will shutdown.

It is very important that, should the stripping operation fail, you do not save a partially stripped image. It will be corrupt and you may lose work.

If you do not wish to deploy the application immediately, then click Done to save the changes you've made to the ImageStripper so that you can return later.