Since ESUG, Tudor Girba and I have collaborated to define a shiny new API on top of the Metacello engine. I released version 1.0-beta.3 of Metacello today, so you can take the new API for a spin.

The new API is completely different than the API described in my previous post: Metacello: Package Management for Monticello. The basic concepts and functionality hasn’t changed, but the details of the API have been changed significantly.

The best way to pick up the new API is to take the tutorial or read the Metacello API Reference on the Metacello Google code project.

The following sections are intended to give you a taste of the new Metacello API.

Metacello Configuration

To create a Metacello configuration for your project, you start by copying the class MetacelloConfigTemplate to your own class (i.e., SeasideConfiguration, MetacelloConfiguration, YourProjectNameConfiguration, etc.). MetacelloConfigTemplate has a handful of helper methods defined. MetacelloConfigTemplate is a subclass of Object, so a Metacello configuration can be loaded into an image without requiring Metacello itself to be pre-loaded. The #ensureMetacello method bootstraps Metacello into an image if Metacello has not already been loaded.

Once you’ve created your project configuration class, you can start defining your project metadata.

The metadata for a project has been split into two distinct components: the baseline and the version.The baseline defines project structure and the version defines package versions.

Baseline definition

The baseline defines the structure of your project in terms of the list of packages involved, the dependencies between packages and the groupings of packages. The


The baseline structure of your project should be stable relative to the version definition.

Similar to the old versionSpec, you can specify a collection of attributes for a baseline (see the API Reference page for a full list of attributes):

  • author. The author of a particular version
  • blessing. A version can be tagged with a blessing like #alpha, #beta, #release, #development, #baseline, or any other tag that is deemed useful. The blessing is used as a version filter. For example the latest version of a Metacello project is currently defined as the latest version whose blessing is not #development or #baseline.
  • description. Useful information about the version.
  • timestamp. The create date and time for a version.
  • packages. A list of Monticello package versions that make up the project.
  • repositories. A list of Monticello repositories from which the packages can be loaded.
  • groups. An alias for a collection of packages.
  • projects (not shown). A list of Metacello configurations for other projects that a package within the current project may require. For example, you would use a project to specify the dependency that a Pier project has upon the Seaside and Magritte projects.

A baseline is a full-fledged version, so it can be loaded. When the loader encounters a package for which a specific version has not specified, the loader will load the latest version of the package from the repository.

Version definition

The version definition associates an explicit list of package versions with a named version. Once a version is snapped off, it should never change so that at any point in time one can come back to a specific version with confidence. The version gets its structural information by imported another version (typically a baseline version).


The same list of attributes associated with the baseline definition can be specified for the version definition.

Metacello Tools

The OB-based Metacello tools have been slightly changed since I originally wrote about them.

[Update 11/03/2009] For the most up-to-date documentation visit the  Metacello Tools page.

The Spawn New Version command has been added, the Load Project Version command has been changed and finally the  Update Package Repositories command has been eliminated.

Select a Metacello configuration class and bring up the Class menu:


Save Packages

Finds the dirty Monticello packages that are members of the selected version of the Metacello project and saves them, prompting you for version name and commit comment. After the packages are saved you are prompted to Update Package Methods.

Spawn New Version

Genearates a new version method prompting for source version, version number and the new methods selector. The package specs for the new method reflect the currently loaded Monticello package versions, like the Update Package Methods command.

Update Package Methods

Automatically updates the package spec metadata for the selected version (i.e., modifies and compiles the methods with the #packages:attribute: pragma for the appropriate version to match the currently loaded Monticello package versions). After the methods are update you are prompted to Save Project.

Current Project Version

Displays the current version of the selected Metacello project. The version is calculated by comparing the currently loaded Monticello packages to those specified in the version spec. A leading ‘~’ means that the version is partially loaded (i.e., not all of the packages associated with the project have been loaded into the image).

[Update 11/03/2009] For the most up-to-date documentation visit the  Metacello Tools page.

Load Project Version

Prompts for the version of the selected Metacello project to be loaded, then loads all of the packages in the project using the ‘ALL’ pseudo group.

Save Project

Saves the selected Metacello project to the repository specified by the project package of the selected version. You are prompted for version name and commit comment.

Update Project

Loads the latest Monticello package version from the repository specified in the project package of the selected version of the Metacello project. Remember that you are simply loading the Metacello project metadata, so it doesn’t hurt to have the latest metadata loaded. Once the latest version is loaded, you are prompted to Load Project Version.

[Update 11/03/2009] For the most up-to-date documentation visit the  Metacello Tools page.

Loading Metacello

[Update 11/04/2009] For the most up-to-date download instructions visit the Metacello donwload page.

To use Metacello in GLASS, modifications to some base classes are needed, so you will still have to wait until I publish a GLASS package to bootstrap Metacello into GLASS.

To load Metacello into Squeak or Pharo:

  1. Load the latest version of the Metacello-Configuration-dkh.50ConfigurationOfMetacello package from http://seaside.gemstone.com/ss/metacello
  2. Execute the following expression in a workspace:
    MetacelloConfigurationConfigurationOfMetacello loadLatestVersion.

The above expression loads all of Metacello into your image (including the OB-based tools). If you want to load a minimal configuration, exucute the following expression in a workspace:

MetacelloConfigurationConfigurationOfMetacello project latestVersion load.

To learn about other loading options, take the Tutorial:)


The tutorial covers all of the important Metacello features in some detail. To ensure that the tutorial is loaded, execute the following expression:

MetacelloConfigurationConfigurationOfMetacello project latestVersion load: 'Metacello-Tutorial'.

Then open two class browsers on the MetacelloTutorialConfig class. In the left hand browser view the methods in the ‘lessons’ category. In the right hand browser view the ‘–all–‘ category. Read the comments in lesson01 through lesson13.

Current Status

Version 1.0-beta.3 is the current version of Metacello, is feature complete and I am happy with the configuration API. I will port the new API to GLASS as part of my Seaside 3.0 porting work.

announced a SeasideConfiguration for Seaside 3.0 the other day that is based on the new Metacello API.

I have created a  Metacello Google code project for bug tracking and distributing up-to-date information about Metacello. If you run into problems with the tutorial or using Metacello, please submit a bug.

[1]Photo by ahhyeah (Creative Commons).