Glossaryofterms
A Project is a collection of Monticello packages and external projects. A Project has a name. The structure for the A Project is defined by a baseline. A Project is managed with a Metacello ConfigurationOf and optionally a Metacello BaselineOf class.
Your Project is the project that you are working on. You are intimate with the details of the project and you use the baseline to record your knowledge of the relationships between the Monticello packages and external projects that make up Your Project, so that others (less familiar with the intimate details) may load and use your project efficiently.
A Metacello ConfigurationOf is a Monticello package whose name follows the convention of prefixing the project name with 'ConfigurationOf'. The ConfigurationOf package contains a single class of the same name.
The methods in the ConfigurationOf class define a collection of basline versions and literal versions. When executed the methods produce an instance of the class MetacelloProject.
A Metacello Project is produced by sending the #project message to a configuration class, as follows:
ConfigurationOfSample project.
A Metacello Version is produced by sending the version: message to a Metacello Project as follows:
ConfigurationOfSample project version: '1.0'.
A Metacello Version is a declaration of the Monticello package versions and external project versions that comprise the Metacello Version.
A Metacello Version is defined by two components in a Metacello ConfigurationOf: a baseline version and a literal version.
A Metacello Version may be:
-
(ConfigurationOfSample project version: '1.0') load. -
(ConfigurationOfSample project version: '1.0') fetch. -
(ConfigurationOfSample project version: '1.0') record.
A Baseline Version defines project structure:
- project repository
- package and external project dependencies
- package groups
Here is a sample specification for a Baseline Version:
<version: '1.0-baseline'>
spec
for: #'common'
do: [
spec blessing: #baseline.
spec
project: 'External'
with: [
spec
version: '1.0-baseline';
repository: 'http://example.com/external' ].
spec
package: 'Sample-Core' with: [ spec requires: 'External'];
package: 'Sample-Tests' with: [ spec requires: 'Sample-Core' ].
spec
group: 'default' with: #('Sample-Core') ].
A Baseline Version may be specified in a ConfigurationOf or a BaselineOf class.
A Literal Version defines the explicit version for each Monticello package and external project.
Here is a sample specification for a Literal Version:
<version: '1.0' imports: #('1.0-baseline')>
spec
for: #'common'
do: [
spec blessing: #release.
spec project: 'External' with: '1.0'.
spec
package: 'Sample-Core' with: 'Sample-Core-dkh.398';
package: 'Sample-Tests' with: 'Sample-Tests-dkh.15' ].
A Monticello Package is a snapshot of Smalltalk classes and method definitions.
A Monticello Package has a name and a specification for the snapshot contents. By default, the following rules are applied against all classes and methods in an image:
- include the class in the snapshot, if the category begins with the name of the Monticello Package
- if a class is included in the snapshot, include all methods defined in the class except those belonging to a protocol whose name begins with '*'
- include a method in the snapshot if the method protocol begins with a '*', followed by the name of the Monticello Package (ignoring case)
A Monticello Snapshot may be saved to disk as:
- a mcz file in a Monticello mcz repository
- a package directory in a FileTree repository.
An Mcz File contains a serialization of the Smalltalk objects that make up the Monticello Snapshot. The serialized data stream is stored as a member in a zip file.
An Mcz File represents a particular version of a Monticello Snapshot.
The name of an Mcz File includes the package name (ConfigurationOfFileTree), author (dkh), and version number (14):
ConfigurationOfFileTree-dkh.14.mcz
An Mcz Repository is a repository for a collection of Mcz Files. Versions for multiple Monticello packages may be stored in a single repository:
+-repository
+-ConfigurationOfFileTree-dkh.14.mcz
+-ConfigurationOfFileTree-dkh.13.mcz
+-ConfigurationOfFileTree-dkh.12.mcz
+-MonticelloFileTree-Core-dkh.36.mcz
+-MonticelloFileTree-Core-dkh.35.mcz
+-MonticelloFileTree-Core-dkh.34.mcz
+-MonticelloFileTree-Core-dkh.25.mcz
+-MonticelloFileTree-Core-dkh.21.mcz
+-MonticelloFileTree-Core-dkh.20.mcz
+-MonticelloFileTree-GemStone-Extensions-revelations.11.mcz
+-MonticelloFileTree-Core-dkh.35.mcz
+-MonticelloFileTree-Core-dkh.34.mcz
A Package Directory maps the Monticello Snapshot content to files and directories:
+-Sample-Core.pkg\
+-snapshot\
| +-classes\
| | +-SampleCore.class\
| | +-SampleCore.st
| | +-instance\
| | +-author.st
| +-extensions\
| +-Object.class\
| +-instance\
| +-isSample.st
+-.filetree
+-categories.st
+-initializers.st
+-package
+-version
The Package Directory records the same information as an mcz file. Packages that are stored in a Package Directory can be copied to an mcz file (and back) with no loss of information.
Storing a snapshot on disk opens the way for using traditional Source Code Management(SCM) systems like Apache Subversion, Git, and Mercurial for managing Smalltalk source code.
A FileTree Repository is a repository for a collection of package directories:
+-FileTree
+-repository/
| +-metacello.json
| +-MonticelloFileTree-Core.pkg\
| +-MonticelloFileTree-GemStone-Extensions.pkg\
| +-BaselineOfFileTree.st
The FileTree Repository differs from the Monticello mcz repository in that a FileTree Repository only stores one version of each Monticello package.
This approach is consistent with the the way that a version in a traditional SCM includes all of the files and directories within a particular directory structure.
With a traditional SCM, all of the packages in the FileTree Repository are versioned together, so it becomes unnecessary for Metacello to specify a literal version. Consequently, managing a full configuration for projects stored in a FileTree Repository is overkill.
On the other hand, the baseline version, which specifies the dependencies between packages and external projects is still necessary and important.
The packages and external projects are managed with a Metacello BaselineOf.
A Metacello BaselineOf is a Monticello package whose name follows the convention of prefixing the project name with 'BaselineOf'. The BaselineOf package contains a single class of the same name.
The methods in the BaselineOf class define a single baseline version for the project. When executed the methods produce an instance of the class MetacelloMCBaselineProject.
The specification the baseline in a BaselineOf looks just like a typical baseline specification. The main difference is in the pragma used to identify the method:
baseline: spec
<baseline>
spec
for: #'common'
do: [
spec
package: 'External-Core';
package: 'External-Tests' with: [ spec requires: 'External-Core' ];
yourself.
spec
group: 'Core' with: #('External-Core');
group: 'default' with: #('Core');
group: 'Tests' with: #('External-Tests');
yourself ]
Loaded Projects is the list of projects that are currently loaded in your image. Once a project has been loaded into your image, the Metacello Scripting API will neither upgrade nor downgrade the version of the project, even if a project that is being loaded requires a later version of the Loaded Project.
This is a departure from what Metacello does when loading a version using:
(ConfigurationOfXXX project version: '1.0') load.When loading a version a version the old way, Metacello will upgrade the version of an already loaded project.
You can explicitly upgrade a project by using the upgrade command.
Registered Projects is a list of external project specifications for projects that are not yet loaded into your image. When an attempt is made to load a registered project, the registered specification* is used instead of the specification from the configuration.
External Projects refer to projects that your project depends upon.
The Project Repository is the repository where your configuration and packages are stored/
A Package Group is a named list of package, projects or other groups. The group name may be used anywhere that a name is used within a specification.