From 75240e3b4c6a87130c7ad4c7725ce19349654463 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Wed, 23 Jan 2008 02:35:44 +0000 Subject: [PATCH] config scribbling svn: r8387 --- collects/config/config.scrbl | 124 +++++++++++++++++++++++++++++++++++ collects/config/doc.txt | 80 ---------------------- collects/config/info.ss | 2 +- 3 files changed, 125 insertions(+), 81 deletions(-) create mode 100644 collects/config/config.scrbl delete mode 100644 collects/config/doc.txt diff --git a/collects/config/config.scrbl b/collects/config/config.scrbl new file mode 100644 index 0000000000..c3a27bfa49 --- /dev/null +++ b/collects/config/config.scrbl @@ -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. diff --git a/collects/config/doc.txt b/collects/config/doc.txt deleted file mode 100644 index 572957e9b9..0000000000 --- a/collects/config/doc.txt +++ /dev/null @@ -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. diff --git a/collects/config/info.ss b/collects/config/info.ss index 783dff79fa..124e0ac80b 100644 --- a/collects/config/info.ss +++ b/collects/config/info.ss @@ -1,3 +1,3 @@ (module info setup/infotab (define name "Config") - (define doc.txt "doc.txt")) + (define scribblings '(("config.scrbl"))))