On this page:
generate-stripped-directory
check-strip-compatible
fixup-local-redirect-reference
strip-binary-compile-info
8.4.0.3

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:

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:

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

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

Any of the above removals can be suppressed through binary-keep-fileseven 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):

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

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

 (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 'binary-lib 'built)
  src-dir : path-string?
  dest-dir : path-string?
Copies src-dir to dest-dir with file/directory omissions and updates corresponding to the creation of a source package, binary package, binary library package, or built package as indicated by mode. The given src-dir and dest-dir must both exist already. If src-dir and dest-dir are the same, then src-dir is modified directly, which may involve deleting files.

Note that generate-stripped-directory does not compile or render source files found in the src-dir. To perform precompilation or rendering before stripping the source directory, use raco setup or raco make.

Changed in version 7.2.0.10 of package base: Added support for src-dir and dest-dir as the same path.

procedure

(check-strip-compatible mode    
  pkg-name    
  dir    
  error)  any
  mode : (or/c 'source 'binary 'binary-lib 'built)
  pkg-name : string?
  dir : path-string?
  error : (string? . -> . any)
Check whether the content of dir is consistent with the given mode conversion according to the content of a "info.rkt" file in dir. If not, error is called with an error-message string to describe the mismatch.

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.

parameter

(strip-binary-compile-info)  boolean?

(strip-binary-compile-info compile?)  void?
  compile? : any/c
A parameter that determines whether "info.rkt" files are included in bytecode form when converting package content for a binary packages, binary library packages, and built packages.