suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix/expand/improve docs on "config.rktd"

Browse Source 
Merge to v6.0
This commit is contained in:
Matthew Flatt 2013-11-22 06:27:11 -07:00
parent 0f8ee73814
commit 8aa5f4a83a
1 changed files with 78 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

133
pkgs/racket-pkgs/racket-doc/scribblings/raco/config.scrbl
View File

@ -7,109 +7,115 @@
@title[#:tag "config-file"]{Installation Configuration and Search Paths} @title[#:tag "config-file"]{Installation Configuration and Search Paths}
A configuration-directory path is built into the Racket executable as A @deftech{configuration directory} path is built into the Racket executable as
selected at install time, or its location can be changed via the selected at install time, and its location can be changed via the
@envvar{PLTCONFIGDIR} directory or @DFlag{config}/@Flag{G} @envvar{PLTCONFIGDIR} directory or @DFlag{config}/@Flag{G}
command-line flag. Use @racket[find-config-dir] to locate the command-line flag. Use @racket[find-config-dir] to locate the
configuration directory. configuration directory.
Modify the @filepath{config.rktd} file as described below to configure Modify the @as-index{@filepath{config.rktd}} file in the @tech{configuration directory}
other directories, but use the @racketmodname[setup/dirs] library (which to configure other directories as described below. Use the
combines information from the configuration files and other sources) @racketmodname[setup/dirs] library (which combines information from
to locate configured directories. the configuration files and other sources) to locate configured
directories, instead of reading @filepath{config.rktd} directly.
A @as-index{@filepath{config.rktd}} file in the configuration directory should The path of the @deftech{main collection directory} is built into the
Racket executable, and it can be changed via the
@DFlag{collects}/@Flag{X} flag, so it has no entry in
@filepath{config.rktd}. Most paths that are specified in
@filepath{config.rktd} have default values that are relative to the
main collection directory. The paths of the @tech{configuration directory} and
@tech{main collection directory} thus work together to determine a
Racket configuration.
A @filepath{config.rktd} file in the configuration directory should
contain a @racket[read]able hash table with any of the following contain a @racket[read]able hash table with any of the following
symbolic keys, where an relative path is relative to the main collection symbolic keys, where a relative path is relative to the @tech{main collection
directory: directory}:
@itemlist[ @itemlist[
@item{@indexed-racket['doc-dir] --- a path, string, or byte string for the @item{@indexed-racket['installation-name] --- a string for the installation
main documentation directory. The value defaults to a name, which is used to determine user- and version-specific paths,
@filepath{doc} sibling directory of the such as the initial path produced by @racket[find-library-collection-paths]
main collection directory.} and the location of packages that are installed in @exec{user}
@tech[#:doc '(lib "pkg/scribblings/pkg.scrbl")]{package
scope}. The default is @racket[(version)].}
@item{@indexed-racket['lib-dir] --- a path, string, or byte string for the @item{@indexed-racket['lib-dir] --- a path, string, or byte string for the
main library directory; it defaults to a @filepath{lib} @deftech{main library directory}. It defaults to a @filepath{lib}
sibling directory of the main collection directory.} sibling directory of the @tech{main collection directory}.}
@item{@indexed-racket['lib-search-dirs] --- a list of paths, strings, byte @item{@indexed-racket['lib-search-dirs] --- a list of paths, strings, byte
strings, or @racket[#f] representing the search path for strings, or @racket[#f] representing the search path for
directories containing foreign libraries; each @racket[#f] in directories containing foreign libraries. Each @racket[#f] in
the list, if any, is replaced with the default search path, the list, if any, is replaced with the default search path,
which is the user- and version-specific @filepath{lib} which is the user- and version-specific @filepath{lib}
directory followed by the main library directory.} directory followed by the @tech{main library directory}.}
@item{@indexed-racket['dll-dir] --- a path, string, or byte string for a @item{@indexed-racket['dll-dir] --- a path, string, or byte string for a
directory containing shared libraries for the main directory containing shared libraries for the main
executable; it defaults to the main library directory.} executable. It defaults to the @tech{main library directory}.}
@item{@indexed-racket['share-dir] --- a path, string, or byte string for the @item{@indexed-racket['share-dir] --- a path, string, or byte string for the
main shared-file directory, which normally includes installed packages; @deftech{main shared-file directory}, which normally includes installed packages.
it defaults to a @filepath{share} sibling directory of the main It defaults to a @filepath{share} sibling directory of the main
collection directory.} collection directory.}
@item{@indexed-racket['links-file] --- a path, string, or byte string for the @item{@indexed-racket['links-file] --- a path, string, or byte string for the
@tech[#:doc reference-doc]{collection links file}; it defaults @tech[#:doc reference-doc]{collection links file}. It defaults
to a @filepath{links.rktd} file in the main shared-file directory.} to a @filepath{links.rktd} file in the @tech{main shared-file directory}.}
@item{@indexed-racket['links-search-files] --- like @racket['lib-search-dirs], @item{@indexed-racket['links-search-files] --- like @racket['lib-search-dirs],
but for @tech[#:doc reference-doc]{collection links file}.} but for @tech[#:doc reference-doc]{collection links file}.}
@item{@indexed-racket['pkgs-dir] --- a path, string, or byte string for @item{@indexed-racket['pkgs-dir] --- a path, string, or byte string
packages that have installation scope; it defaults to for packages that have @exec{installation} @tech[#:doc '(lib
"pkg/scribblings/pkg.scrbl")]{package scope}. It defaults to
@filepath{pkgs} in the main shared-file directory.} @filepath{pkgs} in the main shared-file directory.}
@item{@indexed-racket['pkgs-search-dirs] --- like @racket['lib-search-dirs], @item{@indexed-racket['pkgs-search-dirs] --- like
but for packages in installation scope.} @racket['lib-search-dirs], but for packages in @exec{installation}
@tech[#:doc '(lib "pkg/scribblings/pkg.scrbl")]{package
scope}.}
@item{@indexed-racket['bin-dir] --- a path, string, or byte string for the @item{@indexed-racket['bin-dir] --- a path, string, or byte string for the
installion's directory containing executables; it defaults to a installion's directory containing executables. It defaults to a
@filepath{bin} sibling directory of the main collection @filepath{bin} sibling directory of the @tech{main collection
directory.} directory}.}
@item{@indexed-racket['apps-dir] --- a path, string, or byte string @item{@indexed-racket['apps-dir] --- a path, string, or byte string
for the installation's directory for @filepath{.desktop} files; for the installation's directory for @filepath{.desktop} files.
it defaults to a @filepath{applications} subdirectory of the It defaults to a @filepath{applications} subdirectory of the
@racket['share-dir] directory.} @tech{main shared-file directory}.}
@item{@indexed-racket['man-dir] --- a path, string, or byte string for the @item{@indexed-racket['man-dir] --- a path, string, or byte string for the
installation's man-page directory; it defaults to a @filepath{man} installation's man-page directory. It defaults to a @filepath{man}
sibling directory of the main collection directory.} sibling directory of the @tech{main collection directory}.}
@item{@indexed-racket['man-dir] --- a path, string, or byte string for the @item{@indexed-racket['doc-dir] --- a path, string, or byte string for the
main man-page directory; it defaults to a @filepath{man} main documentation directory. The value defaults to a
sibling directory of the main collection directory.} @filepath{doc} sibling directory of the
@tech{main collection directory}.}
@item{@indexed-racket['doc-search-dirs] --- like @racket['lib-search-dirs], @item{@indexed-racket['doc-search-dirs] --- like @racket['lib-search-dirs],
but for directories containing documentation.} but for directories containing documentation.}
@item{@indexed-racket['include-dir] --- a 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.}
@item{@indexed-racket['include-search-dirs] --- like
@racket[doc-search-dirs], but for directories containing C
header files.}
@item{@indexed-racket['doc-search-url] --- a URL string that is augmented @item{@indexed-racket['doc-search-url] --- a URL string that is augmented
with version and search-tag queries to form a remote with version and search-tag queries to form a remote
documentation reference.} documentation reference.}
@item{@indexed-racket['installation-name] --- a string for the installation @item{@indexed-racket['include-dir] --- a path, string, or byte string for
name, which is used for packages in @exec{user} the main directory containing C header files. It defaults to an
@tech[#:doc '(lib "pkg/scribblings/pkg.scrbl")]{package @filepath{include} sibling directory of the @tech{main collection
scope}; the default is @racket[(version)].} directory}.}
@item{@indexed-racket['build-stamp] --- a string that identifies a build, @item{@indexed-racket['include-search-dirs] --- like
which can be used to augment the Racket version number to more @racket[doc-search-dirs], but for directories containing C
specifically identify the build. An empty string is normally header files.}
appropriate for a release build.}
@item{@indexed-racket['catalogs] --- a list of URL strings used as the search @item{@indexed-racket['catalogs] --- a list of URL strings used as the search
path for resolving package names; an @racket[#f] in the list path for resolving package names. An @racket[#f] in the list
is replaced with the default search path.} is replaced with the default search path.}
@item{@indexed-racket['default-scope] --- either @racket["user"] or @item{@indexed-racket['default-scope] --- either @racket["user"] or
@ -117,6 +123,23 @@ directory:
'(lib "pkg/scribblings/pkg.scrbl")]{package scope} for '(lib "pkg/scribblings/pkg.scrbl")]{package scope} for
package-management operations.} package-management operations.}
@item{@indexed-racket['download-cache-dir] --- a path string used as
the location for storing downloaded package archives. When not
specified, packages are cached in a @filepath{download-cache}
directory in the user's add-on directory as reported by
@racket[(find-system-path 'addon-dir)].}
@item{@indexed-racket['download-cache-max-files] and
@indexed-racket['download-cache-max-bytes] --- real numbers that
determine limits on the download cache. When not specified, the
cache is allowed to hold up to 1024 files that total up to
64@|~|MB.}
@item{@indexed-racket['build-stamp] --- a string that identifies a build,
which can be used to augment the Racket version number to more
specifically identify the build. An empty string is normally
appropriate for a release build.}
@item{@indexed-racket['absolute-installation?] --- a boolean that is @item{@indexed-racket['absolute-installation?] --- a boolean that is
@racket[#t] if the installation uses absolute path names, @racket[#t] if the installation uses absolute path names,
@racket[#f] otherwise.} @racket[#f] otherwise.}