Application Deployment KitApplication Deployment KitThe Application Deployment Kit provides the ability to deploy an application you have created with Dolphin Smalltalk to an executable file which may then be distributed to others as required. The kit itself is comprised of a package that must be loaded into your image to provide the deployment capabilities and a supplemental license that grants you the right to re-distribute the Dolphin Virtual Machine DLL. This will be required to run your deployed applications and you must agree to the license conditions when the ADK is installed.
This documentation consists of:
In order for a deployed application to run correctly you must also distribute with it the Dolphin Smalltalk Virtual Machine DLL. The VM will have been copied into your Windows System directory when the base development system was installed. The filename has the following format:
DolphinVMYYR.DLL
Where YY is a two digit number signifying the year of release and R is a numeric release identifier. For example, the VM for Dolphin Smalltalk/98 release 1 is the file DolphinVM981.DLL. This is the only file from the base development system that you are allowed to distribute with your applications and it is released to you only on condition that you have purchased the Application Deployment Kit and have agreed to the Deployment License.
You should install the Application Deployment Kit.pac file into your image using the Package Browser. This adds a number of new classes and resources and installs some new methods into several system classes. The end result is that the Tools/Application Deployment Wizard menu command, which was previously disabled, now becomes available. It is the Application Deployment Wizard (ADW) that provides the user interface on to the application deployment process.
The application deployment process consists of two stages.
Both stages are implemented by the new ImageStripper class.
An ImageStripper object can be configured with a number of options. These control how the stripping operation proceeds and also determine the name of the executable file to which the image will be deployed. It is the job of the ADW to provide the user interface for setting these options and instigating the deployment process.
Tip: as with all the Dolphin development tools, the ADW is built using the MVP framework. The ImageStripper is the model and the ADW is its presenter. The 'Application deployment wizard' view resource associated with the ADW was built with the View Composer.
There are three basic strategies that can be used for deploying applications under different circumstances. In all cases, once the deployment operation is complete, the development image will be shut down.
Tip: the deployment process saves the development image just before it starts. This ensures that when you restart it, it is in the same state as it was before image stripping.
This method is used when you have created a set of application classes but they are not associated with any package. An instance of the application is set up (using a workspace) with its user interface in the exactly the state it should appear when it is launched as an executable. All other windows that are not Dolphin development tools should be closed, otherwise they will be assumed to be part of the eventual program. The ADW is launched and used to configure an ImageStripper object and to deploy the application to its executable file. When the executable is run the application objects will be already in existence and ready to go just as you left them before deployment.
A disadvantage of this approach is that the ImageStripper object is not retained so all configuration information is lost after a single deployment. More importantly perhaps, some of the stripping options are not available and this results in a somewhat larger executable than can be achieved by adopting one of the following strategies.
If your application resides in a package then it is preferable to use this approach. Once again, an instance of the application is set up and other non-tool windows are closed. This time, however, the appropriate package is selected in the Package Browser before choosing Tools/Application Deployment Wizard. This creates an ImageStripper (if one does not already exist) and associates it with the package. All of the configuration information set up by the ADW is then recorded and will be remembered each time the application is deployed from its package. As with the previous instance-based approach the application objects will be fully instantiated when the resulttant executable is started.
With this method an additional Strip redundant classes option is available for the image stripping process. This is because the ImageStripper is able to determine a network of required classes based on the contents of the root package. Classes that are not required are held to be redundant and are then removed. Use of this option can result in significantly smaller executable files.
Sometimes, the instance based approach is not acceptable. An example might be a full-screen (non-windowed) Direct3D application. It would not be possible to set up the initial instance of this and at the same time return to the Application Deployment Wizard in order to deploy the executable. In such cases it is necessary instead, to create a new RuntimeSessionManager subclass that instantiates the application as part of its start-up processing. This is done by overriding the #tertiaryStartup method.
When deploying the application, it is not necessary to create an application instance. Instead, the package is simply selected in the Package Browser and the ADW is invoked. The first step in configuring the ImageStripper allows the selection of the session manager that will be installed during deployment and it is here that the new RuntimeSessionManager subclass is specified.
Tip: using the #getCommandLine method of SessionManager can also be useful in conjunction with this approach to configure how an application will be started depending on parameters that are supplied on the command line.
Tip: it is also possible to override the #onUnhandledError:, #onUnhandledWarning: and #onUnhandledNotification: methods in any RuntimeSessionManager subclass that you create. This will give control over how such events are dealt with.
Depending on the size of your initial application objects, this method may result in a smaller executable file but at the expense of a longer a start-up time as the objects are instantiated during the load.
Image stripping is not an exact science. It is possible that the stripping process may remove too much from the image such that the resultant application does not execute correctly. This is why we have provided different stripping options that can be configured by the Application Deployment Wizard. Unfortunately, since all the development tools are automatically stripped from a deployed image, tracking down the source of a problem can prove difficult. For example, a #doesNotUnderstand error at runtime simply brings up a message box with no opportunity to invoke the Debugger.
If you experience problems with your application that were not present in the development environment then you should experiment with one or more of the following procedures.
- All methods that belong to the categories commands and must not strip are forcibly preserved in the image. If you find that your application is failing because a particular method has been removed then try adding this to the must not strip category. This set of categories to maintain is determined by the ImageStripper>>requiredMethodCategories method.
- Methods that belong to the category must strip are forcibly removed from the image. If you find, perhaps by looking at the log file, that your application is too large and contains methods that could readily be removed then you can add them to the must strip category. The method ImageStripper>>notRequiredMethodCategories determines the set of method categories that are forcibly stripped.
- A number of classes are always retained. These are determined in the ImageStripper>>requiredClasses method. Adding classes to this set may be able to alleviate the consequences of occasions when the stripper is "over aggressive" in its stripping policy.
- You may specify that a number of classes are always removed. This set is determined by the ImageStripper>>notRequiredClasses method. Adding classes to this set may allow you to further reduce the size of deployed image.
If you wish to alter these default strategies then you may choose to create a new subclass of ImageStripper and override the appropriate methods. In this case, you will either have to modify the Package Browser to use your new strip class, or perform the stripping process manually from within a workspace by evaluating:
ApplicationDeploymentWizard showModalOn: MyImageStripper new