672910f27b
I started from tabs that are not on the beginning of lines, and in several places I did further cleanings. If you're worried about knowing who wrote some code, for example, if you get to this commit in "git blame", then note that you can use the "-w" flag in many git commands to ignore whitespaces. For example, to see per-line authors, use "git blame -w <file>". Another example: to see the (*much* smaller) non-whitespace changes in this (or any other) commit, use "git log -p -w -1 <sha1>".
719 lines
30 KiB
Racket
719 lines
30 KiB
Racket
#lang scribble/manual
|
|
|
|
@(require
|
|
(for-label
|
|
racket/base
|
|
scribble/manual
|
|
planet/resolver
|
|
planet/config
|
|
planet/util
|
|
planet/version
|
|
planet/syntax
|
|
planet/scribble))
|
|
|
|
@title{Utility Libraries}
|
|
|
|
The planet collection provides configuration and utilities for using @|PLaneT|.
|
|
|
|
@section{Resolver}
|
|
|
|
@defmodule[planet/resolver]
|
|
|
|
The primary purpose of this library to for @racket[require] to find
|
|
@PLaneT packages. It also, however, provides some utilities for manipulating
|
|
the resolvers behavior.
|
|
|
|
@defproc*[(((planet-module-name-resolver [r-m-p resolved-module-path?])
|
|
void?)
|
|
((planet-module-name-resolver [spec (or/c module-path? path?)]
|
|
[module-path (or/c #f resolved-module-path?)]
|
|
[stx (or/c #f syntax?)]
|
|
[load boolean?]
|
|
[orig-paramz parameterization?])
|
|
resolved-module-path?))]{
|
|
This implements the @|PLaneT| module resolution process. It is @racket[dynamic-require]d
|
|
by racket when the first @|PLaneT| module require is needed. It acts much like a
|
|
@racket[current-module-name-resolver] would, but racket provides it with a special
|
|
@racket[parameterization?] (giving it special privileges) that it uses when installing new packages.
|
|
}
|
|
|
|
@defproc[(get-planet-module-path/pkg [spec (or/c module-path? path?)]
|
|
[module-path (or/c #f resolved-module-path?)]
|
|
[stx (or/c #f syntax?)])
|
|
(values path? pkg?)]{
|
|
Returns the path corresponding to the package (interpreting the arguments
|
|
the same way as @racket[planet-module-name-resolver] and @racket[(current-module-name-resolver)]).
|
|
}
|
|
|
|
@defproc[(resolve-planet-path [planet-path any/c]) path?]{
|
|
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.
|
|
|
|
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 @racketmodname[planet/util].
|
|
}
|
|
|
|
@defparam[download? dl? boolean?]{
|
|
A parameter that controls if @PLaneT attempts to download a package that isn't already present.
|
|
If the package isn't present, the resolver will raise the @racket[exn:fail:planet?] exception
|
|
instead of downloading it.
|
|
}
|
|
|
|
@defparam[install? inst? boolean?]{
|
|
A parameter that controls if @PLaneT attempts to install a package that isn't already installed.
|
|
If the package isn't installed, the resolver will raise the @racket[exn:fail:planet?] exception
|
|
instead of installing it.
|
|
}
|
|
|
|
@subsection{Resolver file locking}
|
|
|
|
When @|PLaneT| is asked to resolve a module path for loading the file
|
|
(e.g., when the last argument to the @racket[(current-module-name-resolver)]
|
|
is @racket[#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:
|
|
|
|
@centered{@filepath{@racket[(CACHE-DIR)]/dyoo/closure-compile.plt/1/2/}}
|
|
|
|
If the file
|
|
|
|
@centered{@filepath{@racket[(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 @filepath{2.SUCCESS} file is not there, then it attempts to grab an
|
|
@racket['exclusive] filesystem lock on this file (via @racket[port-try-file-lock?])
|
|
|
|
@centered{@filepath{@racket[(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 @filepath{2.UNPACKED} file:
|
|
|
|
@centered{@filepath{@racket[(CACHE-DIR)]/dyoo/closure-compile.plt/1/2.UNPACKED}}
|
|
|
|
When compilation and docs build are complete, it creates the @filepath{2.SUCCESS} file:
|
|
|
|
@centered{@filepath{@racket[(CACHE-DIR)]/dyoo/closure-compile.plt/1/2.SUCCESS}}
|
|
|
|
and releases the lock on the @filepath{2.LOCK} file.
|
|
|
|
If it fails to get the lock on @filepath{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 @racketmodname[planet/resolver]
|
|
module is instantiated) then it goes into a loop that polls for
|
|
the existence of the @filepath{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
|
|
@racketmodname[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 @racket[#f], or when
|
|
@racket[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
|
|
@filepath{2.UNPACKED} file instead of the @filepath{2.SUCCESS} file.
|
|
|
|
@section{Client Configuration}
|
|
|
|
@defmodule[planet/config]
|
|
|
|
The @racketmodname[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 @filepath{config.rkt} file.
|
|
|
|
@defparam[PLANET-BASE-DIR dir path-string?]{
|
|
The root of the tree where planet stores all of its files. Defaults to
|
|
@racketblock[(let ([plt-planet-dir-env-var (getenv "PLTPLANETDIR")])
|
|
(if plt-planet-dir-env-var
|
|
(string->path plt-planet-dir-env-var)
|
|
(build-path (find-system-path 'addon-dir)
|
|
"planet"
|
|
(PLANET-CODE-VERSION))))]
|
|
}
|
|
|
|
@defparam[PLANET-DIR dir path-string?]{
|
|
The root of the version-specific PLaneT files.
|
|
Defaults to @racket[(build-path (PLANET-BASE-DIR) (version))].
|
|
}
|
|
|
|
@defparam[CACHE-DIR dir path-string?]{
|
|
The root of the PLaneT client's cache directory.}
|
|
|
|
@defparam[UNINSTALLED-PACKAGE-CACHE 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.}
|
|
|
|
@defparam[LINKAGE-FILE 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 @filepath{LINKAGE}
|
|
in the root PLaneT directory.}
|
|
|
|
@defparam[LOG-FILE file (or/c path-string? false?)]{
|
|
If @racket[#f], indicates that no logging should take place. Otherwise
|
|
specifies the file into which logging should be written. The default
|
|
is the file @filepath{INSTALL-LOG} in the root PLaneT directory.}
|
|
|
|
@defboolparam[USE-HTTP-DOWNLOADS? bool]{
|
|
PLaneT can use two different protocols to retrieve packages. If @racket[#t],
|
|
PLaneT will use the HTTP protocol; if @racket[#f] it will use the custom-built
|
|
PLaneT protocol. The default value for this parameter is @racket[#t] and setting
|
|
this parameter to @racket[#f] is not recommended.}
|
|
|
|
@defparam[HTTP-DOWNLOAD-SERVLET-URL url string?]{
|
|
The URL for the servlet that will provide PLaneT packages if
|
|
@racket[USE-HTTP-DOWNLOADS?] is @racket[#t], represented as a string.
|
|
This defaults to the value of the @indexed-envvar{PLTPLANETURL} environment
|
|
variable if it is set and otherwise is
|
|
@racket["http://planet.racket-lang.org/servlets/planet-servlet.rkt"].}
|
|
|
|
@defparam[PLANET-SERVER-NAME host string?]{
|
|
The name of the PLaneT server to which the client should connect if
|
|
@racket[USE-HTTP-DOWNLOADS?] is @racket[#f]. The default value for this parameter is
|
|
@racket["planet.racket-lang.org"].}
|
|
|
|
@defparam[PLANET-SERVER-PORT port natural-number?]{
|
|
The port on the server the client should connect to if
|
|
@racket[USE-HTTP-DOWNLOADS?] is @racket[#f]. The default value for this parameter is
|
|
@racket[270].}
|
|
|
|
@defparam[HARD-LINK-FILE file path?]{
|
|
The name of the file where hard links are saved. Defaults to
|
|
@racket[(build-path (PLANET-BASE-DIR) (version) "HARD-LINKS")].
|
|
}
|
|
@defparam[PLANET-ARCHIVE-FILTER regexp-filter (or/c #f string? regexp?)]{
|
|
A regular-expression based filter that is used to skip files when building a @|PLaneT| archive.
|
|
}
|
|
@defparam[PLANET-CODE-VERSION vers string?]{
|
|
Used to compute @racket[PLANET-BASE-VERSION].
|
|
}
|
|
|
|
@defparam[DEFAULT-PACKAGE-LANGUAGE vers string?]{
|
|
The package language used when communicating with the server to find
|
|
which package to download.
|
|
|
|
Defaults to @racket[(version)].
|
|
}
|
|
|
|
@section{Package Archives}
|
|
|
|
@defmodule[planet/planet-archives]
|
|
|
|
@defproc[(get-all-planet-packages)
|
|
(listof (list/c (and/c path? absolute-path?) string? string? (listof string?)
|
|
exact-nonnegative-integer?
|
|
exact-nonnegative-integer?))]{
|
|
Returns the installed planet package. Each element of the result list corresponds to
|
|
a single package. The first element in an inner list is the location of the installed files.
|
|
The second and third elements are the owner and package names. The last two elements
|
|
are the major and minor verisons
|
|
}
|
|
|
|
@defproc[(get-installed-planet-archives)
|
|
(listof (list/c (and/c path? absolute-path?) string? string? (listof string?)
|
|
exact-nonnegative-integer?
|
|
exact-nonnegative-integer?))]{
|
|
Like @racket[get-all-planet-archives], except that it does not return packages linked in
|
|
with ``raco planet link''.
|
|
|
|
}
|
|
|
|
@defproc[(get-hard-linked-packages)
|
|
(listof (list/c (and/c path? absolute-path?) string? string? (listof string?)
|
|
exact-nonnegative-integer?
|
|
exact-nonnegative-integer?))]{
|
|
Like @racket[get-all-planet-archives], except that it return only packages linked in
|
|
with ``raco planet link''.
|
|
|
|
}
|
|
|
|
@section[#:tag "util.rkt"]{Package Utils}
|
|
|
|
@defmodule[planet/util]
|
|
|
|
The @racketmodname[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 @seclink["cmdline"]{the @exec{raco planet} command-line tool} is
|
|
also available programmatically through this library.
|
|
|
|
@defproc[(download/install-pkg [owner string?]
|
|
[pkg (and/c string? #rx"[.]plt$")]
|
|
[maj natural-number/c]
|
|
[min natural-number/c])
|
|
(or/c pkg? #f)]{
|
|
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 @racket[pkg] argument must end with @racket[".plt"].
|
|
}
|
|
|
|
@defproc[(install-pkg [pkg-spec pkg-spec?]
|
|
[file path-string?]
|
|
[maj natural-number/c]
|
|
[min natural-number/c])
|
|
(or/c pkg-spec? #f)]{
|
|
Installs the package represented by the arguments, using
|
|
the @racket[pkg-spec] argument to find the path and name of
|
|
the package to install.
|
|
|
|
See @racket[get-package-spec] to build a @racket[pkg-spec] argument.
|
|
|
|
Returns a new @racket[pkg-spec?] corresponding to the package
|
|
that was actually installed.
|
|
}
|
|
|
|
|
|
@defproc[(get-package-spec [owner string?]
|
|
[pkg (and/c string? #rx"[.]plt$")]
|
|
[maj (or/c #f natural-number/c) #f]
|
|
[min (or/c #f natural-number/c) #f])
|
|
pkg-spec?]{
|
|
Builds a @racket[pkg-spec?] corresponding to the package specified by
|
|
@racket[owner], @racket[pkg], @racket[maj], and @racket[min].
|
|
|
|
The @racket[pkg] argument must end with the string @racket[".plt"].
|
|
}
|
|
|
|
@defproc[(pkg-spec? [v any/c]) boolean?]{
|
|
Recognizes the result of @racket[get-package-spec] (and @racket[install-pkg]).
|
|
}
|
|
|
|
@defparam[current-cache-contents 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.}
|
|
|
|
@defproc[(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.}
|
|
|
|
@defproc[(make-planet-archive [directory path-string?]
|
|
[output-file (or/c path? path-string?)
|
|
(string-append (path->string name) ".plt")])
|
|
path-string?]{
|
|
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.
|
|
|
|
See also @racket[build-scribble-docs?] and @racket[force-package-building?]
|
|
}
|
|
|
|
@defparam[build-scribble-docs? b boolean?]{
|
|
Determines if @racket[make-planet-archive] builds scribble docs (or not).
|
|
}
|
|
|
|
@defparam[force-package-building? b boolean?]{
|
|
Determines if @racket[make-planet-archive] signals an error and refuses
|
|
to continue packaging for certain, more significant errors.
|
|
|
|
Defaults to @racket[#t], and thus packaging will signal errors.
|
|
}
|
|
|
|
@defproc[(download-package [pkg-spec pkg-spec?])
|
|
(or/c (list/c #true path? natural-number/c natural-number/c)
|
|
string?
|
|
(list/c #false string?))]{
|
|
Downloads the package given by @racket[pkg-spec]. If the result is
|
|
a list whose first element is @racket[#true], then the package was
|
|
downloaded successfully and the rest of the elements of the list
|
|
indicate where it was downloaded, and the precise version number.
|
|
|
|
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.)
|
|
}
|
|
|
|
@defproc[(pkg->download-url [pkg pkg?]) url?]{
|
|
Returns the url for a given package.
|
|
}
|
|
|
|
@defproc[(get-package-from-cache [pkg-spec pkg-spec?]) (or/c #false path?)]{
|
|
Returns the location of the already downloaded package,
|
|
if it exists (and @racket[#false] otherwise).
|
|
}
|
|
|
|
@defproc[(lookup-package-by-keys [owner string?]
|
|
[name string?]
|
|
[major exact-nonnegative-integer?]
|
|
[minor-lo exact-nonnegative-integer?]
|
|
[minor-hi exact-nonnegative-integer?])
|
|
(or/c (list/c path?
|
|
string?
|
|
string?
|
|
(listof string?)
|
|
exact-nonnegative-integer?
|
|
exact-nonnegative-integer?)
|
|
#false)]{
|
|
Looks up and returns a list representation of the package named by the given owner,
|
|
package name, major and (range of) minor version(s).
|
|
}
|
|
|
|
@defproc[(unpack-planet-archive [plt-file (or/c path? path-string?)]
|
|
[output-dir (or/c path? path-string?)])
|
|
any]{
|
|
Unpacks the PLaneT archive with the given filename, placing its contents
|
|
into the given directory (creating that path if necessary).}
|
|
|
|
@defproc[(remove-pkg [owner string?]
|
|
[pkg (and/c string? #rx"[.]plt$")]
|
|
[maj natural-number/c]
|
|
[min natural-number/c])
|
|
any]{
|
|
Removes the specified package from the local planet cache, deleting the installed files.
|
|
}
|
|
|
|
@defproc[(erase-pkg [owner string?]
|
|
[pkg (and/c string? #rx"[.]plt$")]
|
|
[maj natural-number/c]
|
|
[min natural-number/c])
|
|
any]{
|
|
Like @racket[remove-pkg], removes the specified package from the local planet cache and deletes
|
|
all of the files corresponding to the package, but also deletes the cached @filepath{.plt} file
|
|
(so it will be redownloaded later).
|
|
}
|
|
|
|
@defproc[(display-plt-file-structure [plt-file (or/c path-string? path?)])
|
|
any]{
|
|
Print a tree representing the file and directory structure of the
|
|
PLaneT archive .plt file named by @racket[plt-file] to @racket[(current-output-port)].}
|
|
|
|
@defproc[(display-plt-archived-file [plt-file (or/c path-string? path?)]
|
|
[file-to-print string?])
|
|
any]{
|
|
Print the contents of the file named @racket[file-to-print] within the
|
|
PLaneT archive .plt file named by @racket[plt-file] to @racket[(current-output-port)].}
|
|
|
|
@defproc[(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.}
|
|
|
|
@defproc[(add-hard-link [owner string?]
|
|
[pkg (and/c string? #rx"[.]plt$")]
|
|
[maj natural-number/c]
|
|
[min natural-number/c]
|
|
[dir path?])
|
|
any]{
|
|
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 @racket[pkg] argument must end with the string @racket[".plt"].
|
|
}
|
|
|
|
@defproc[(remove-hard-link [owner string?]
|
|
[pkg (and/c string? #rx"[.]plt$")]
|
|
[maj natural-number/c]
|
|
[min natural-number/c]
|
|
[#:quiet? quiet? boolean? #false])
|
|
any]{
|
|
Removes any hard link that may be associated with the given package.
|
|
|
|
The @racket[pkg] argument must end with the string @racket[".plt"].
|
|
The @racket[maj] and @racket[min] arguments must be integers. This
|
|
procedure signals an error if no such link exists, unless
|
|
@racket[#:quiet?] is @racket[#true].
|
|
}
|
|
|
|
@defproc[(resolve-planet-path [spec quoted-planet-require-spec?])
|
|
path?]{
|
|
This is the same function as the one with the same name,
|
|
exported by @racketmodname[planet/resolver].
|
|
}
|
|
|
|
@defproc[(path->package-version [p path?])
|
|
(or/c (list/c string? string? natural-number/c natural-number/c) #f)]{
|
|
|
|
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
|
|
@racket[(this-package-version)]. Given any other path, produces @racket[#f].
|
|
|
|
}
|
|
|
|
@defstruct[(exn:fail:planet exn:fail) ([message string?] [continuation-marks continuation-mark-set?])]{
|
|
This exception record is used to report planet-specific exceptions.
|
|
}
|
|
|
|
@defproc[(pkg? [v any/c]) boolean?]{
|
|
Determines if its argument is a pkg, the representation of an
|
|
installed package.
|
|
}
|
|
|
|
@section[#:tag "version.rkt"]{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.
|
|
|
|
@defmodule[planet/version #:use-sources (planet/private/version)]
|
|
|
|
@deftogether[(
|
|
@defform[(this-package-version)]
|
|
@defform*[[(this-package-version-symbol)
|
|
(this-package-version-symbol suffix-id)]]
|
|
@defform[(this-package-version-name)]
|
|
@defform[(this-package-version-owner)]
|
|
@defform[(this-package-version-maj)]
|
|
@defform[(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. @racket[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
|
|
@racket[#f] if the expression appears outside the context of a package.
|
|
The macros @racket[this-package-version-name],
|
|
@racket[this-package-version-owner], @racket[this-package-version-maj], and
|
|
@racket[this-package-version-min] produce the relevant fields of the package
|
|
version list.
|
|
|
|
@racket[this-package-version-symbol] produces a symbol
|
|
suitable for use in @racket[planet] module paths. For instance, in version
|
|
@racketmodfont{1:0} of the package @racketmodfont{package.plt} owned by
|
|
@racketmodfont{author}, @racket[(this-package-version-symbol dir/file)] produces
|
|
@racket['author/package:1:0/dir/file]. In the same package,
|
|
@racket[(this-package-version-symbol)] produces @racket['author/package:1:0].
|
|
|
|
}
|
|
|
|
@defform[(this-package-in suffix-id ...)]{
|
|
|
|
A @racket[require] sub-form that requires modules from within the same @|PLaneT|
|
|
package version as the require, as referred to by each @racket[suffix-id]. For
|
|
instance, in version @racketmodfont{1:0} of the package
|
|
@racketmodfont{package.plt} owned by @racketmodfont{author},
|
|
@racket[(require (this-package-in dir/file))] is equivalent to
|
|
@racket[(require (planet author/package:1:0/dir/file))].
|
|
|
|
@italic{Note:} Use @racket[this-package-in] when documenting @|PLaneT| packages
|
|
with Scribble to associate each documented binding with the appropriate package.
|
|
|
|
}
|
|
|
|
@defproc[(make-planet-symbol [stx syntax?]
|
|
[suffix (or/c #false string?) #false])
|
|
(or/c #false symbol?)]{
|
|
Returns a symbol representing a require spec for the location of @racket[stx],
|
|
as a planet package.
|
|
}
|
|
|
|
@defproc[(package-version->symbol [ver (or/c (list/c string? string? exact-nonnegative-integer? exact-nonnegative-integer?)
|
|
#false)]
|
|
[suffix (or/c #false string?) #false])
|
|
(or/c #false symbol?)]{
|
|
Returns a symbol representing the require spec for @racket[ver],
|
|
as a planet package.
|
|
}
|
|
|
|
@section[#:tag "syntax.rkt"]{Macros and Syntax Objects}
|
|
|
|
@defmodule[planet/syntax]
|
|
|
|
Provides bindings useful for @|PLaneT|-based macros.
|
|
|
|
@deftogether[(
|
|
@defproc[(syntax-source-planet-package [stx syntax?]) (or/c list? #f)]
|
|
@defproc[(syntax-source-planet-package-owner [stx syntax?]) (or/c string? #f)]
|
|
@defproc[(syntax-source-planet-package-name [stx syntax?]) (or/c string? #f)]
|
|
@defproc[(syntax-source-planet-package-major [stx syntax?]) (or/c integer? #f)]
|
|
@defproc[(syntax-source-planet-package-minor [stx syntax?]) (or/c integer? #f)]
|
|
@defproc[(syntax-source-planet-package-symbol
|
|
[stx syntax?]
|
|
[suffix (or/c symbol? #f) #f])
|
|
(or/c symbol? #f)]
|
|
)]{
|
|
|
|
Produce output analogous to @racket[this-package-version],
|
|
@racket[this-package-version-owner], @racket[this-package-version-name],
|
|
@racket[this-package-version-maj], @racket[this-package-version-min], and
|
|
@racket[this-package-version-symbol] based on the source location of
|
|
@racket[stx].
|
|
|
|
}
|
|
|
|
@defproc[(make-planet-require-spec
|
|
[stx syntax?]
|
|
[suffix (or/c symbol? #f) #f])
|
|
syntax?]{
|
|
|
|
Produces a @racket[require] sub-form for the module referred to by
|
|
@racket[suffix] in the @|PLaneT| package containing the source location of
|
|
@racket[stx].
|
|
|
|
}
|
|
|
|
@section[#:tag "scribble.rkt"]{Scribble Documentation}
|
|
|
|
@defmodule[planet/scribble]
|
|
|
|
Provides bindings for documenting @|PLaneT| packages.
|
|
|
|
@defform[(this-package-in suffix-id ...)]{
|
|
|
|
This binding from @racketmodname[planet/version] is also exported from
|
|
@racketmodname[planet/scribble], as it is useful for @racket[for-label] imports
|
|
in Scribble documentation.
|
|
|
|
}
|
|
|
|
@deftogether[(
|
|
@defform[(racketmod/this-package maybe-file suffix-id datum ...)]
|
|
@defform*[((racketmodname/this-package suffix-id)
|
|
(racketmodname/this-package (#,(racket unsyntax) suffix-expr)))]
|
|
@defform[(racketmodlink/this-package suffix-id pre-content-expr ...)]
|
|
@defform[(defmodule/this-package maybe-req suffix-id maybe-sources pre-flow ...)]
|
|
@defform*[((defmodulelang/this-package suffix-id maybe-sources pre-flow ...)
|
|
(defmodulelang/this-package suffix-id
|
|
#:module-paths (mod-suffix-id ...) maybe-sources
|
|
pre-flow ...))]
|
|
@defform[(defmodulereader/this-package suffix-id maybe-sources pre-flow ...)]
|
|
@defform[(defmodule*/this-package maybe-req (suffix-id ...+)
|
|
maybe-sources pre-flow ...)]
|
|
@defform*[((defmodulelang*/this-package (suffix-id ...+)
|
|
maybe-sources pre-flow ...)
|
|
(defmodulelang*/this-package (suffix-id ...+)
|
|
#:module-paths (mod-suffix-id ...) maybe-sources
|
|
pre-flow ...))]
|
|
@defform[(defmodulereader*/this-package (suffix-id ...+)
|
|
maybe-sources pre-flow ...)]
|
|
@defform[(defmodule*/no-declare/this-package maybe-req (suffix-id ...+)
|
|
maybe-sources pre-flow ...)]
|
|
@defform*[((defmodulelang*/no-declare/this-package (suffix-id ...+)
|
|
maybe-sources pre-flow ...)
|
|
(defmodulelang*/no-declare/this-package (suffix-id ...+)
|
|
#:module-paths (mod-suffix-id ...) maybe-sources pre-flow ...))]
|
|
@defform[(defmodulereader*/no-declare/this-package (suffix-id ...+)
|
|
maybe-sources pre-flow ...)]
|
|
@defform[(declare-exporting/this-package suffix-id ... maybe-sources)]
|
|
)]{
|
|
|
|
Variants of @racket[racketmod], @racket[racketmodname],
|
|
@racket[racketmodlink], @racket[defmodule], @racket[defmodulereader],
|
|
@racket[defmodulelang], @racket[defmodule*], @racket[defmodulelang*],
|
|
@racket[defmodulereader*], @racket[defmodule*/no-declare],
|
|
@racket[defmodulelang*/no-declare],
|
|
@racket[defmodulereader*/no-declare], and @racket[declare-exporting],
|
|
respectively, that implicitly refer to the PLaneT package that
|
|
contains the enclosing module.
|
|
|
|
The full module name passed to @racket[defmodule], etc is formed by
|
|
appending the @racket[suffix-id] or @racket[mod-suffix-id] to the
|
|
symbol returned by @racket[(this-package-version-symbol)], separated
|
|
by a @litchar{/} character, and tagging the resulting symbol as a
|
|
@racket[planet] module path. As a special case, if @racket[suffix-id]
|
|
is @racketid[main], the suffix is omitted.
|
|
|
|
For example, within a package named @tt{package.plt} by @tt{author},
|
|
version @tt{1:0}, the following are equivalent:
|
|
@racketblock[
|
|
(defmodule/this-package dir/file)
|
|
@#,elem{=} (defmodule (planet author/package:1:0/dir/file))
|
|
]
|
|
and
|
|
@racketblock[
|
|
(defmodule/this-package main)
|
|
@#,elem{=} (defmodule (planet author/package:1:0))
|
|
]
|
|
}
|
|
|
|
@section{Terse Status Updates}
|
|
|
|
@defmodule[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 @racket[dynamic-require] to load
|
|
this module each time it wants to announce information. Similarly, the
|
|
state of which procedures are registered (via @racket[planet-terse-register])
|
|
is saved in the namespace, making the listening and information producing
|
|
namespace-specific.
|
|
|
|
@defproc[(planet-terse-register
|
|
[proc (-> (or/c 'download 'install 'docs-build 'finish)
|
|
string?
|
|
any/c)])
|
|
void?]{
|
|
Registers @racket[proc] as a function to be called when
|
|
@racket[planet-terse-log] is called.
|
|
|
|
Note that @racket[proc] is called
|
|
asynchronously (ie, on some thread other than the one calling @racket[planet-terse-register]).
|
|
}
|
|
|
|
@defproc[(planet-terse-log [id (or/c 'download 'install 'finish)]
|
|
[msg string?]) void?]{
|
|
This function is called by PLaneT to announce when things are happening. See also
|
|
@racket[planet-terse-set-key].
|
|
}
|
|
|
|
@defproc[(planet-terse-set-key [key any/c]) void?]{
|
|
This sets a @seclink["threadcells" #:doc '(lib "scribblings/reference/reference.scrbl")]{thread cell}
|
|
to the value of @racket[key].
|
|
The value of the thread cell is used as an index into a table to determine which
|
|
of the functions passed to @racket[planet-terse-register] to call when
|
|
@racket[planet-terse-log] is called.
|
|
|
|
The table holding the key uses ephemerons and a weak hash table to ensure that
|
|
when the @racket[key] is unreachable, then the procedures passed to @racket[planet-terse-log]
|
|
cannot be reached through the table.
|
|
}
|
|
|
|
@section{The Cache File's Path}
|
|
|
|
@defmodule[planet/cachepath]
|
|
|
|
@defproc[(get-planet-cache-path) (and/c path? absolute-path?)]{
|
|
Returns the path to the @filepath{cache.rktd} file for the planet installation.
|
|
}
|