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 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.

A package is not specifically tagged as a source package, binary package, or built package. The different kinds of packages are 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.

Programmers normally supply only source packages, while a package catalog service may convert each source package to a binary package or built package. Alternatively, programmers can create binary packages or built packages by using the raco pkg create subcommand with --binary or --built. As a convenience, the raco pkg create subcommand can also create a source 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 at all.

Creating a source package, binary 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) or binary-keep-files (for binary package and built package bundling) definition in an "info.rkt" in the package or any subdirectory. A binary-keep-files or binary-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);

• 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; and

• 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, and any build-deps definition is removed.

Creating a built package removes any file or directory that would be removed for a source package and binary package, and it performs the ".html" file updating of a binary package.

Finally, creating built package or source 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).