Project

The Metacello Scripting API is all about manipulating projects. The project in the Metacello Scripting API is very similar to the project spec that you use when defining external references in a baseline version:

    spec
        project: 'Gofer'
        with: [ 
            spec
                className: 'ConfigurationOfGofer';
                versionString: '1.0';
                loads: #('Core');
                repository: 'http://seaside.gemstone.com/ss/metacello' ]

with minor differences:

    Metacello new
        project: 'Gofer';
        version: '1.0';
        repository: 'http://seaside.gemstone.com/ss/metacello';
        load: #('Core').

The Metacello Scripting API constructs the name of the configuration class by tacking a 'ConfigurationOf' on the front of the projectName.

##Tracked Projects The Metacello Scripting API keeps track of the projects that are loaded into your image. The map is keyed by project name and the value is an instance of MetacelloProject using the name, version, and repository fields.

##Registered Projects One may register a project with the Metacello Scripting API, specifying a name, version, and repository.

##Pinned Projects The Metacello Scripting API has an affinity for project versions that are tracked or registered.

When a load is initiated through the Metacello Scripting API, Metacello will use the version and repository for the tracked or registered projects instead of the ones specified by the configurations.

If one wants to override the project pinning, then one should use the upgrade command. ##Example For example, here's a spec for version 1.0 of the Sample project (Note that the baseline and version specs are collapsed into a single spec):

version100: spec
  <version: '1.0'>
  spec
      for: #'common'
      do: [ 
          spec
              project: 'External'
              with: [ 
                  spec 
                      className: 'ConfigurationOfExternal';
                      versionString: '1.0';
                      repository: 'http://example.com:External' ].
          spec
              package: 'Sample-Core' with: [ 
                  spec 
                      file: 'Sample-Core-dkh.1';
                      requires: 'External' ] ].

If you execute the following expression in a fresh image:

    Metacello new
        project: 'Sample';
        version: '1.0';
        load.

you expect that version 1.0 of the External project to be loaded. However, if one had registered version 0.9 of the External project prior to loading the Sample project:

    Metacello new
        project: 'External';
        version: '0.9';
        repository: 'http://example.com:External';
        register.

then version 1.0 of the External project would not loaded by the following:

    Metacello new
        project: 'Sample';
        version: '1.0';
        load.

because the External project is pinned at version 0.9. To explicitly load version 1.0 of the External project once it has been pinned use the upgrade command as follows:

    Metacello new
        project: 'External';
        version: '1.0';
        upgrade.

##Rationale When using directory based repositories where all of the files in the repository are at the same version it is necessary for the developer to be able to exert explicit control over which versions of each project is being used ... yes to the point where the required version for another project is not loaded.

Notifications are signaled during the load process when pinned projects are encountered so developers are able to programmatically control the pinning behavior.