710320e3dc
Although "macOS" is the correct name for Apple's current desktop OS, we've decided to go with "Mac OS" to cover all of Apple's Unix-like desktop OS versions. The label "Mac OS" is more readable, clear in context (i.e., unlikely to be confused with the Mac OSes that proceeded Mac OS X), and as likely to match Apple's future OS names as anything.
256 lines
11 KiB
Racket
256 lines
11 KiB
Racket
#lang scribble/manual
|
|
@(require "common.rkt"
|
|
(for-label pkg/strip
|
|
setup/dirs))
|
|
|
|
@title[#:tag "strip"]{Source, Binary, and Built Packages}
|
|
|
|
A package, especially in a repository format, normally provides module
|
|
implementations and documentation in source form. Such @deftech{source
|
|
packages} may work with multiple Racket versions, and modules are
|
|
compiled to bytecode and documentation is rendered when the package is
|
|
installed.
|
|
|
|
A @deftech{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
|
|
@tech{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 @deftech{binary library package} is like a @tech{binary package},
|
|
but it further omits documentation.
|
|
|
|
A @deftech{built package} combines source and compiled elements. A
|
|
@tech{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 @tech{source packages}, while a
|
|
package catalog service may convert each source package to a
|
|
@tech{binary package}, @tech{binary library package}, or @tech{built package}. Alternatively,
|
|
programmers can create @tech{binary packages}, @tech{binary library packages}, or @tech{built packages}
|
|
by using the @command-ref{create} subcommand with @DFlag{binary}, @DFlag{binary-lib}, or
|
|
@DFlag{built}. As a convenience, the @command-ref{create} subcommand
|
|
can also create any kind of package from an installed package or
|
|
repository checkout, dropping repository elements (such as a
|
|
@filepath{.git} directory) and compiled code. Note that
|
|
@command-ref{create} by default bundles a package directory as-is,
|
|
with no filtering or annotation.
|
|
|
|
Although a package can be specifically annotated as a @tech{source package},
|
|
@tech{binary package}, @tech{binary library package}, or @tech{built
|
|
package} (see @racketidfont{package-content-state} in @secref["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,
|
|
@exec{raco pkg install} and @exec{raco pkg update} support
|
|
@DFlag{source}, @DFlag{binary}, @DFlag{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 @tech{source package}, @tech{binary package}, @tech{binary library package}, or
|
|
@tech{built package} from a directory or package installation prunes
|
|
the following files and directories:
|
|
|
|
@itemlist[
|
|
|
|
@item{directories/files named @filepath{.svn};}
|
|
|
|
@item{directories/files whose names start with @filepath{.git};}
|
|
|
|
@item{directories/files whose names end with @filepath{~}; and}
|
|
|
|
@item{directories/files whose names start and end with @filepath{#}.}
|
|
|
|
]
|
|
|
|
Any of the above can be suppressed, however, by a
|
|
@racket[source-keep-files] (for @tech{source package} and @tech{built
|
|
package} bundling), @racket[binary-keep-files] (for @tech{binary
|
|
package}, @tech{binary library package} and @tech{built package} bundling),
|
|
or @racket[binary-lib-keep-files] (for @tech{binary library package} bundling) definition in an
|
|
@filepath{info.rkt} in the package or any subdirectory. A
|
|
@racket[source-keep-files], @racket[binary-keep-files], or @racket[binary-lib-keep-files] definition
|
|
should bind the name to a list of paths relative to the
|
|
@filepath{info.rkt} file.
|
|
|
|
Creating a @tech{source package} prunes the following additional files
|
|
and directories:
|
|
|
|
@itemlist[
|
|
|
|
@item{directories/files named @filepath{compiled};}
|
|
|
|
@item{directories/files named @filepath{doc};}
|
|
|
|
@item{directories/files named @filepath{synced.rktd}, which can appear
|
|
as a marker in rendered documentation;}
|
|
|
|
@item{directories/files named in an @filepath{info.rkt} file's
|
|
@racket[source-omit-files] definition.}
|
|
|
|
]
|
|
|
|
Any of the above removals can be suppressed through
|
|
@racketidfont{source-keep-files}---even for files and directories
|
|
within an otherwise removed directory.
|
|
|
|
Creating a @tech{binary package} prunes the following additional files
|
|
and directories:
|
|
|
|
@itemlist[
|
|
|
|
@item{directories/files with names ending in @filepath{.rkt} or
|
|
@filepath{.ss} for which a corresponding compiled bytecode file
|
|
is present (in a @filepath{compiled} subdirectory), not
|
|
counting @filepath{info.rkt};}
|
|
|
|
@item{directories/files with names ending in @filepath{.scrbl},
|
|
@filepath{_scrbl.zo}, or @filepath{.dep};}
|
|
|
|
@item{directories/files ending with @filepath{.css} or @filepath{.js}
|
|
immediately within a directory named @filepath{doc};}
|
|
|
|
@item{directories/files named @filepath{tests} or
|
|
@filepath{scribblings} (but see the exception below for
|
|
@filepath{doc} and @filepath{info.rkt});}
|
|
|
|
@item{directories/files named in an @filepath{info.rkt} file's
|
|
@racket[binary-omit-files] definition.}
|
|
|
|
]
|
|
|
|
Any of the above removals can be suppressed through
|
|
@racketidfont{binary-keep-files}---even files and directories within
|
|
an otherwise removed directory. Furthermore, a @filepath{doc} or
|
|
@filepath{info.rkt} directory/file is kept when it is within a
|
|
@filepath{scribblings} directory and not within a @filepath{tests}
|
|
directory. Creating a @tech{binary package} further adjusts the
|
|
following files (when they are not pruned):
|
|
|
|
@itemlist[
|
|
|
|
@item{for any file whose name ends in @filepath{.zo}, submodules
|
|
named @racketidfont{test}, @racketidfont{doc}, or
|
|
@racketidfont{srcdoc} are removed;}
|
|
|
|
@item{for each @filepath{.html} file that refers to a
|
|
@filepath{local-redirect.js} script, the path to the script is
|
|
removed;}
|
|
|
|
@item{each @filepath{info.rkt} is adjusted as follows: an
|
|
@racket[assume-virtual-sources] definition is added, any
|
|
@racket[copy-foreign-libs] definition is changed to
|
|
@racket[move-foreign-libs], any
|
|
@racket[copy-shared-files] definition is changed to
|
|
@racket[move-shared-files], any @racket[copy-man-pages]
|
|
definition is changed to @racket[move-man-pages], any
|
|
@racket[build-deps] definition is removed, any
|
|
@racket[update-implies] definition is removed, and
|
|
a @racket[package-content-state] is added to changed to
|
|
@racket[(list 'binary (version))]; and}
|
|
|
|
@item{each collection within the path gets an @filepath{info.rkt} if
|
|
it did not have one already, so that
|
|
@racket[assume-virtual-sources] can be defined.}
|
|
|
|
]
|
|
|
|
Creating a @tech{binary library package} prunes the following
|
|
additional files and directories and makes additional adjustments
|
|
compared to a @tech{binary package}:
|
|
|
|
@itemlist[
|
|
|
|
@item{directories/files named @filepath{doc} are removed;}
|
|
|
|
@item{directories/files named in an @filepath{info.rkt} file's
|
|
@racket[binary-lib-omit-files] definition are removed; and}
|
|
|
|
@item{each @filepath{info.rkt} is adjusted to remove any
|
|
@racket[scribblings] definition, and
|
|
@racket[package-content-state] is adjusted to @racket[(list
|
|
'binary-lib (version))].}
|
|
|
|
]
|
|
|
|
Any of the removals can be suppressed through
|
|
@racketidfont{binary-lib-keep-files}, in addition to suppressions
|
|
through @racketidfont{binary-keep-files}.
|
|
|
|
Creating a @tech{built package} removes any file or directory that
|
|
would be removed for a @tech{source package} @emph{and} @tech{binary
|
|
package}, it performs the @filepath{.html} file updating of a
|
|
@tech{binary package}, and the package's @filepath{info.rkt} file
|
|
(added if it does not exist already) is adjusted to define
|
|
@racket[package-content-state] as @racket[(list 'built (version))].
|
|
|
|
Finally, creating a @tech{binary package}, @tech{binary library
|
|
package}, or @tech{built package} ``unmoves'' files that were
|
|
installed via @racket[move-foreign-libs], @racket[move-shared-files],
|
|
or @racket[move-man-pages] definitions in an @filepath{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 @racket[find-user-lib-dir], @racket[find-user-share-dir],
|
|
or @racket[find-user-man-dir], respectively). On Mac OS, when an
|
|
unmoved file for @racket[move-foreign-libs] is a Mach-O file that
|
|
includes a reference to another library in one of the directories reported by
|
|
@racket[(get-lib-search-dirs)], then the reference is changed to a
|
|
@litchar{@"@"loader_path/} reference. On Unix, when an
|
|
unmoved file for @racket[move-foreign-libs] is an ELF file whose
|
|
RPATH configuration is @litchar{$ORIGIN:} followed by the path
|
|
to the main installation's library directory as reported by
|
|
@racket[(find-lib-dir)], then its RPATH value is set to @litchar{$ORIGIN}.
|
|
|
|
@defmodule[pkg/strip]{The @racketmodname[pkg/strip] module provides
|
|
support for copying a package-style directory to a given destination
|
|
with the same file/directory omissions and updates as
|
|
@command-ref{create}.}
|
|
|
|
@defproc[(generate-stripped-directory [mode (or/c 'source 'binary 'binary-lib 'built)]
|
|
[src-dir path-string?]
|
|
[dest-dir path-string?])
|
|
void?]{
|
|
|
|
Copies @racket[src-dir] to @racket[dest-dir] with file/directory
|
|
omissions and updates corresponding the creation of a @tech{source
|
|
package}, @tech{binary package}, @tech{binary library package}, or @tech{built package} as indicated
|
|
by @racket[mode].}
|
|
|
|
|
|
@defproc[(check-strip-compatible [mode (or/c 'source 'binary 'binary-lib 'built)]
|
|
[pkg-name string?]
|
|
[dir path-string?]
|
|
[error (string? . -> . any)])
|
|
any]{
|
|
|
|
Check whether the content of @racket[dir] is consistent with the given
|
|
@racket[mode] conversion according to the content of a
|
|
@filepath{info.rkt} file in @racket[dir]. If not, @racket[error] is
|
|
called with an error-message string to describe the mismatch.}
|
|
|
|
|
|
@defproc[(fixup-local-redirect-reference [file path-string?]
|
|
[js-path string?])
|
|
void?]{
|
|
|
|
Assuming that @racket[file] is an HTML file for documentation, adjusts
|
|
the URL reference to @filepath{local-redirect.js}, if any, to use the
|
|
prefix @racket[js-path].}
|
|
|
|
|
|
@defboolparam[strip-binary-compile-info compile?]{
|
|
|
|
A parameter that determines whether @filepath{info.rkt} files are
|
|
included in bytecode form when converting package content for a
|
|
@tech{binary packages}, @tech{binary library packages}, and
|
|
@tech{built packages}.}
|
|
|