5 Utility Libraries

▼ |  | PLane T: Automatic Package Distribution

1 | Using PLane T
2 | The PLane T Search Order
3 | The raco planet Command-Line Tool
4 | The planet Language
5 | Utility Libraries
6 | Developing Packages for PLane T

► | 5 | Utility Libraries

5.1 | Resolver
5.2 | Client Configuration
5.3 | Utilities
5.4 | Terse Status Updates

On this page:

5.1`` Resolver
resolve-planet-path
download?
install?
5.2`` Client Configuration
PLANET-DIR
CACHE-DIR
UNINSTALLED-PACKAGE-CACHE
LINKAGE-FILE
LOG-FILE
USE-HTTP-DOWNLOADS?
HTTP-DOWNLOAD-SERVLET-URL
PLANET-SERVER-NAME
PLANET-SERVER-PORT
5.3`` Utilities
download/ install-pkg
install-pkg
get-package-spec
pkg-spec?
current-cache-contents
current-linkage
make-planet-archive
unpack-planet-archive
remove-pkg
display-plt-file-structure
display-plt-archived-file
unlink-all
add-hard-link
remove-hard-link
resolve-planet-path
this-package-version
this-package-version-name
this-package-version-owner
this-package-version-maj
this-package-version-min
path->package-version
exn: fail: planet?
5.4`` Terse Status Updates
planet-terse-register
planet-terse-log

top← prev up next →

### 5`` Utility Libraries

The planet collection provides configuration and utilities for using PLaneT.

#### 5.1`` Resolver

