1 Using PLaneT

To use a PLaneT package in a program, require it using the planet require form (see Importing and Exporting: require and provide for a full reference on the features of the require statement in general and the exact allowed grammar of PLaneT require statements). Here we explain how to use PLaneT by example.

1.1 Finding a Package

If you are new to PLaneT, the first thing to to is visit the PLaneT repository web site and see what packages are available. People contribute new PLaneT packages all the time – if you want to be notified whenever a new or updated package is released, you can subscribe to the (announcement-only) PLaneT-announce mailing list or use an RSS reader to subscribe to PLaneT’s RSS feed.

To use a package from PLaneT in your program, the easiest thing to do is copy the require code snippet off of that package’s page and paste it ino your program. For instance, to use Schematics’ spgsql.plt package (a library for interacting with the PostgresQL database), as of this writing you would copy and paste the line:

(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 3)))

into your program. This line requires the file "spgsql.ss" in package version 2.3 of the "spgsql.plt" package written by "schematics". That does two things: first, it downloads and installs a version of "spgsql.plt" that is compatible with package version 2.3 from the central PLaneT repository if a compatible version hasn’t already been installed. Second, it requires the module in file "spgsql.ss" from that package, making all of its exported bindings available for use.

Unlike with most package-distribution systems, package downloading and installation in PLaneT is transparent – there’s no need for you to do anything special the first time you want to use a package, and there’s no need for you to even know whether or not a particular package is installed on your computer or the computers where your code will be deployed.

1.2 Shorthand Syntax

As of PLT Scheme version 4.0, the code snippet in section Finding a Package can also be written using a new shorter syntax:

(require (planet schematics/spgsql:2:3/spgsql))

The two forms behave identically. In the abbreviated syntax, however, it is illegal to write the trailing ".ss" suffix on the file name to be required or the trailing ".plt" on the package file name. (They are mandatory for the long-form syntax.) It is also legal in the abbreviated syntax to omit a filename to be required entirely; in that case, PLaneT requires the file "main.ss" in the given package.

1.3 Fine-Grained Control Over Package Imports

The PLaneT client is designed to balance two competing goals: transparent upgradability and control over the effect of a package requirement. To that end, the most basic PLaneT require form offers maximum upgradability, but several more specialized forms allow finer-grained control over what versions of the named package may be downloaded.

Package versions should not be confused with program or library versions; a package version is a PLaneT-specific version number that encodes backwards-compatibility information.

The most basic planet require line, which is what is used in the form

(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 3)))

in longhand notation, or

(require (planet schematics/spgsql:2:3/spgsql))

in shorthand notation, should be read “Require from PLaneT any release of Schematics’ "spgsql.plt" package that is backwards-compatible with package version 2.3.” (The actual package version used is determined by the PLaneT search order.) To signal this explicitly, it is possible to write

(require (planet "spgsql.ss" ("schematics" "spgsql.plt" 2 (+ 3))))

or

(require (planet schematics/spgsql:2:>=3/spgsql))

both of which mean the same thing as the first pair of require lines.

See Determine Your Package’s Backwards-Compatibility for a more detailed discussion of backwards-compatibility obligations for PLaneT packages.

The notion of “backwards-compatibility” has a specific meaning in PLaneT: by definition, for the purposes of automation, a package is considered to be backwards-compatible with any other package of the same owner, name, and major version, and any lower minor version. Package maintainers are responsible for marking new releases that break backwards-compatibility by incrementing their major-version number. This means that all of the above require specifications will match any release of "unlib.plt" with major package version 3 (and any minor version), but will never match releases of "unlib.plt" with higher (or lower) major version numbers.

Of course a package author may make a mistake and introduced a backwards-incompatibility unintentionally, or may fix a bug that code in third-party libraries was already working around. In those cases, it may help to make use of the “upper bound” form of the planet require, in longhand form:

(require (planet "reduction-semantics.ss" ("robby" "redex.plt" 4 (- 3))))

and using shorthand notation:

(require (planet robby/redex:4:<=3/reduction-semantics))

In this require line, any version of the package "redex.plt" from package version 4.0 to package version 4.3 will match the require spec (though as with any PLaneT require specification, the PLaneT package search order determines which package is actually loaded).

It is also possible to specify both an upper and a lower bound, using the planet require’s “range” form:

(require (planet "test.ss" ("schematics" "schemeunit.plt" 2 (9 10))))

or

(require (planet schematics/schemeunit:2:9-10/test))

This form matches any package in the specified range (inclusive on both ends), in this example the specifications match either package version 2.9 or 2.10 of the "schemeunit.plt" package, but do not match version with higher or lower minor version numbers (or any other major version number).

Using the range form, it is possible to require a specific version of a package as a special case (choosing the upper and lower bounds to be equal), but this is a common enough case that it has special support with the “exact-match” form:

(require (planet "unzip.ss" ("dherman" "zip.plt" 2 (= 1))))

or

(require (planet dherman/zip:2:=1/unzip))

match only the exact package version 2.1 of the "zip.plt" package.