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 do 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.rkt" ("schematics" "spgsql.plt" 2 3)))

into your program. This line requires the file "spgsql.rkt" 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.rkt" 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

The code snippet above 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 ".rkt" 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.rkt" in the given package.

1.3 Networking troubles

Sometimes, when PLaneT tries to download and install a package for the first time, your operating system may block it from access to the network. If you are uncomfortable giving DrRacket free access to the network (or if your attempts to do so do not seem to work), then you can use your browser to manually install a planet package.

Once that is complete, PLaneT will use that version of the package for any subsequent requires and won’t try to use the network.

If you wish to ensure that PLaneT won’t use the network even if your operating system allows it, you can use the download? parameter of the planet/resolver module to control whether it attempts to download files. Similarly, you can use the install? parameter to prevent installation. Finally, you can block access at the operating system level to the path returned by (PLANET-BASE-DIR) to control which operating system users can install PLaneT packages.

1.4 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.rkt" ("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.rkt" ("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.

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.rkt"

("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.rkt" ("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.rkt" ("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.

1.5 Monitoring PLaneT’s progress

PLaneT logs information about what it is doing to the info log (via log-info). In DrRacket, you can view the logs from the Show Log menu item in the View menu, and Racket’s logging output can be controlled via command-line options and via environment variables. See Logging for more details.