( require planet/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.

( resolve-planet-path planet-path) → path?
planet-path : any/c

Returns the path where the file named by the require spec planet-path is located in the current installation.

(download?) → boolean?
(download? dl?) → void?
dl? : boolean?

A parameter that controls if PLaneT attempts to download a planet package that isn’t already present. If the package isn’t present, the resolver will raise the exn:fail:planet? exception instead of downloading it.

(install?) → boolean?
(install? inst?) → void?
inst? : boolean?

A parameter that controls if PLaneT attempts to install a planet package that isn’t already installed. If the package isn’t installed, the resolver will raise the exn:fail:planet? exception instead of installing it.

#### 5.2`` Client Configuration

( require planet/config)

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.

( PLANET-DIR) → path-string?
( PLANET-DIR dir) → void?
dir : path-string?

The root PLaneT directory. If the environment variable PLTPLANETDIR is set, default is its value; otherwise the default is the directory in which "config.rkt" is found.

( CACHE-DIR) → path-string?
( CACHE-DIR dir) → void?
dir : path-string?

The root of the PLaneT client’s cache directory.

( UNINSTALLED-PACKAGE-CACHE) → path-string?
( UNINSTALLED-PACKAGE-CACHE dir) → void?
dir : path-string?

The root of the PLaneT client’s uninstalled-packages cache. PLaneT stores package distribution files in this directory, and searches for them in this directory for them if necessary. Unlike the main PLaneT cache, which contains compiled files and is specific to each particular version of Racket, the uninstalled package cache is shared by all versions of Racket that use the same package repository, and it is searched if a package is not installed in the primary cache and cannot be downloaded from the central PLaneT repository (for instance due to a loss of Internet connectivity). This behavior is intended to primarily benefit users who upgrade their Racket installations frequently.

( LINKAGE-FILE) → path-string?
( LINKAGE-FILE file) → void?
file : path-string?

The file to use as the first place PLaneT looks to determine how a particular PLaneT dependence in a file should be satisfied. The contents of this file are used to ensure that no "magic upgrades" occur after a package is installed. The default is the file "LINKAGE" in the root PLaneT directory.

( LOG-FILE) → ( or/c path-string? false?)
( LOG-FILE file) → void?
file : ( or/c path-string? false?)

If #f, indicates that no logging should take place. Otherwise specifies the file into which logging should be written. The default is the file "INSTALL-LOG" in the root PLaneT directory.

( USE-HTTP-DOWNLOADS?) → boolean?
( USE-HTTP-DOWNLOADS? bool) → void?
bool : any/c

PLaneT can use two different protocols to retrieve packages. If #t, PLaneT will use the HTTP protocol; if #f it will use the custom-built PLaneT protocol. The default value for this parameter is #t and setting this parameter to #f is not recommended.

( HTTP-DOWNLOAD-SERVLET-URL) → string?
( HTTP-DOWNLOAD-SERVLET-URL url) → void?
url : string?

The URL for the servlet that will provide PLaneT packages if USE-HTTP-DOWNLOADS? is #t, represented as a string. This defaults to the value of the PLTPLANETURL environment variable if it is set and otherwise is "http://planet.racket-lang.org/servlets/planet-servlet.rkt".

( PLANET-SERVER-NAME) → string?
( PLANET-SERVER-NAME host) → void?
host : string?

The name of the PLaneT server to which the client should connect if USE-HTTP-DOWNLOADS? is #f. The default value for this parameter is "planet.racket-lang.org".

( PLANET-SERVER-PORT) → natural-number?
( PLANET-SERVER-PORT port) → void?
port : natural-number?

The port on the server the client should connect to if USE-HTTP-DOWNLOADS? is #f. The default value for this parameter is 270.

#### 5.3`` Utilities

( require planet/util)

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.

( download/install-pkg owner pkg maj min) → ( or/c pkg? #f)
owner : string?
pkg : string?
maj : natural-number/c
min : natural-number/c

Downloads and installs the package specifed by the given owner name, package name, major and minor version number. Returns false if no such package is available; otherwise returns a package structure for the installed package.

( install-pkg pkg file maj min) → ( or/c pkg? #f)
pkg : pkg-spec?
file : path-string?
maj : natural-number/c
min : natural-number/c

Installs the package represented by the arguments, using only the pkg-spec-path and pkg-spec-name fields of pkg.

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

( get-package-spec owner pkg [maj min]) → pkg-spec?
owner : string?
pkg : string?
maj : ( or/c #f natural-number/c) = #f
min : ( or/c #f natural-number/c) = #f

Builds a pkg-spec? corresponding to the package specified by owner, pkg, maj, and min.

( pkg-spec? v) → boolean?
v : any/c

Recognizes the result of get-package-spec.

( current-cache-contents)

→

( listof
( list/c string?
( listof
( list/c string?
( cons/c natural-number/c
( listof natural-number/c))))))

( current-cache-contents contents) → void?

contents

:

( listof
( list/c string?
( listof
( list/c string?
( cons/c natural-number/c
( listof natural-number/c))))))

Holds a listing of all package names and versions installed in the local cache.

( current-linkage)

→

( listof ( list/c path-string?
( list/c string?
( list/c string?)
natural-number/c
natural-number/c)))

Returns the current linkage table.

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.

( make-planet-archive directory [output-file]) → path-string?
directory : path-string?

| output-file |  | : |  | ( or/c path? path-string?)
|  |  | = |  | ( string-append ( path->string name) ".plt")

Makes a .plt archive file suitable for PLaneT whose contents are all files in the given directory and returns that file’s name. If the optional filename argument is provided, that filename will be used as the output file’s name.

( unpack-planet-archive plt-file output-dir) → any
plt-file : ( or/c path? path-string?)
output-dir : ( or/c path? path-string?)

Unpacks the PLaneT archive with the given filename, placing its contents into the given directory (creating that path if necessary).

( remove-pkg owner pkg maj min) → any
owner : string?
pkg : string?
maj : natural-number/c
min : natural-number/c

Removes the specified package from the local planet cache.

( display-plt-file-structure plt-file) → any
plt-file : ( or/c path-string? path?)

Print a tree representing the file and directory structure of the PLaneT archive .plt file named by plt-file to ( current-output-port).

( display-plt-archived-file |  | plt-file |  |  |  |
|  | file-to-print) |  | → |  | any

plt-file : ( or/c path-string? path?)
file-to-print : string?

Print the contents of the file named file-to-print within the PLaneT archive .plt file named by plt-file to ( current-output-port).

( unlink-all) → any

Removes the entire linkage table from the system, which will force all modules to relink themselves to PLaneT modules the next time they run.

( add-hard-link owner pkg maj min dir) → any
owner : string?
pkg : string?
maj : natural-number/c
min : natural-number/c
dir : path?

Adds a development link between the specified package and the given directory; once a link is established, PLaneT will treat the cache as having a package with the given owner, name, and version whose files are located in the given path. This is intended for package development; users only interested in using PLaneT packages available online should not need to create any development links.

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

( remove-hard-link owner pkg maj min) → any
owner : string?
pkg : string?
maj : natural-number/c
min : natural-number/c

Removes any hard link that may be associated with the given package.

( resolve-planet-path spec) → path?
spec : quoted-planet-require-spec?

Returns the file system path to the file specified by the given quoted planet require specification. This function downloads and installs the specified package if necessary, but does not verify that the actual file within it actually exists.

( this-package-version)

( this-package-version-name)

( this-package-version-owner)

( this-package-version-maj)

( this-package-version-min)

Macros that expand into expressions that evaluate to information about the name, owner, and version number of the package in which they appear. this-package-version returns a list consisting of a string naming the package’s owner, a string naming the package, a number indicating the package major version and a number indicating the package minor version, or #f if the expression appears outside the context of a package. The others are convenience macros that select out the relevant field, or return #f if the expression appears outside the context of a PLaneT package.

( path->package-version p)
→ ( or/c ( list/c string? string? natural-number/c natural-number/c) #f)
p : path?

Given a path that corresponds to a PLaneT package (or some part of one), produces a list corresponding to its name and version, exactly like ( this-package-version). Given any other path, produces #f.

( exn:fail:planet? val) → boolean?
val : any/c

Returns #t if val is

#### 5.4`` Terse Status Updates

( require planet/terse-info)

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.

(planet-terse-register proc [namespace]) → void?
proc : (-> ( or/c 'download 'install 'docs-build 'finish) string? any/c)
namespace : namespace? = ( current-namespace)

Registers proc as a function to be called when planet-terse-log is called with a matching namespace argument. Note that proc is called asynchronously (ie, on some thread other than the one calling planet-terse-register).

(planet-terse-log id msg [namespace]) → void?
id : ( or/c 'download 'install 'finish)
msg : string?
namespace : namespace? = ( current-namespace)

This function is called by PLaneT to announce when things are happening. The namespace passed along is used to identify the procs to notify.
top← prev up next →