5 Utility Libraries

The planet collection provides configuration and utilities for using PLaneT.

5.1 Resolver

The primary purpose of this library to for require to find PLaneT packages. It also, however, provides some utilities for manipulating the resolvers behavior.

If the PLaneT package is not actually installed, then this function expects to be called with a very powerful security guard, one that is available to the built-in module name resolver, but not generally available to user code. So probably this function will fail (possibly deadlock).

This is the same function as the one with the same name, exported by planet/util.

5.1.1 Resolver file locking

When PLaneT is asked to resolve a module path for loading the file (e.g., when the last argument to the (current-module-name-resolver) is #t and that resolver triggers a call to the PLaneT resolver), it finds the directory where the files are installed, say in this directory, which corresponds to version 1.2 of dyoo’s closure-compile.plt package:

"(CACHE-DIR)/dyoo/closure-compile.plt/1/2/"

If the file

"(CACHE-DIR)/dyoo/closure-compile.plt/1/2.SUCCESS"

is there, it assumes that there is no installation needed and it just continues, using the path to the file inside that directory.

If the "2.SUCCESS" file is not there, then it attempts to grab an 'exclusive filesystem lock on this file (via port-try-file-lock?)

"(CACHE-DIR)/dyoo/closure-compile.plt/1/2.LOCK"

If it gets the lock, it then proceeds with the installation, calling raco setup to do the unpacking, compilation, and docs building. After the unpacking has finished, but before beginning compilation and docs building, it creates the "2.UNPACKED" file:

"(CACHE-DIR)/dyoo/closure-compile.plt/1/2.UNPACKED"

When compilation and docs build are complete, it creates the "2.SUCCESS" file:

"(CACHE-DIR)/dyoo/closure-compile.plt/1/2.SUCCESS"

and releases the lock on the "2.LOCK" file.

If it fails to get the lock on "2.LOCK" and it does not already hold the lock (due to a re-entrant call to the resolver (the resolver knows about locks it holds via an internal parameter that gets created when the planet/resolver module is instantiated) then it goes into a loop that polls for the existence of the "2.SUCCESS" file; when it that file appears, it just continues, without installing anything (since that means someone else installed it).

In some situations (e.g., when a new namespace is created and a fresh instantiation of planet/resolver is created), PLaneT can be fooled into thinking that it does not hold the lock on some installation. In order to cope with these situations somewhat, PLaneT takes an easier path when the resolver is only looking for information about package files (i.e., when the last argument to the resolver is #f, or when get-planet-module-path/pkg is called directly (as opposed to being called via module resolution). In those cases, PLaneT will look only for the "2.UNPACKED" file instead of the "2.SUCCESS" file.

5.2 Client Configuration

The planet/config library provides several parameters useful for configuring how PLaneT works.

Note that while these parameters can be useful to modify programmatically, PLaneT code runs at module-expansion time, so most user programs cannot set them until PLaneT has already run. Therefore, to meaningfully change these settings, it is best to manually edit the "config.rkt" file.

Defaults to (version).

5.3 Package Archives

5.4 Package Utils

The planet/util library supports examination of the pieces of PLaneT. It is meant primarily to support debugging and to allow easier development of higher-level package-management tools. The functionality exposed by the raco planet command-line tool is also available programmatically through this library.

The pkg argument must end with ".plt".

See get-package-spec to build a pkg-spec argument.

Returns a new pkg-spec? corresponding to the package that was actually installed.

The pkg argument must end with the string ".plt".

The linkage table is an association between file locations (encoded as path strings) and concrete planet package versions. If a require line in the associated file requests a package, this table is consulted to determine a particular concrete package to satisfy the request.

See also build-scribble-docs? and force-package-building?

Defaults to #t, and thus packaging will signal errors.

The other two possible results indicate errors. If the result is a list, then the server is saying that there is no matching package; otherwise the error is some lower-level problem (perhaps no networking, etc.)

If the specified package already has a development link, this function first removes the old link and then adds the new one.

The pkg argument must end with the string ".plt".

The pkg argument must end with the string ".plt". The maj and min arguments must be integers. This procedure signals an error if no such link exists, unless #:quiet? is #true.

5.5 Package Version

Provides bindings for PLaneT developers that automatically produce references to the name and version of the containing PLaneT package so the same code may be reused across releases without accidentally referring to a different version of the same package.

this-package-version-symbol produces a symbol suitable for use in planet module paths. For instance, in version 1:0 of the package package.plt owned by author, (this-package-version-symbol dir/file) produces 'author/package:1:0/dir/file. In the same package, (this-package-version-symbol) produces 'author/package:1:0.

Note: Use this-package-in when documenting PLaneT packages with Scribble to associate each documented binding with the appropriate package.

5.6 Macros and Syntax Objects

Provides bindings useful for PLaneT-based macros.

5.7 Scribble Documentation

Provides bindings for documenting PLaneT packages.

The full module name passed to defmodule, etc is formed by appending the suffix-id or mod-suffix-id to the symbol returned by (this-package-version-symbol), separated by a / character, and tagging the resulting symbol as a planet module path. As a special case, if suffix-id is main, the suffix is omitted.

5.8 Terse Status Updates

This module provides access to some PLaneT status information. This module is first loaded by PLaneT in the initial namespace (when PLaneT’s resolver is loaded), but PLaneT uses dynamic-require to load this module each time it wants to announce information. Similarly, the state of which procedures are registered (via planet-terse-register) is saved in the namespace, making the listening and information producing namespace-specific.

Note that proc is called asynchronously (ie, on some thread other than the one calling planet-terse-register).

The table holding the key uses ephemerons and a weak hash table to ensure that when the key is unreachable, then the procedures passed to planet-terse-log cannot be reached through the table.

5.9 The Cache File’s Path