7 Main Distribution via Docker🔗ℹ

The distro-build/main-distribution library provides functions for generating a site configuration that builds distributions like those available at the main Racket download site.

The configuration assumes a x86_64 (64-bit Intel) or AArch64 (64-bit Arm) host that can run Docker containers. See make-spliceable-limits for information on expected resource usage.

The minimal? argument indicates whether the configuration is intended as a Minimal Racket distribution. It determines the default for many other arguments. If minimal? is true, then pkgs must be an empty list.

To fully imitate the main download site, make-machines should be called twice, once with minimal? as true and once with minimal? as false, normally in that order. Results from multiple calls must be combined with sequential, not parallel, because containers are reused to reduce unnecessary rebuilds. When using #:clean?, a good strategy is to wrap the result of make-machine with minimal? as true also with #:clean? as true, and not the result of make-machine with minimal? as #false; see also extract-container-names. Supply mac-sign-cert-config, mac-notarization-config, and recompile-cache arguments consistently, and beware that changing those arguments may require removing old containers.

The pkgs argument determines packages that are pre-installed in the distribution. It must be a subset of the packages that are listed for #:pkgs in the top-level site configuration.

The filter-rx argument, when not #f, determines which installers are generated. It is matched against the human-readable #:name for each configuration, so it will be something like

{1} Racket | {3} Linux | {1} 64-bit x86_64; built on Debian 10

If installer? is true, then the configurations will include ".exe" installers for Windows, ".dmg" disk images for Mac PS, and ".sh" installers for Linux. If tgz? is true, then the configurations will include ".tgz" archives for all platforms. Source distributions will be included as ".tgz" archives independent of installer? and tgz?.

The name argument provides a component of the human-readable #:name for a configuration, typically "{1} Racket" or "{2} Minimal Racket". The file-name argument provides the component of an installer or archive name, typically "racket" or "racket-minimal".

The container-prefix argument is used as a prefix on all Docker container names used by the build.

The cs? and bc? arguments indicate whether the respective Racket variant is included, and the cs-name-suffix and bc-name-suffix arguments provide a suffix to add to name.

The uncommon? argument indicates whether to include platforms that are supported but not among the most widely used, and that are included only in Minimal Racket form at the main Racket download site.

The extra-linux-variants? argument indicates whether to include extra Linux variants. The base variant links to libraries to work on as many Linux distributions as possible, but additional variants can provide a better fit for the C and terminal libraries on different Linux distributions.

If windows-sign-post-process is not #f, then it is used as a #:server-installer-post-process for Windows installer configurations to sign them. Similarly, if mac-sign-cert-config or mac-notarization-configis not #f, it is used as a #:sign-cert-config or #:notarization-configvalue to sign Mac OS disk images.

The recompile-cache argument is used as the #:recompile-cache configuration for all installer builds.

The aliases list is added to #:dist-alises for each configuration.

The max-parallel argument limits the number of Docker containers that run concurrently, while j limits parallelism within a Docker container.

Expect each container to use 2 GB of memory or j GB, whichever is larger. Containers are not automatically removed after a build, so they are available for incremental builds; see also extract-container-names. Expect the full set of containers to use up to 128 GB of disk space. Note that Docker on some host platforms (such as Mac OS) has a configurable set of limits that span all running containers, so make sure those limits are set appropriately.

Docker containers are left in place after a distribution build, which enables incremental updates (to some degree) when rebuilding. It’s always safe to discard the containers between builds.

Note that the configuration produced by make-machines creates Git checkouts in the "build" subdirectory of the Racket checkout used to drive a distribution build. To reset a build to work from scratch, be sure to delete the "build" subdirectory as well as removing Docker containers.