config scribbling
svn: r8387
This commit is contained in:
Matthew Flatt
parent
3443acd61a
commit
75240e3b4c
124
collects/config/config.scrbl
Normal file
124
collects/config/config.scrbl
Normal file
|
|
@ -0,0 +1,124 @@
|
|||
#lang scribble/doc
|
||||
@(require scribble/manual
|
||||
(for-label scheme/base
|
||||
scheme/contract
|
||||
config/config))
|
||||
|
||||
@title{Installation and Search Path Configuration}
|
||||
|
||||
@section{Configuring Directories and Search Paths}
|
||||
|
||||
@defmodule[config/config]{
|
||||
|
||||
The @schememodname[config/config] library specifies the location of
|
||||
directories (such as the main documentation directory) and also
|
||||
directory search paths (such as a list of directories to search for
|
||||
documentation).}
|
||||
|
||||
|
||||
@bold{Note:} Instead of @scheme[require]ing
|
||||
@schememodname[config/config] directly, use the
|
||||
@schememodname[setup/dirs] library, which combines information from
|
||||
@schememodname[config/config] and other sources.
|
||||
|
||||
The @schememodname[config/config] module must export the following
|
||||
values. In all cases where a @scheme[delay]ed value is expected for an
|
||||
exported identifier, the value can be a @scheme[delay]ed @scheme[#f]
|
||||
to indicate the default.
|
||||
|
||||
@defthing[doc-dir (promise/c (or/c path? string? bytes? false/c))]{
|
||||
|
||||
A @scheme[delay]ed path, string, or byte string for the main
|
||||
documentation directory. It defaults to a @filepath{doc} sibling
|
||||
directory of the main collection directory.}
|
||||
|
||||
@defthing[lib-dir (promise/c (or/c path? string? bytes? false/c))]{
|
||||
|
||||
A @scheme[delay]ed path, string, or byte string for the main directory
|
||||
containing C libraries and build information; it defaults to a
|
||||
@filepath{lib} sibling directory of the main collection directory.}
|
||||
|
||||
@defthing[dll-dir (promise/c (or/c path? string? bytes? false/c))]{
|
||||
|
||||
A @scheme[delay]ed path, string, or byte string for a directory
|
||||
containing Unix shared libraries for the main executable; it defaults
|
||||
to the main C-library directory}
|
||||
|
||||
@defthing[include-dir (promise/c (or/c path? string? bytes? false/c))]{
|
||||
|
||||
A @scheme[delay]ed path, string, or byte string for the main directory
|
||||
containing C header files; it defaults to an @filepath{include}
|
||||
sibling directory of the main collection directory.}
|
||||
|
||||
@defthing[bin-dir (promise/c (or/c path? string? bytes? false/c))]{
|
||||
|
||||
A @scheme[delay]ed path, string, or byte string for the main directory
|
||||
containing executables; it defaults to a @filepath{bin} sibling
|
||||
directory of the main collection directory.}
|
||||
|
||||
@defthing[doc-search-dirs (promise/c (or/c path? string? bytes? false/c))]{
|
||||
|
||||
A @scheme[delay]ed path, string, byte string, or @scheme[#f]
|
||||
representing the search path for documentation; each @scheme[#f] in
|
||||
the list, if any, is replaced with the default search path, which is
|
||||
the user- and version-specific @filepath{doc} directory followed by
|
||||
the main documentation directory.}
|
||||
|
||||
@defthing[lib-search-dirs (promise/c (or/c path? string? bytes? false/c))]{
|
||||
|
||||
Like @scheme[doc-search-dirs], but for directories containing C
|
||||
libraries and other build information}
|
||||
|
||||
@defthing[include-search-dirs(promise/c (or/c path? string? bytes? false/c))]{
|
||||
|
||||
Like @scheme[doc-search-dirs], but for directories containing C header
|
||||
files}
|
||||
|
||||
@defthing[absolute-installation? boolean?]{
|
||||
|
||||
A (simple, non-@scheme[delay]ed) boolean that is @scheme[#t] if the
|
||||
installation uses absolute path names, @scheme[#f] otherwise.}
|
||||
|
||||
@defthing[cgc-suffix (promise/c (or/c string? false/c))]{
|
||||
|
||||
A string used as the suffix (before the actual suffix, such as
|
||||
@filepath{.exe}) for a @filepath{CGC} executable. Use Windows-style
|
||||
casing, and the string will be downcased as appropriate (e.g., for a
|
||||
Unix binary name). A @scheme[#f] value means that if the
|
||||
@exec{mzscheme} binary identifies itself as CGC, then the suffix is
|
||||
@scheme[""], otherwise it is @scheme["CGC"].}
|
||||
|
||||
@defthing[3m-suffix (promise/c (or/c string? false/c))]{
|
||||
|
||||
Analogous to @scheme[cgc-suffix], but for 3m. A @scheme[#f] value
|
||||
means that if the @filepath{mzscheme} binary identifies itself as CGC,
|
||||
then the suffix is @scheme["3m"], otherwise it is @scheme[""].}
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@section{Overriding the Installation's Configuration}
|
||||
|
||||
A user can override an installation's configuration through a
|
||||
@filepath{config} collection in the user's collection directory (which
|
||||
normally takes precedence over the main collection directory).
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@section{Configuration Language}
|
||||
|
||||
@defmodule[setup/configtab]{
|
||||
|
||||
The @schememodname[setup/configtab] library defines a language module
|
||||
that can be used to implement @schememodname[config/config].}
|
||||
|
||||
When @schememodname[setup/configtab] is used as a language module, the
|
||||
module body must consist of a sequence of
|
||||
|
||||
@schemeblock[(define _id _val)]
|
||||
|
||||
declarations, where each @scheme[_id] is one of the names that the
|
||||
@schememodname[config/config] library must export, and @scheme[_val] is
|
||||
an expression for the value (which will be automatically wrapped with
|
||||
@scheme[delay] when needed). If a required export has no corresponding
|
||||
@scheme[define], a definition with @scheme[#f] is inserted
|
||||
automatically.
|
||||
|
|
@ -1,80 +0,0 @@
|
|||
|
||||
Installation and Search Path Configuration
|
||||
------------------------------------------
|
||||
|
||||
The _config.ss_ library of the "config" collection specifies the
|
||||
location of directories (such as the main documentation directory) and
|
||||
also directory search paths (such as a list of directories to search
|
||||
for documentation).
|
||||
|
||||
Note: instead of `require'ing "config.ss" directly, use the "dirs.ss"
|
||||
library from "setup", which combines information from "config.ss" and
|
||||
other sources.
|
||||
|
||||
The "config.ss" module must export the following values:
|
||||
|
||||
doc-dir - a `delay'ed path/string/bytes for the main documentation
|
||||
directory; it defaults to a "doc" sibling directory of the main
|
||||
collection directory.
|
||||
|
||||
lib-dir - a `delay'ed path/string/bytes for the main directory
|
||||
containing C libraries and build information; it defaults to a
|
||||
"lib" sibling directory of the main collection directory.
|
||||
|
||||
dll-dir - a `delay'ed path/string/bytes for a directory containing
|
||||
Unix shared libraries for the main executable; it defaults to the
|
||||
main C-library directory
|
||||
|
||||
include-dir - a `delay'ed path/string/bytes for the main directory
|
||||
containing C header files; it defaults to an "include" sibling
|
||||
directory of the main collection directory.
|
||||
|
||||
bin-dir - a `delay'ed path/string/bytes for the main directory
|
||||
containing executables; it defaults to a "bin" sibling directory of
|
||||
the main collection directory.
|
||||
|
||||
doc-search-dirs - a `delay'ed list of paths/strings/bytes/#f
|
||||
representing the search path for documentation; each #f in the
|
||||
list, if any, is replaced with the default search path, which is
|
||||
the user- and version-specific "doc" directory followed by the main
|
||||
documentation directory.
|
||||
|
||||
lib-search-dirs - like `doc-search-dirs', but for directories
|
||||
containing C libraries and other build information
|
||||
|
||||
include-search-dirs - like `doc-search-dirs', but for directories
|
||||
containing C header files
|
||||
|
||||
absolute-installation? - a (simple, non-delayed) boolean that is
|
||||
true if this installation is using absolute path names
|
||||
|
||||
cgc-suffix - a string used as the suffix (before the actual suffix,
|
||||
such as ".exe") for a CGC executable; use Windows-style casing, and
|
||||
the string will be downcased as appropriate (e.g., for a Unix
|
||||
binary name); #f means that if the "mzscheme" binary identifies
|
||||
itself as CGC, then the suffix is "", otherwise it is "CGC"
|
||||
|
||||
3m-suffix - analogous to `cgc-suffix', but for 3m; #f means that
|
||||
if the "mzscheme" binary identifies itself as CGC, then the suffix
|
||||
is "3m", otherwise it is ""
|
||||
|
||||
In all cases, the value of an exported name can be a `delay'ed #f
|
||||
(instead of a path/string/bytes or list) to indicate the default.
|
||||
|
||||
A user can override an installation's "config.ss" though a "config"
|
||||
collection in the user's collection directory (which normally takes
|
||||
precedence over the main collection directory).
|
||||
|
||||
|
||||
The _configtab.ss_ library of the "setup" collection defines a
|
||||
language module that can be used to implement "config.ss" files. When
|
||||
_configtab.ss_ is used as a language module, the module body must
|
||||
consist of a sequence of
|
||||
|
||||
(define id val)
|
||||
|
||||
declarations, where each `id' is one of the names that the "config.ss"
|
||||
module must export, and `val' is an expression for the value (which
|
||||
will be automatically wrapped with `delay' when needed). If a required
|
||||
export has no corresponding `define', a definition with #f is inserted
|
||||
automatically.
|
||||
|
|
@ -1,3 +1,3 @@
|
|||
(module info setup/infotab
|
||||
(define name "Config")
|
||||
(define doc.txt "doc.txt"))
|
||||
(define scribblings '(("config.scrbl"))))
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user