Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 38 ยท Tools and Image Workflow

Metacello, Baselines and Package Loading

Learn how Smalltalk projects declare packages, dependencies and groups with Metacello baselines, load them reproducibly, and run them in CI. Read-only Smalltalk plus a runnable dependency-resolver stand-in.

A project is rarely one package. It has core code, tests, tools and dependencies on other projects, and every developer and every build server needs to assemble the same set in a fresh image. Metacello is the package-management layer of Pharo and Squeak that does this. You describe your project once in a baseline class, and Metacello loads it, with its dependencies, in the right order.

This lesson shows a real baseline (read-only, since Metacello is not available here), the loading expressions you use daily, and how version pinning and CI work. A JavaScript stand-in resolves dependencies so you can see how a load order is computed.

The baseline class

A baseline is a class whose name starts with BaselineOf. Its baseline: method describes the structure of the project, not the versions (read-only):

SMALLTALK
BaselineOf subclass: #BaselineOfBank
    package: 'BaselineOfBank'.

BaselineOfBank >> baseline: spec
    <baseline>
    spec for: #common do: [
        spec
            baseline: 'NeoJSON'
            with: [ spec repository: 'github://svenvc/NeoJSON/repository' ].
        spec
            package: 'Bank-Core' with: [ spec requires: #('NeoJSON') ];
            package: 'Bank-Tests' with: [ spec requires: #('Bank-Core') ].
        spec
            group: 'default' with: #('Bank-Core');
            group: 'tests' with: #('Bank-Core' 'Bank-Tests') ]

It declares:

  • Packages (Bank-Core, Bank-Tests) and what each requires.
  • External baselines (NeoJSON) with where to fetch them.
  • Groups (default, tests), named subsets that users can load.

The baseline lives in the repository next to the source, which is why a Git checkout is enough to rebuild the project.

Loading

The standard loading expression names the baseline and a repository (read-only):

SMALLTALK
Metacello new
    baseline: 'Bank';
    repository: 'github://example-user/bank:main/src';
    load.

"only the tests group"
Metacello new
    baseline: 'Bank';
    repository: 'github://example-user/bank:v1.2.0/src';
    load: 'tests'.

The part after the colon in the repository string is a Git reference: a branch (main), a tag (v1.2.0) or a commit. Pinning a tag gives a reproducible build; following main gives the newest code. You can also lock a project in the image so that a later load does not move it:

SMALLTALK
Metacello new
    baseline: 'Bank';
    repository: 'github://example-user/bank:v1.2.0/src';
    lock.

Depending on your project

When another project uses yours, it lists a baseline in its own spec:

SMALLTALK
spec baseline: 'Bank' with: [
    spec repository: 'github://example-user/bank:v1.x.x/src' ].

The v1.x.x form is a semantic version pattern, so a project gets compatible updates but never a breaking v2. Cycles and conflicting versions are detected when you load.

Resolving a load order

Metacello must load a package after everything it requires. That is a topological sort. This runnable stand-in computes the order for a small project, detects a cycle, and expands a group.

JS Stand-in: a dependency resolver

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Dependencies are always loaded first, and a cycle is reported instead of looping forever.

Version patterns

Semantic version patterns like v1.x.x and v1.2.x match compatible tags. This stand-in picks the newest tag that matches.

JS Stand-in: choosing a tag from a pattern

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Note the numeric comparison: v1.10.0 is newer than v1.2.3, which string sorting would get wrong.

Continuous integration

A CI job for a Pharo project is short (read-only):

  1. Download a fresh image and VM (the Pharo launcher or the zeroconf script).
  2. Run Metacello new baseline: ...; load: 'tests' against the checked-out repository.
  3. Run the test suite headlessly and fail on any red test. SUnit provides the runner.
  4. Optionally publish a coverage report or a tagged release.

Building from a clean image each time keeps you honest, as explained in the image workflow.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a baseline describe?

    A baseline is a structure description; versions come from the repository reference.
  2. 2. What does the part after the colon in github://user/repo:v1.2.0/src mean?

    It selects which Git commit to load, so tags make builds reproducible.
  3. 3. What does v1.x.x allow?

    A pattern accepts any matching minor and patch release within major version 1.
  4. 4. Why is dependency order computed with a topological sort?

    Loading a package before its dependencies would fail to compile references.

Summary

  • A BaselineOf... class declares packages, requirements, external baselines and groups.
  • Metacello new baseline:; repository:; load assembles the project; the Git reference in the URL pins the version.
  • Version patterns such as v1.x.x pick compatible releases; locks freeze them.
  • Load order is a topological sort and cycles are errors.
  • The Metacello code is read-only; the resolvers are JavaScript stand-ins.

Next: Testing with SUnit