From 8aa5f4a83a85237e82f67850cc60ed6fb4fa382c Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Fri, 22 Nov 2013 06:27:11 -0700 Subject: [PATCH] fix/expand/improve docs on "config.rktd" Merge to v6.0 --- .../racket-doc/scribblings/raco/config.scrbl | 133 ++++++++++-------- 1 file changed, 78 insertions(+), 55 deletions(-) diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/raco/config.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/raco/config.scrbl index 35c57dd16a..f2d49c1c25 100644 --- a/pkgs/racket-pkgs/racket-doc/scribblings/raco/config.scrbl +++ b/pkgs/racket-pkgs/racket-doc/scribblings/raco/config.scrbl @@ -7,109 +7,115 @@ @title[#:tag "config-file"]{Installation Configuration and Search Paths} -A configuration-directory path is built into the Racket executable as -selected at install time, or its location can be changed via the +A @deftech{configuration directory} path is built into the Racket executable as +selected at install time, and its location can be changed via the @envvar{PLTCONFIGDIR} directory or @DFlag{config}/@Flag{G} command-line flag. Use @racket[find-config-dir] to locate the configuration directory. -Modify the @filepath{config.rktd} file as described below to configure -other directories, but use the @racketmodname[setup/dirs] library (which -combines information from the configuration files and other sources) -to locate configured directories. +Modify the @as-index{@filepath{config.rktd}} file in the @tech{configuration directory} +to configure other directories as described below. Use the +@racketmodname[setup/dirs] library (which combines information from +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 -symbolic keys, where an relative path is relative to the main collection -directory: +symbolic keys, where a relative path is relative to the @tech{main collection +directory}: @itemlist[ - @item{@indexed-racket['doc-dir] --- a path, string, or byte string for the - main documentation directory. The value defaults to a - @filepath{doc} sibling directory of the - main collection directory.} + @item{@indexed-racket['installation-name] --- a string for the installation + name, which is used to determine user- and version-specific paths, + such as the initial path produced by @racket[find-library-collection-paths] + 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 - main library directory; it defaults to a @filepath{lib} - sibling directory of the main collection directory.} + @deftech{main library directory}. It defaults to a @filepath{lib} + sibling directory of the @tech{main collection directory}.} @item{@indexed-racket['lib-search-dirs] --- a list of paths, strings, byte 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, 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 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 - main shared-file directory, which normally includes installed packages; - it defaults to a @filepath{share} sibling directory of the main + @deftech{main shared-file directory}, which normally includes installed packages. + It defaults to a @filepath{share} sibling directory of the main collection directory.} @item{@indexed-racket['links-file] --- a path, string, or byte string for the - @tech[#:doc reference-doc]{collection links file}; it defaults - to a @filepath{links.rktd} file in the main shared-file directory.} + @tech[#:doc reference-doc]{collection links file}. It defaults + to a @filepath{links.rktd} file in the @tech{main shared-file directory}.} @item{@indexed-racket['links-search-files] --- like @racket['lib-search-dirs], but for @tech[#:doc reference-doc]{collection links file}.} - @item{@indexed-racket['pkgs-dir] --- a path, string, or byte string for - packages that have installation scope; it defaults to + @item{@indexed-racket['pkgs-dir] --- a path, string, or byte string + 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.} - @item{@indexed-racket['pkgs-search-dirs] --- like @racket['lib-search-dirs], - but for packages in installation scope.} + @item{@indexed-racket['pkgs-search-dirs] --- like + @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 - installion's directory containing executables; it defaults to a - @filepath{bin} sibling directory of the main collection - directory.} + installion's directory containing executables. It defaults to a + @filepath{bin} sibling directory of the @tech{main collection + directory}.} @item{@indexed-racket['apps-dir] --- a path, string, or byte string - for the installation's directory for @filepath{.desktop} files; - it defaults to a @filepath{applications} subdirectory of the - @racket['share-dir] directory.} + for the installation's directory for @filepath{.desktop} files. + It defaults to a @filepath{applications} subdirectory of the + @tech{main shared-file directory}.} @item{@indexed-racket['man-dir] --- a path, string, or byte string for the - installation's man-page directory; it defaults to a @filepath{man} - sibling directory of the main collection directory.} + installation's man-page directory. It defaults to a @filepath{man} + sibling directory of the @tech{main collection directory}.} - @item{@indexed-racket['man-dir] --- a path, string, or byte string for the - main man-page directory; it defaults to a @filepath{man} - sibling directory of the main collection directory.} + @item{@indexed-racket['doc-dir] --- a path, string, or byte string for the + main documentation directory. The value defaults to a + @filepath{doc} sibling directory of the + @tech{main collection directory}.} @item{@indexed-racket['doc-search-dirs] --- like @racket['lib-search-dirs], 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 with version and search-tag queries to form a remote documentation reference.} - @item{@indexed-racket['installation-name] --- a string for the installation - name, which is used for packages in @exec{user} - @tech[#:doc '(lib "pkg/scribblings/pkg.scrbl")]{package - scope}; the default is @racket[(version)].} + @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 @tech{main collection + directory}.} - @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['include-search-dirs] --- like + @racket[doc-search-dirs], but for directories containing C + header files.} @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.} @item{@indexed-racket['default-scope] --- either @racket["user"] or @@ -117,6 +123,23 @@ directory: '(lib "pkg/scribblings/pkg.scrbl")]{package scope} for 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 @racket[#t] if the installation uses absolute path names, @racket[#f] otherwise.}