Example: Seaside Traffic Light Single Module Packaging
This example illustrates the packaging of the Seaside Traffic Light project (shipped with VA Smalltalk) into a single runtime image which also contains debugging tools: the
interactive debugger and the
stack dump debugger. The purpose of this example is to show the basic use of these debugging tools.
Seaside Traffic Light displays a traffic light on a website. The example has no desktop user interface to control what is written or where it is written and is therefore headless. It has a self halt deliberately placed in the Smalltalk code displaying the green light to facilitate the use of the interactive debugger.
In order to deploy the debugging tools at runtime, the Seaside Traffic Light project is divided into runtime and development time portions.
The
Packaging Steps start with a shipped image. Here the steps are repeated with links to how to accomplish each step. Steps unique to cross platform debugging tools appear in
bold.
•Launch a clean development image.
•"Load the ‘ST: Server, SST’ feature.
•Notice that choosing to load this feature also causes the ‘ST: Server Workbench, Base’ feature to load.
•The Seaside Traffic Light project relies on the following VA Smalltalk code:
•the ‘ST: Server Smalltalk (SST) - Seaside Testing’ feature
•the configuration map 'ENVY/Image Batch Runtime'.
Loading the ST: Server Smalltalk (SST) - Seaside Testing’ feature causes the Seaside feature with all its tests to be loaded. The Seaside tests are useful both for their sample code and as an aid in determining whether the Seaside framework or the Seaside Traffic Light project is malfunctioning;
Load both the feature and the configuration map.
•The Seaside Traffic Light project includes its own packaging instructions. The project is found in two configuration maps:
•‘Seaside Traffic Light Runtime’
•‘Seaside Traffic Light Development’.
The configuration map ‘Seaside Traffic Light Runtime’ contains the code needed to actually display the traffic light and change which light is lit.
The SeasideTrafficLightPackagingInstructionsApp appears as an Application in the ‘Seaside Traffic Light Development’ configuration map. This allows you to avoid loading the predefined packaging instructions for the project as a separate step.
Once the configuration map is loaded, the Transcript has a new pulldown menu named XD.
•Enable remote debugging. (See
how.)
•Create the passive (XD) image for the Windows platform.
Create a
new passive image making sure to load the following as the
installed features.
•‘Server Smalltalk Seaside’ -- the XD counterpart of the development image feature ‘ST: Server Smalltalk (SST) – Seaside’. It is available because ‘ST: Server, SST’ is loaded in the development image.
•‘Interactive Debug using TCP/IP’ -- the connection between the workstation and the target system.
Note: The XD pulldown menu has a new entry after the Development menu item.
Note
If you have a Linux installation as well as a Windows installation, you could choose to package for Linux. If you do, you must also test on Linux.
•If the new passive image is not the current one, make it the current image.
(See
how.)
• In the passive image:
•Set the address of the workstation where the debugger should open. (See
how.)
For this example, enter the local host IP address: 127.0.0.1 as the workstation address. This identifies where the interactive debugger will open in the event of an error when the packaged Seaside Traffic Light image is running.
• Load the ‘Seaside Traffic Light Runtime’ configuration map. (See
how.) If it loads without error, continue packaging.
• Save the image from the XD Transcript. This saves the passive image together with the development image.
•Start the packager from the XD Transcript. (See
how.)
•Choose the radio button Show application hierarchy.
•Open the SeasideTrafficLightPackagingInstructionsApp by double clicking it.
•Select XDSeasideTrafficLightPackagingInstructions.
•At this point it would be informative to take note of the high level differences in the packaging instructions introduced due to the fact that the headless application relies on Seaside.
•Following the link to “
modify” will allow you to compare what settings the simple “Hello World” example required. Whereas Seaside Hello World records the settings for a Seaside example without debugging enabled, Seaside Traffic Light includes support for remote debugging (in
bold below). To see what it needed for remote debugging, choose
modify step to see the instructions:
•observe the domain project SeasideTrafficLight and the SstDebuggingSupport Application are included,
•observe the startup class is AbtStackDumpStartup, which allows the debugging tools (interactive debugger and stack dump debugger) to be used with the packaged image,
•observe the startup code, and
•observe seasideTrafficLight.icx is the output file.
•Output the reduced runtime image.
•Close the packager.
•However, you could skip the detailed steps above and simply click Finish and close the packager.
Note: If you have not set the Workstation address, a dialog will appear asking you to set the Workstation address.
•Make the
development image the current one. (See
how.)
•Optionally, save the image. This step is needed to preserve information generated during packaging including information which allows the image to be identified as the one which generated the packaged image. However, it also puts the passive image into state that, in a less restricted case than this example, may prove troublesome. Best practice is not to save the image.
•Close the image from the Transcript.
Look at the directory in which you started the development image. You should see seasideTrafficLight.icx. This is the single packaging module, aka the runtime image. The packaging process also creates SEASIDETRAFICLIGHT.SNP and several packaging statistics files (with ES extensions), which are useful in debugging but not required to run the packaged image.
The next thing to do is
run the packaged image and explore the available debugging tools.