Monticello Importer
Monticello is a code versioning system used with
Pharo and
Squeak Smalltalk systems. Each Monticello archive contains a
Monticello package consisting of classes and methods.
SqueakSource, the newer
SqueakSource3, and other sites are central online repositories where applications used in those Smalltalk systems are stored. A Monticello package is most analogous to a VA Smalltalk Application. Monticello differs from the VA Smalltalk ENVY Repository in that each version of a Monticello package is stored as a separate Monticello file (
.mcz).
To share code between Pharo or Squeak and VA Smalltalk, it is useful to be able to import a Monticello package and create (or update) a VA Smalltalk Application from it.
Loading the Monticello Importer
The Monticello Importer is delivered as a loadable feature. To load it, use the Transcript Tools -> Load/Unload Features … to load the ST: Monticello Importer feature. Once the feature is loaded, you can access the Monticello Importer from the Application Manager’s Applications menu. The Monticello Importer is not currently enabled for use from the VA Organizer or from Trailblazer.
Using the Monticello Importer
After the Monticello Importer is loaded, the next time the Application Manager is opened there will be a new Import Application from Monticello … menu item available. If you are using the standard Application Manager, select Applications -> Import -> Import Application from Monticello …; if you are using the VA Assist Application Manager, select Applications -> Import/Export -> Import Application from Monticello ….
In either case, a File Selection Prompter will open allowing you to select the Monticello archive file that you want to import into VA Smalltalk. The Monticello packages can usually be found in the package-cache subdirectory of your Squeak or Pharo installation. If you Cancel the prompter, the import operation is ended.
Once a Monticello archive file is selected, you will be given an opportunity to set the application prerequisites using the Application Prerequisite Prompter. You’ll notice that the Monticello Importer makes a pretty good guess at the prerequisites based on the structure of the Application being imported, but you will sometimes need to make adjustments to include additional Applications that the Monticello Importer couldn’t identify. If you Cancel the prompter, the import operation is ended.
Finally you will be given the opportunity to version the imported Application. The importer will suggest a version name that matches the version name of the Monticello package. You can supply a different version name by overtyping the suggested name. If you want to leave the imported Application as an open edition, just Cancel this prompter.
What the Monticello Importer does
The importer processes a Monticello package in 2 steps:
•The parser step creates proto-objects from the content of the Monticello package
•The loader step processes the proto-objects to create actual VA Smalltalk Applications, Subapplications, Classes and Methods
This 2 step process is important because it allows the Monticello Importer to go beyond what could be done by a simple filein of all the code in a Monticello package. The importer can reflect on the package contents to determine the correct processing. This means:
•Classes and methods that haven’t changed are ignored
•Subapplications, Classes and Methods that have been refactored/reorganized are handled (as long as the changes are contained within one Monticello package)
•Deleted Subapplications, Classes and Methods are handled
The mapping of the content of a Monticello package to a VA Smalltalk Application goes as follows for the initial import of a Monticello package:
•A VA Smalltalk Application is created with a name MonticelloPackageNameApp
•MonticelloPackageNameApp will contain all *extension methods defined in the Monticello package as class extensions
•A VA Smalltalk Subapplication is created for each Monticello package category with a name MonticelloPackageCategory (with embedded hyphens removed)
•Each Subapplication contains all Classes defined in its Monticello package category
•Each Subapplication class has generated loaded, removing, and failedRemove methods
•All Class class side initialize methods are renamed initializeOnLoad (called from Subapplication loaded method)
•When you use MonticelloImporter to import code, all those classes that had an instance side #initialize won't work out of the box because they will miss a class side #new sending #initialize. To solve that, MonticelloImporter auto generates that class side #new. We automatically create this only for the root classes of the application we are importing. And only if they don't already have a custom #new defined.
•All methods are public
•All methods retain their Monticello categories except as yet unclassified becomes Not categorized
Monticello Importer Troubleshooting
Missing superclass
If an imported class is a subclass of a class that is not loaded in the image, the importer will stop with an error message.
Missing base class
If an imported class extension is for a class that is not loaded in the image, the importer will stop with an error message.
Method that won’t compile
If an imported class contains a method that doesn’t compile, the source of the method will be replaced by a method that does compile. The original content is wrapped in a comment and one executable line is added which will open a debugger when the method is executed.
Bad method
methodThatWontCompile
“Use a bad variable so the method doesn’t compile”
xyz := ‘?’
Replacement method:
methodThatWontCompile
"The following source failed to compile (all double quotes have been doubled):
""Use a bad variable so the method doesn't compile""
xyz := '?'
"
^ self halt: 'The source for this method failed to compile'