On this page:
generate-stripped-directory
fixup-local-redirect-reference
5.92

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:

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:

Any of the above removals can be suppressed through source-keep-files.

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

Any of the above removals can be suppressed through binary-keep-files.

Creating a binary package further adjusts the following files:

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

 (require pkg/strip) package: base
The pkg/strip module provides support for copying a package-style directory to a given destination with the same file/directory omissions and updates as raco pkg create.

procedure

(generate-stripped-directory mode    
  src-dir    
  dest-dir)  void?
  mode : (or/c 'source 'binary 'built)
  src-dir : path-string?
  dest-dir : path-string?
Copies src-dir to dest-dir with file/directory omissions and updates corresponding the creation of a source package, binary package, or built package as indicated by mode.

procedure

(fixup-local-redirect-reference file    
  js-path)  void?
  file : path-string?
  js-path : string?
Assuming that file is an HTML file for documentation, adjusts the URL reference to "local-redirect.js", if any, to use the prefix js-path.