Metacello Scripting API Documentation
The Metacello Scripting API provides a platform independent way for loading Metacello configurations into your image.
- Using the Metacello Scripting API
- Scripting API Referenece
- Best Practice
- Specifying Configurations
- Metacello Version Numbers
In Pharo 3.0, Metacello Scripting comes pre-installed. For other platforms...
To get started we need to load the
In an older Pharo image:
"Get the Metacello configuration" Gofer new gemsource: 'metacello'; package: 'ConfigurationOfMetacello'; load.
or a Squeak4.3 image:
Installer gemsource project: 'metacello'; install: 'ConfigurationOfMetacello'.
Metacello #'previewBootstrap' and install the
Metacello Preview code (both images):
((Smalltalk at: #ConfigurationOfMetacello) project version: #'previewBootstrap') load. (Smalltalk at: #Metacello) new configuration: 'MetacelloPreview'; version: #stable; repository: 'github://dalehenrich/metacello-work:configuration'; load.
Once the Metacello Scripting API is released, the Metacello class will be installed in the base images for GemStone, Pharo and Squeak and bootstrapping will no longer be necessary.
Using the Metacello Scripting API
Metacello loads the packages and dependencies (required projects) for a project based on the specifications in the configuration of a project.
Metacello new configuration: 'Sample'; squeaksource3: 'Sample'; version: '0.9.0'; load.
ConfigurationOfSample package from
proceeds to load the
default group of
Sample 0.9.0 into your image.
The above expression is equivalent to the following old-style
Gofer new squeaksource3: 'Sample'; package: 'ConfigurationOfSample'; load. ((Smalltalk at: #ConfigurationOfSample) project version: '0.9.0') load.
Besides being a bit more compact, the Metacello scripting API uses a few
handy default values for the version and repository attributes.
The default version attribute is
#stable and the default
repository attribute is platform-dependent
Applying the default values, the following expression:
Metacello new configuration: 'Sample'; load.
is equivalent to (assuming the platform-specific default repository is
Metacello new configuration: 'Sample'; squeaksource3: 'Sample'; version: #stable; load.
Arguments to the load command may be used to specify which groups,
packages or dependent projects should be loaded instead of the
This command loads the
Core group for the
#stable version of
Metacello new configuration: 'Sample'; load: 'Core'.
This command loads the
Core group and the 'Sample-Tests' package
#stable version of
Metacello new configuration: 'Sample'; load: #('Core' 'Sample-Tests').
The load operation is performed in two phases.
In the first phase, all
of the packages that are to be loaded into your image are fetched from their respective
repositories and stashed in the Monticello
package-cache. If there
is an network error during the
fetch phase, you can execute the
load command again, and Metacello will not attempt to re-fetch any
packages that are already present in the
In the second phase the packages are loaded into your image.
load return value
The load command returns an instance of MetacelloVersionLoadDirective which when printed, gives you a report of the packages loaded into your image.
The following expression:
Metacello new configuration: 'Sample'; version: #stable; repository: 'github://dalehenrich/sample:configuration'; load.
linear load : explicit load : 0.8.0 [ConfigurationOfSample] linear load : 0.8.0 [ConfigurationOfSample] linear load : baseline [BaselineOfSample] load : Sample-Core-dkh.2
If a configuration is already present in the image when the load command is executed, the existing configuration is used. Use the get command to refresh the configuration.
The default repository is platform-dependent. Evaluate the following Smalltalk expression to determine the default repository for your platform:
MetacelloPlatform current defaultRepositoryDescription
github://projects are implicitly locked when loaded.
filetree://projects are implicitly locked when loaded unless loaded as a project dependency.
See the Options section for additional information.
Automatically upgrading projects is not always desirable. Of course, in the normal course of loading and upgrading, you want the correct version of dependent projects loaded. However under the following conditions:
- You may be actively developing a particular version of a project and you don't want the project upgraded (or downgraded) out from under you.
- You may be working with a git checkout of a project and you want to continue using the git checkout.
you may not want to have particular projects upgraded automatically.
lock command gives you control.
You can lock a project to a particular version:
Metacello new configuration: 'Sample'; version: '0.9.0'; lock.
If you don't specify an explicit version, then the currently loaded version of the project is locked:
Metacello image configuration: 'Sample'; lock.
lock return value
The lock command returns an instance of the MetacelloProjectRegistration class that when printed, displays the version and repository for the locked project.
The following expression:
Metacello new configuration: 'Sample'; lock.
ConfigurationOfSample stable from github://dalehenrich/sample:configuration
You can obtain a list of
locked projects in the registry:
Metacello registry locked.
To obtain a list of
locked projects loaded in the image:
Metacello image locked.
The locked command returns a list of locked project specs.
To lock a git checkout for a project, you should lock the
Metacello new baseline: 'Sample'; lock.
- Additional documentation and an example locking project are available ### Unlocking
To unlock a project, use the
Metacello new project: 'Sample'; unlock.
unlock return value
If you are interested in looking at a configuration you may use the get command to load the configuration of a project into your image:
Metacello new configuration: 'Sample'; get.
You can specify an explicit repository from which to get the configuration:
Metacello new configuration: 'Sample'; squeaksource3: 'Sample'; get.
get return value
This command downloads all of the Sample packages into the local
Metacello new configuration: 'Sample'; version: '0.8.0'; fetch: 'ALL'.
You can specify a different repository to be used as the
The following command copies all of the Sample packages into the filetree repository in
Metacello new configuration: 'Sample'; version: '0.8.0'; cacheRepository: 'filetree:///opt/git/localSampleRepository'; fetch: 'ALL'.
If a project has dependent projects, then the packages for the dependent projects that would be loaded in the iamge are also copied.
The fetch command duplicates what the load command would
do, which means if a package is alrady loaded in the image, it will not be fetched.
To fetch packages regardless of what is loaded in the image, use the
Metacello new configuration: 'Sample'; version: '0.8.0'; cacheRepository: 'filetree:///opt/git/localSampleRepository'; ignoreImage; fetch: 'ALL'.
If you have fetched your packages to a location on disk, you can use the following variant of the load command to load your project from the disk location:
Metacello new configuration: 'Sample'; version: '0.8.0'; cacheRepository: 'filetree:///opt/git/localSampleRepository'; load: 'ALL'.
fetch return value
The record command performs the same function as the fetch command, without actually downloading any files. As a consequence, it can give you a quick report of what packages will be loaded into your image.
record return value
Printing the following expression:
Metacello new configuration: 'Sample'; record.
linear load : linear load : 0.8.0 [ConfigurationOfSample] load : BaselineOfSample linear load : 0.8.0 [ConfigurationOfSample] linear load : baseline [BaselineOfSample] load : Sample-Core
The list command may be used to list projects in a repository:
Metacello new configuration: [:spec | true ]; repository: 'github://dalehenrich/sample:configuration'; list.
or loaded in the image:
Metacello image configuration: [:spec | true ]; list.
Metacello registry configuration: [:spec | true ]; list.
list return value
The list command returns a collection of instances of the MetacelloProjectSpec class.
Scripting API Referenece
The Repository description is a URL that is used to resolve the location of Metacello repositories.
The general form of the description:
Where the scheme may be any one of the following:
The layout of the location is dependent upon the scheme being used.
client:// <full directory path to Monticello repository>
dictionary:// <Global name of dictionary containing Monticello repository instance>
filetree:// <full directory path to Filetree repository>
ftp:// <ftp server host name> [: <port> ] </ path>
NOTE: Squeak and Pharo only.
github:// <github user> / <github project> [ : <version identifier> ] [ / <repository path> ]
The semantics used are based on those of the GitHub API used to retrieve a ZIP archive of parts of a GitHub repository.
Unfortunately GitHub has no official documentation on the matter. Apparently, to get a ZIP archive of some resource
the URL must look like this:
https://github.com/<github user>/<github project>/zipball/<version identifier>/
gitthub:// is the scheme identifier for the GitHub repository description.
*github user *is the user name or organization name of the owner of the GitHub proejct.
github project is the name of the GitHub project.
version identifier is the name of a branch, the name of a tag or the SHA of a commit. The tag name and SHA
identifies a specific commit. The branch name resolves to the current HEAD of the branch. The version identifier is optional.
repository path is the path to a subdirectory in the project where the repository is rooted. If absent the repository is rooted in the projects HOME directory.
http:// <http server host name> [: <port> ] </ path to Monticello repository>
server:// <full directory path to Monticello repository>
NOTE: GemStone only.