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.
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 —
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:
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.
The code snippet above can also be written using a new shorter syntax:
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.
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.
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:
% raco planet url plai plai.plt 1 1
and get this as a response:
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:
% raco 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):
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.
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.
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
in longhand notation, or
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
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.
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:
and using shorthand notation:
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:
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:
match only the exact package version 2.1 of the "zip.plt" package.
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.