4 Work Directory Content
The build-pkgs function needs a work directory where it will assemble packages and results. The generated content of the work directory can be used as a catalog of built packages plus web-friendly files that report build and test results.
If the work directory content persists across calls to build-pkgs, then build-pkgs will incrementally rebuild changed packages and other packages that depends on them. However, a work directory must be reused only when the configuration supplied to build-pkgs does not change.
The work directory will include the following files and directories, most of which are output, some of which record state for the purpose of incremental builds, and very few of which are treated as extra inputs:
"installer/" —
Holds an installer downloaded from a snapshot site. "install-uuids.rktd" —
Holds a mapping of VM names to IDs for prepared Docker containers or VirtualBox snapshots. "install-list.rktd" —
A list of packages found in the installation. "install-adds.rkt" —
A table of documentation, libraries, etc. in the installation, which is used to detect conflicts. "install-doc.tgz" —
A copy of installation’s documentation. "server/archive" —
Archived packages from the snapshot site plus additional specified catalogs. "state.sqlite" —
Records the state of "server/archive" for incremental updates. "all-pkgs.rktd" —
A list of available package at most recent build, which is used to avoid re-building packages that will fail again due to missing dependencies. "force-pkgs.rktd" —
A list of packages to force a rebuild; this file is an input, and it is deleted after it is used. "server/built" —
Built packages. For each package P, this directory contains one of the following: "pkgs/P.orig-CHECKSUM" (same as the checksum in the archived catalog), "pkgs/P.zip" (built package), and "pkgs/P.zip.CHECKSUM" (built package’s checksum) —
An up-to-date package that successfully built. Additional files:
"docs/P-adds.rktd" —
a listing of documentation, executables, etc. "success/P.txt" —
records success "install/P.txt" —
records installation "install/P.txt" —
records dependency-checking failure "test-success/P.txt" or "test-fail/P.txt" —
records raco test result possibly "min-fail/P.txt" —
records failure on minimal-host attempt
"pkgs/P.orig-CHECKSUM" (same as the checksum in the archived catalog) and "fail/P.txt" —
An up-to-date package that failed to build. An "install/P.txt" file may nevertheless report installation success in the sense that raco pkg install failed only in its raco setup step. "archive-fail/P.orig-CHECKSUM" —
Archiving failure.
"dumpster/" —
Saved builds of failed packages if the package at least installs (and failure was in the raco setup step), because maybe the attempt built some documentation. "doc/" —
Unpacked documentation with non-conflicting packages installed. "all-doc.tgz" —
The same content as "doc/", but still packed. "summary.rktd" —
A summary of build results as a hash table mapping each package name to another hash table with the following keys: 'success-log —
#f or relative path 'failure-log —
#f or relative path 'dep-failure-log —
#f or relative path 'test-success-log —
#f or relative path 'test-failure-log —
#f or relative path 'min-failure-log —
#f or relative path - 'docs —
a list of elements, each one of 'conflict-log —
#f, a relative path, or (list 'conflicts/indirect path)
"index.html" (and "robots.txt", etc.) —
A summary of results in web-page form. "site.tgz" or "site.tar" —
All files meant to populate a web site, including a "doc/" directory of documentation and a "server/built/catalog/" catalog of built packages that are in "server/built/pkgs/". The packed form "site.tgz" is created unless #:compress-site? is provided as #f.
Using this information, the build-pkgs rebuilds a package is if its checksum changes or if one of its declared dependencies changes.