5 Source, Binary, and Built Packages

A package, especially in a repository format, normally provides module implementations and documentation in source form. Such source packages may work with multiple Racket versions, and modules are compiled to bytecode and documentation is rendered when the package is installed.

A binary package provides only compiled bytecode and rendered documentation, instead of package and documentation sources. Since compiled bytecode is specific to a version of Racket, a binary package is specific to a version of Racket. The benefit of a binary package is that it can have fewer dependencies (e.g., on Scribble to implement the documentation or on other packages whose documentation is referenced) and it can be installed faster. A drawback of a binary package is that it is version-specific and the source code may be less immediately accessible to other programmers.

A binary library package is like a binary package, but it further omits documentation.

A built package combines source and compiled elements. A built package can be installed more quickly than source, as long as it is installed for a suitable Racket version, but the source remains available as a back-up for other programmers to consult or to re-build for a different Racket version.

Programmers normally supply only source packages, while a package catalog service may convert each source package to a binary package, binary library package, or built package. Alternatively, programmers can create binary packages, binary library packages, or built packages by using the raco pkg create subcommand with --binary, --binary-lib, or --built. As a convenience, the raco pkg create subcommand can also create any kind of package from an installed package or repository checkout, dropping repository elements (such as a ".git" directory) and compiled code. Note that raco pkg create by default bundles a package directory as-is, with no filtering or annotation.

Although a package can be specifically annotated as a source package, binary package, binary library package, or built package (see package-content-state in Package Metadata), the different kinds of packages are primarily just conventions based on the content of the package. All forms of packages can be mixed in an installation, and a package can be updated from any form to any other form. Furthermore, raco pkg install and raco pkg update support --source, --binary, --binary-lib flags to convert to a package on installation; in that case, the package’s existing annotation is checked to verify that it is consistent with the requested conversion.

Creating a source package, binary package, binary library package, or built package from a directory or package installation prunes the following files and directories:

• directories/files named ".svn";

• directories/files whose names start with ".git";

• directories/files whose names end with "~"; and

• directories/files whose names start and end with "#".

Any of the above can be suppressed, however, by a source-keep-files (for source package and built package bundling), binary-keep-files (for binary package, binary library package and built package bundling), or binary-lib-keep-files (for binary library package bundling) definition in an "info.rkt" in the package or any subdirectory. A source-keep-files, binary-keep-files, or binary-lib-keep-files definition should bind the name to a list of paths relative to the "info.rkt" file.

Creating a source package prunes the following additional files and directories:

• directories/files named "compiled";

• directories/files named "doc";

• directories/files named "synced.rktd", which can appear as a marker in rendered documentation;

• directories/files named in an "info.rkt" file’s source-omit-files definition.

Any of the above removals can be suppressed through source-keep-files—even for files and directories within an otherwise removed directory.

Creating a binary package prunes the following additional files and directories:

• directories/files with names ending in ".rkt" or ".ss" for which a corresponding compiled bytecode file is present (in a "compiled" subdirectory), not counting "info.rkt";

• directories/files with names ending in ".scrbl", "_scrbl.zo", or ".dep";

• directories/files ending with ".css" or ".js" immediately within a directory named "doc";

• directories/files named "tests" or "scribblings" (but see the exception below for "doc" and "info.rkt");

• directories/files named in an "info.rkt" file’s binary-omit-files definition.

Any of the above removals can be suppressed through binary-keep-files—even files and directories within an otherwise removed directory. Furthermore, a "doc" or "info.rkt" directory/file is kept when it is within a "scribblings" directory and not within a "tests" directory. Creating a binary package further adjusts the following files (when they are not pruned):

• for any file whose name ends in ".zo", submodules named test, doc, or srcdoc are removed;

• for each ".html" file that refers to a "local-redirect.js" script, the path to the script is removed;

• each "info.rkt" is adjusted as follows: an assume-virtual-sources definition is added, any copy-foreign-libs definition is changed to move-foreign-libs, any copy-shared-files definition is changed to move-shared-files, any copy-man-pages definition is changed to move-man-pages, any build-deps definition is removed, any update-implies definition is removed, and a package-content-state is added to changed to (list 'binary (version)); and

• each collection within the path gets an "info.rkt" if it did not have one already, so that assume-virtual-sources can be defined.

Creating a binary library package prunes the following additional files and directories and makes additional adjustments compared to a binary package:

• directories/files named "doc" are removed;

• directories/files named in an "info.rkt" file’s binary-lib-omit-files definition are removed; and

• each "info.rkt" is adjusted to remove any scribblings definition, and package-content-state is adjusted to (list 'binary-lib (version)).

Any of the removals can be suppressed through binary-lib-keep-files, in addition to suppressions through binary-keep-files.

Creating a built package removes any file or directory that would be removed for a source package and binary package, it performs the ".html" file updating of a binary package, and the package’s "info.rkt" file (added if it does not exist already) is adjusted to define package-content-state as (list 'built (version)).

Finally, creating a binary package, binary library package, or built package “unmoves” files that were installed via move-foreign-libs, move-shared-files, or move-man-pages definitions in an "info.rkt" file, retrieving them if they are not present at referenced location but are present in a user-specific target directory (i.e., the directory reported by find-user-lib-dir, find-user-share-dir, or find-user-man-dir, respectively). On Mac OS X, when an unmoved file for move-foreign-libs is a Mach-O file that includes a reference to another library in one of the directories reported by (get-lib-search-dirs), then the reference is changed to a @loader_path/ reference. On Unix, when an unmoved file for move-foreign-libs is an ELF file whose RPATH configuration is $ORIGIN: followed by the path to the main installation’s library directory as reported by (find-lib-dir), then its RPATH value is set to $ORIGIN.