5 Package-Building API🔗ℹ

The build-pkgs function drive a package build, but it relies on a set of VMs that are created by docker-vm or vbox-vm.

Additional configuration options:

• pkgs-for-version — The Racket version to use in queries to archived catalogs. This version should be consistent with snapshot-url.

• extra-packages — Extra packages to install within an installation so that they’re treated like packages that are included in the installer. These should be built packages (normally from the snapshot site), or else the generated built packages will not work right (especially when using multiple VMs).

• only-packages — When not #f, specifies a subset of packages available from pkg-catalogs to be built and recorded in a catalog. Any dependencies of a specified package are also included.

• only-sys+subpath — When not #f and when only-packages is not #f, considers only dependencies for the indicated specific platform. The platform is described by consing a symbol matching the result of (system-type) to a string matching the result of (system-library-subpath #f).

• compile-any? — When not #f, compiles bytecode in built packages to machine-independent form. The installer specified by installer-name or installer-platform-name and the packages provided by pkg-catalogs must also have machine-independent bytecode.

• steps — Steps to perform the package-build process. The possible steps, in order, are

  • 'download: download installer from snapshot site.

  • 'archive: archive catalogs byt downloading all packages to the work directory.

  • 'install: run the installer to set up each VM.

  • 'build: build packages that have changed.

  • 'docs: extract and assemble documentation.

  • 'summary: summarize the results as a web page.

  • 'site: assemble web-friendly pieces to an archive.

  You can skip steps at the beginning if you know that they’re already done, and you can skip tests at the end if you don’t want them, but any included steps must be contiguous and in order.

• timeout — Timeout in seconds for any one package or step.

• test-timeout — If not #f, supplied with --timeout to raco test to configure the default testing timeout.

• jobs — If not #f, supplied with --jobs to raco pkg install, raco setup, and/or raco test to configure the number of concurrent jobs that run.

• on-empty-pkg-updates — A thunk that is called in the case that no packages need to be rebuilt.

• install-doc-list-file — If not #f, save a list of files in the original installation’s "doc" directory to the specified file as part of the 'install step.

• run-tests? — Determines whether each package’s tests are run after building the package.

• built-at-site? — Determines whether to include a catalog of built packages in an assembled site.

• site-url — The URL where the assemble site will be made available (for, e.g., showing help about the catalog).

• site-starting-point — Text for help to describes the starting point, where #f means “the current release.”

• compress-site? — Selects whether the 'site step produces "site.tgz" (if true) or "site.tar" (otherwise).

• summary-omit-pkgs — A list of packages to omit from the build summary.

• max-build-together — Number of packages to build at once in a single VM. Building more than one package at a time can be faster, but it is not recommended: building multiple packages risks success when a build should have failed due to missing dependencies, and it risks corruption due to broken or nefarious packages.

• server-port — A TCP port to use for serving packages from the build machine to VirtualBox VMs. This server is not started if vms contains only Docker VMs.

The dir argument specifies a working directory within the Docker container; it must be a complete-path?, when viewed as a unix path, i.e., (complete-path? (bytes->path (string->bytes/utf-8 dir) 'unix)) must return #t.

The env argument specifies environment variable settings that prefix every command.

The shell argument determines the shell command that is used to run shell-command strings in the container.

The memory-mb and swap-mb arguments set memory-use constraints on the created container. The memory-mb value corresponds to “real” memory in megabytes, and swap-mb is additional swap space. If either is non-#f, the same value is used in place of a #f for the other. If both are #f, no specific limit is imposed.

The minimal-variant argument, if not #f, specifies a VM to try before this one. If installation fails with the minimal-variant VM, it is tried again with this one. Tests run in this VM, however, instead of minimal-variant.

The dir argument specifies a working directory within the virtual machine, with the same checks as docker-vm’s dir argument.

The env argument specifies environment variable settings that prefix every command.

The shell argument determines the shell command that is used to run shell-command strings in the virtual machine.

The init-snapshot string names a snapshot that exists as the starting point in the virtual machine, so that it can be reset to a state before any Racket installation. You must configure the virtual machine to have this snapshot.

The installed-snapshot string names a snapshot that will be created by build-pkgs after it installs Racket in the virtual machine. If a snapshot using this name already exists, it may be replaced.

The minimal-variant argument, if not #f, specifies a VM to try before this one. If installation fails with the minimal-variant VM, it is tried again with this one. Tests run in this VM, however, instead of minimal-variant.