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.
Returns the path where the file named by the require spec planet-path is located in the current installation.
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.
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
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.
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.
The root of the PLaneT client’s cache directory.
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.
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.
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.
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.
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".
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".
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 Package Archive
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.
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.
The pkg argument must end with ".plt".
Installs the package represented by the arguments, using
the pkg-spec argument to find the path and name of
the package to install.
See get-package-spec to build a pkg-spec argument.
Returns a new pkg-spec? corresponding to the package
that was actually installed.
Builds a
pkg-spec? corresponding to the package specified by
owner,
pkg,
maj, and
min.
The pkg argument must end with the string ".plt".
Holds a listing of all package names and versions installed in the
local cache.
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.
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.
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 : (and/c string? #rx"[.]plt") |
| maj : natural-number/c |
| min : natural-number/c |
Removes the specified package from the local planet cache.
The pkg argument must end with the string ".plt".
Print a tree representing the file and directory structure of the
PLaneT archive .plt file named by
plt-file to
(current-output-port).
Print the contents of the file named
file-to-print within the
PLaneT archive .plt file named by
plt-file to
(current-output-port).
Removes the entire linkage table from the system, which will force all
modules to relink themselves to PLaneT modules the next time they run.
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.
The pkg argument must end with the string ".plt".
|
| owner : string? |
| pkg : (and/c string? #rx"[.]plt") |
| maj : natural-number/c |
| min : natural-number/c |
| quiet? : boolean? = #false |
Removes any hard link that may be associated with the given package.
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 #t.
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.
Aliases of the same bindings from
planet/version for backward
compatibility.
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.
Returns #t if val is an exception indicating a planet-specific failure.
5.4 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.
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 macros
this-package-version-name,
this-package-version-owner,
this-package-version-maj, and
this-package-version-min produce the relevant fields of the package
version list.
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.
A
require sub-form that requires modules from within the same
PLaneT
package version as the require, as referred to by each
suffix-id. For
instance, in version
1:0 of the package
package.plt owned by
author,
(require (this-package-in dir/file)) is equivalent to
(require (planet author/package:1:0/dir/file)).
Note: Use this-package-in when documenting PLaneT packages
with Scribble to associate each documented binding with the appropriate package.
5.5 Macros and Syntax Objects
Provides bindings useful for PLaneT-based macros.
Produces a
require sub-form for the module referred to by
suffix in the
PLaneT package containing the source location of
stx.
5.6 Scribble Documentation
Provides bindings for documenting PLaneT packages.
Variants of
racketmod,
racketmodname,
racketmodlink,
defmodule,
defmodulereader,
defmodulelang,
defmodule*,
defmodulelang*,
defmodulereader*,
defmodule*/no-declare,
defmodulelang*/no-declare,
defmodulereader*/no-declare, and
declare-exporting,
respectively, that implicitly refer to the PLaneT package that
contains the enclosing module.
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.
For example, within a package named package.plt by author,
version 1:0, the following are equivalent:
and
5.7 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.
| (planet-terse-register proc) → void? |
| | proc | | : | | | (-> (or/c 'download 'install 'docs-build 'finish) | | string? | | any/c) |
|
|
Registers proc as a function to be called when
planet-terse-log is called.
Note that proc is called
asynchronously (ie, on some thread other than the one calling planet-terse-register).
| (planet-terse-log id msg) → void? |
| id : (or/c 'download 'install 'finish) |
| msg : string? |
This function is called by PLaneT to announce when things are happening. See also
planet-terse-set-key.
| (planet-terse-set-key key) → void? |
| key : any/c |
This sets a
thread cell
to the value of
key.
The value of the thread cell is used as an index into a table to determine which
of the functions passed to
planet-terse-register to call when
planet-terse-log is called.
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.