6.3 Controlling raco setup with "info.rkt" Files
To compile a collection’s files to bytecode, raco setup uses the compile-collection-zos procedure. That procedure, in turn, consults the collection’s "info.rkt" file, if it exists, for specific instructions on compiling the collection. See compile-collection-zos for more information on the fields of "info.rkt" that it uses, and see "info.rkt" File Format for information on the format of an "info.rkt" file.
Additional fields are used by the Racket package manager and are documented in Package Metadata. The raco test command also recognizes additional fields, which are documented in Test Configuration by "info.rkt".
Optional "info.rkt" fields trigger additional actions by raco setup:
scribblings : (listof (cons/c string? list?)) —
A list of documents to build. Each document in the list is itself represented as a list, where each document’s list starts with a string that is a collection-relative path to the document’s source file. A document name (which is derived from the source module’s name by default) is intended to be globally unique in the same way as a package or module name. More precisely a scribblings entry must be a value that can be generated from an expression matching the following entry grammar:
entry = (list doc ...) doc = (list src-string) | (list src-string flags) | (list src-string flags category) | (list src-string flags category name) | (list src-string flags category name out-k) | (list src-string flags category name out-k order-n) flags = (list mode-symbol ...) category = (list category-string-or-symbol) | (list category-string-or-symbol sort-number) name = string | #f A document’s list optionally continues with information on how to build the document. If a document’s list contains a second item, flags, it must be a list of mode symbols (described below). If a document’s list contains a third item, category, it must be a list that categorizes the document (described further below). If a document’s list contains a fourth item, name, it is a name to use for the generated documentation, instead of defaulting to the source file’s name (sans extension), where #f means to use the default; a non-#f value for name must fit the grammar of a collection-name element as checked by collection-name-element?. If a document’s list contains a fifth item, out-k, it is used a hint for the number of files to use for the document’s cross-reference information; see below. If a document’s list contains a fourth item, order-n, it is used a hint for the order of rendering; see below.
Each mode symbol in flags can be one of the following, where only 'multi-page is commonly used:
'multi-page : Generates multi-page HTML output, instead of the default single-page format.
'main-doc : Indicates that the generated documentation should be written into the main installation directory, instead of to a user-specific directory. This mode is the default for a collection that is itself located in the main installation.
'user-doc : Indicates that the generated documentation should be written a user-specific directory. This mode is the default for a collection that is not itself located in the main installation.
'depends-all : Indicates that the document should be re-built if any other document is rebuilt—
except for documents that have the 'no-depend-on flag. 'depends-all-main : Indicates that the document should be re-built if any other document is rebuilt that is installed into the main installation—
except for documents that have the 'no-depend-on flag. 'depends-all-user : Indicates that the document should be re-built if any other document is rebuilt that is installed into the user’s space—
except for documents that have the 'no-depend-on flag. 'always-run : Build the document every time that raco setup is run, even if none of its dependencies change.
'no-depend-on : Removes the document for consideration for other dependencies. Furthermore, references from the document to other documents are always direct, instead of potentially indirect (i.e., resolved at document-viewing time and potentially redirected to a remote site).
'main-doc-root : Designates the root document for the main installation. The document that currently has this mode should be the only one with the mode.
'user-doc-root : Designates the root document for the user-specific documentation directory. The document that currently has this mode should be the only one with the mode.
'keep-style : Leave the document’s style as-is, instead of imposing the document style for manuals.
'no-search : Build the document without a search box.
The category list specifies how to show the document in the root table of contents. The list must start with a category, which determines where the manual appears in the root documentation page. A category is either a string or a symbol. If it is a string, then the string is the category label on the root page. If it is a symbol, then a default category label is used. The available symbols and the order of categories on the root documentation page is as below:
'getting-started : High-level, introductory documentation, typeset at the same level as other category titles.
'language : Documentation for a prominent programming language.
'tool : Documentation for an executable.
'gui-library : Documentation for GUI and graphics libraries.
'net-library : Documentation for networking libraries.
'parsing-library : Documentation for parsing libraries.
'tool-library : Documentation for programming-tool libraries (i.e., not important enough for the more prominent 'tool category).
'interop : Documentation for interoperability tools and libraries.
All string categories as ordered by string<=?.
'library : Documentation for libraries; this category is the default and used for unrecognized category symbols.
'legacy : Documentation for deprecated libraries, languages, and tools.
'experimental : Documentation for an experimental language or library.
'other : Other documentation.
'omit : Documentation that should not be listed on the root page or indexed for searching.
'omit-start : Documentation that should not be listed on the root page but should be indexed for searching.
If the category list has a second element, it must be a real number that designates the manual’s sorting position with the category; manuals with the same sorting position are ordered alphabetically. For a pair of manuals with sorting numbers n and m, the groups for the manuals are separated by space if (truncate (/ n 10))and (truncate (/ m 10)) are different.
The out-k specification is a hint on whether to break the document’s cross-reference information into multiple parts, which can reduce the time and memory use for resolving a cross-reference into the document. It must be a positive, exact integer, and the default is 1.
The order-n specification is a hint for ordering document builds, since documentation references can be mutually recursive. The order hint can be any real number. A value of -10 or less disables running the document in parallel to other documents. The main Racket reference is given a value of -11, the search page is given a value of 10, and the default is 0.
A directory for pre-rendered documentation is computed from the source file name by starting with the directory of the "info.rkt" file, adding "doc", and then using the document name (which is usually the source file’s name without a suffix); if such a directory exists and does not have a "synced.rktd" file, then it is treated as pre-rendered documentation and moved into place, in which case the documentation source file need not be present. Moving documentation into place may require no movement at all, depending on the way that the enclosing collection is installed, but movement includes adding a "synced.rktd" file to represent the installation.
Changed in version 6.4: Allow a category to be a string instead of a symbol.
release-note-files : (listof (cons/c string? (cons/c string? list?))) —
A list of release-notes text files to link from the main documentation pages. Each note is itself represented as a list, and the list can specify auxiliary notes that are grouped with the main note. A release-note-files entry must be a value that can be generated from an expression matching the following entry grammar:
entry = (list note ...) doc = (list label-string note-path) | (list label-string note-path order-integer) | (list label-string note-path order-integer (list sub-note ...)) sub-note = (list label-string note-path) The order-integer is used to order notes and defaults to 0.
racket-launcher-names : (listof string?) —
A list of executable names to be generated in the installation’s executable directory to run Racket-based programs implemented by the collection. A parallel list of library names must be provided by racket-launcher-libraries or racket-launcher-flags. For each name, a launching executable is set up using make-racket-launcher. The arguments are -l- and ‹colls›/.../‹file›, where ‹file› is the file named by racket-launcher-libraries and ‹colls›/... are the collections (and subcollections) of the "info.rkt" file.
In addition,
(build-aux-from-path (build-path (collection-path ‹colls› ...) ‹suffixless-file›)) is provided for the optional aux argument (for icons, etc.) to make-racket-launcher, where ‹suffixless-file› is ‹file› without its suffix.
If racket-launcher-flags is provided, it is used as a list of command-line arguments passed to racket instead of the above default, allowing arbitrary command-line arguments. If racket-launcher-flags is specified together with racket-launcher-libraries, then the flags will override the libraries, but the libraries can still be used to specify a name for build-aux-from-path (to find related information like icon files etc).
racket-launcher-libraries : (listof path-string?) —
A list of library names in parallel to racket-launcher-names. racket-launcher-flags : (listof string?) —
A list of command-line flag lists, in parallel to racket-launcher-names. mzscheme-launcher-names, mzscheme-launcher-libraries, and mzscheme-launcher-flags —
Backward-compatible variant of racket-launcher-names, etc. gracket-launcher-names : (listof string?) —
Like racket-launcher-names, but for GRacket-based executables. The launcher-name list is treated in parallel to gracket-launcher-libraries and gracket-launcher-flags. gracket-launcher-libraries : (listof path-string?) —
A list of library names in parallel to gracket-launcher-names. gracket-launcher-flags : (listof string?) —
A list of command-line flag lists, in parallel to gracket-launcher-names. mred-launcher-names, mred-launcher-libraries, and mred-launcher-flags —
Backward-compatible variant of gracket-launcher-names, etc. copy-foreign-libs : (listof (and/c path-string? relative-path?)) —
Files to copy into a directory where foreign libraries are found by ffi-lib. If install-platform is defined, then the files are copied only if the current platform matches the definition. On Mac OS X, when a Mach-O file is copied, if the copied file includes a library reference that starts @loader_path/, and if the referenced library exists in a different location among the paths listed by (get-lib-search-dirs), then the library reference is updated to an absolute path.
On Unix, when an ELF file is copied, if the copied file includes an RPATH setting of $ORIGIN and the file is being installed to a user-specific location, then the file’s RPATH is adjusted to $ORIGIN: followed by the path to the main installation’s library directory as reported by (find-lib-dir).
On Windows, deleting a previously installed foreign library may be complicated by a lock on the file, if it is in use. To compensate, raco setup deletes a foreign-library file by first renaming the file to have the prefix "raco-setup-delete-"; it then attempts to delete the renamed file and merely issues a warning on a failure to delete the renamed file. Meanwhile, in modes where raco setup removes uninstalled libraries, it attempts to delete any file in the foreign-library directory whose name starts with "raco-setup-delete-" (in an attempt to clean up after previous failures).
move-foreign-libs : (listof (and/c path-string? relative-path?)) —
Like copy-foreign-libs, but the original file is removed after it is copied (which makes sense for precompiled packages). copy-shared-files : (listof (and/c path-string? relative-path?)) —
Files to copy into a directory where shared files are found. If install-platform is defined, then the files are copied only if the current platform matches the definition. On Windows, uninstalled files are deleted in the same way as for copy-foreign-libs, and the name prefix "raco-setup-delete-" is similarly special.
move-shared-files : (listof (and/c path-string? relative-path?)) —
Like copy-shared-files, but the original file is removed after it is copied (which makes sense for precompiled packages). copy-man-pages : (listof (and/c path-string? relative-path? filename-extension)) —
Files to copy into a man directory. The file suffix determines its category; for example, .1 should be used for a man page describing an executable. On Windows, uninstalled files are deleted in the same way as for copy-foreign-libs, and the name prefix "raco-setup-delete-" is similarly special.
move-man-pages : (listof (and/c path-string? relative-path? filename-extension)) —
Like copy-man-pages, but the original file is removed after it is copied (which makes sense for precompiled packages). install-platform : platform-spec? —
Determines whether files are copied or moved for copy-foreign-libs, move-foreign-libs, copy-shared-files, or move-shared-files. See matching-platform? for information on the way that the specification is compared to (system-type) and (system-library-subpath #f). install-collection : path-string? —
A library module relative to the collection that provides installer. The installer procedure accepts one to three arguments. The first argument is a directory path to the parent of the Racket installation’s "collects" directory; the second argument, if accepted, is a path to the collection’s own directory; the third argument, if accepted, is a boolean indicating whether the collection is installed as user-specific (#t) or installation-wide (#f). The procedure should perform collection-specific installation work, and it should avoid unnecessary work in the case that it is called multiple times for the same installation. pre-install-collection : path-string? —
Like install-collection, except that the corresponding installer is called before the normal ".zo" build, instead of after. The provided procedure should be named pre-installer in this case, so it can be provided by the same file that provides an installer. post-install-collection : path-string? —
Like install-collection. It is called right after the install-collection procedure is executed. The only difference between these is that the --no-install flag can be used to disable the previous two installers, but not this one. It is therefore expected to perform operations that are always needed, even after an installation that contains pre-compiled files. The provided procedure should be named post-installer in this case, so it can be provided by the same file that provides the previous two. assume-virtual-sources : any/c —
A true value indicates that bytecode files without a corresponding source file should not be removed from "compiled" directories, and no files should not be removed when the --clean or -c flag is passed to raco setup. clean : (listof path-string?) —
A list of pathnames to be deleted when the --clean or -c flag is passed to raco setup. The pathnames must be relative to the collection. If any path names a directory, each of the files in the directory are deleted, but none of the subdirectories of the directory are checked. If the path names a file, the file is deleted. The default, if this flag is not specified, is to delete all files in the "compiled" subdirectory, and all of the files in the platform-specific subdirectory of the compiled directory for the current platform. Just as compiling ".zo" files will compile each module used by a compiled module, deleting a module’s compiled image will delete the ".zo" of each module that is used by the module. More specifically, used modules are determined when deleting a ".dep" file, which would have been created to accompany a ".zo" file when the ".zo" was built by raco setup or raco make (see Dependency Files). If the ".dep" file indicates another module, that module’s ".zo" is deleted only if it also has an accompanying ".dep" file. In that case, the ".dep" file is deleted, and additional used modules are deleted based on the used module’s ".dep" file, etc. Supplying a specific list of collections to raco setup disables this dependency-based deletion of compiled files.
compile-omit-paths, compile-omit-files, and compile-include-files —
Used indirectly via compile-collection-zos. module-suffixes and doc-module-suffixes —
Used indirectly via get-module-suffixes.