On this page:
1.1 Finding a Package
1.2 Shorthand Syntax
1.3 Networking troubles
1.4 Fine-Grained Control Over Package Imports
1.5 Monitoring PLane T’s progress

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.

To see how this works, lets assume you want to install the PLAI package and
  (require (planet plai/plai:1))
is not working for you.
  • First, fire up a command-line window and use raco planet url to determine the url for downloading the package. To find the url for version (1 1) of the plai package, do this:

    % planet url plai plai.plt 1 1

    and get this as a response:

    http://planet.racket-lang.org/servlets/planet-servlet.rkt?lang=%224.1.5.3%22&name=%22plai.plt%22&maj=1&min-lo=1&min-hi=%23f&path=%28%22plai%22%29

  • Copy and paste that url into your browser, which should trigger the dowload of a file called plai.plt. Note that your browser will probably try to call the file something else. Rename it to plai.plt.

  • Now run the command-line tool one more time to install the plt file:

    % planet fileinject plai plai.plt 1 1

    This command should be run from the same directory where you saved plai.plt.

    This command may fail, since version (1 1) of the PLAI package depends on cce/scheme:4:1. If it does, simply repeat the above steps for that package first, and then continue with the fileinject command for PLAI.

  • Finally, to check that the installation is successful, run raco planet show. You should see output like this (possibly with slightly different version numbers, if the packages have been updated since this was written):

    Normally-installed packages:

      cce scheme.plt 4 1

      plai plai.plt 1 1

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

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.

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