MaSarPackage
Last updated at 1:31 am UTC on 16 July 2010
About SAR Files
Squeak has several options for deployment of applications. There is Monticello, MonticelloConfigurations, Metacello. These are great SCM tools developers can use for loading and updating code in the image.
Squeak can also install a SAR file directly from its internal SqueakMap browser, its internal File browser, or by dragging a SAR file from the underlying OS's file-manager on to a running Squeak image. A SAR file is simply a zip of files, one of which is an install script that runs when the SAR file is installed. The install script inside a SAR file can do anything, making the SAR file a wonderfully effective installation and configuration tool. Consider that SAR files can be used for:
- storing meta-information about any MC package within the MC package itself (via PackageInfo, details below), much like Metacello does.
- keeping an exact configuration that is assured to work, forever, on the version of Squeak that it has been tagged to work with.
- including relevant resource files or image patches with a configuration.
- publishing to SqueakMap.
- allowing users to examine the load-script and contents before loading, in case there is a concern about security.
- loading software even when no network connection is present.
SAR files have, traditionally, been associated with static configurations. However, because the load-script can do anything, it is perfectly feasible to have a SAR file with only a load-script that instructs Installer to, say, one-click load and update a set of packages to the "latest versions" from network-accessible locations.
About PackageInfo
PackageInfo is a core Squeak class for attributing meta-information to packages. By creating your own subclass of PackageInfo for each of your (Monticello) packages, meta-information about the package can be included inside the versioned Monticello package, itself. MaSarPackage (or other tools) can access this meta information to assist with configuration and deployment.
About MaSarPackage
MaSarPackage is a tool for creating SAR files. SAR files are a good way to publish code and objects to SqueakMap. Often the types of projects that are made into a SAR involve multiple packages and/or resources such as graphic files or serialized object files, or even change-set patches to the base Squeak image. MaSarPackage makes it relatively easy to build such one-click installable SAR files.
Installing MaSarPackage
MaSarPackage is available with or without a GUI. Both versions are one-click installable from SqueakMap. If you want a GUI, just install "MaSarPackageWithGui". If you don't want the GUI, just install "MaSarPackage". For details about how to load a package from SqueakMap, see SqueakMap.
Tutorial
MaSarPackage, itself, was used to build its own SAR. The following tutorial describes the steps used to build the SAR file using the Maui interface, which, by nature, also reveals the exact message names needed to operate it via Smalltalk script.
Process Overview
The following is the normal process used to create a SAR file:
- create a MaSarPackage object (which acts as the "builder" of the SAR file).
- Verify the package list, click the sort button to sort them into load order.
- Verify the files list; the latest versions in Monticello.
- Verify the auto-generated install script.
- Click the "generate" menu and specify the filename of the .SAR file.
Normally, most steps are just a verification, MaSarPackage does most of the work.
Step 1 (optional): Create a PackageInfo subclass to represent the package
This step is not actually required, but it is highly recommended to do so. By defining the #packageName and #prerequisitePackageNames of your package, MaSarPackage can include the entire pre-requisite tree and sort them in load-dependent order.
Here is the appropriate definition for the PackageInfo subclass for the MaSarPackage package:
PackageInfo subclass: #MaSarPackageInfo
instanceVariableNames: ''
classVariableNames: ''
poolDictionaries: ''
category: 'MaSarPackage-Info'
Typically the subclass name is suffixed with "PackageInfo" or, just, "Info" but it can be anything you want.
Implement the following methods, first, on the class side a method which identifies the package by name. This should be the Monticello package name:
packageName
^ 'MaSarPackage'
It is very common for a package to make use of another third-party package. MaSarPackage has two specific required packages: "Ma base additions" and "Ma files additions".
On the instance side, implement #prerequisitePackageNames to identify these two prerequisite package names:
prerequisitePackageNames
^ super prerequisitePackageNames ,
{ MaBaseAdditionsPackageInfo packageName.
MaFilesAdditionsPackagInfo packageName }
If the package has a change-set, such as to modify the base image, it can be specified in #patchNames. It answers an Array of Strings, where each string is the filename of the change set. These should be uncompressed (.cs, not .gz) since they will be compressed in the zip file anyway.
Step 2: Create the MaSarPackage
An instance of MaSarPackage is not persisted anywhere, it is only created in memory and used only to create the actual '.sar' file. To create the MaSarPackage, just use the #named: constructor, passing in the name specified by #packageName (which should also the name of the MC package):
(MaSarPackage named: 'MaSarPackage') maui
A Maui panel opens on the hand, set it down:
Step 3: Verify the package suite
Click the "packages" selector of the user-interface panel, a list of all of the packages proposed is presented, based on the prerequisitePackageNames specified by each package and their prereqisites, appears:
We only specified two prerequisites, why are there five prerequisite packages listed? Because "Ma files additions" package uses the other two, "Ma Statistics" and "MaFixedWidthReport".
Important: To ensure the packages load in the correct order, it is essential to click the sortPackages button. Once that is done, refresh the #packageList method (right click, "refresh" or just press the "r" key on the keyboard) and the load order reflects correctly.
Step 4: Verify the files that will go into the SAR
Click the "files" selector, the top versions of Monticello mcz files are listed that comprise the packages list. If #patchNames was overridden on any packages, those files will be included as well. On this panel, any additional resource files by dragging them to the argument of the #addFile: message.
Important: MaSarPackage can only package up files. It is therefore important, if you have unsaved changes to a Monticello package that you wish to be included in the SAR file, to first save the Monticello package.
The #calculateFiles may be used to reset the files list to the most-recent, and in load order based on the PackageInfo declarations.
Step 5: Verify the load script, add any post-initialization
Click the "script" selector, the exact script that will be executed upon loading the SAR file is displayed. This script is generated based on the packages / files in the MaSarPackage. If any additional "post-initialization" is needed (not common), it can be typed or pasted into the #init: parameter.
Step 6: Generate the SAR file
Click the "generate" selector, two messages are presented allowing you to specify a filename for the SAR and/or a directory location to put it in. If a directory-location is not specified, it goes in the current directory from where the image was launched.
