3 Site Configuration Language🔗ℹ

A site configuration module is normally written in the distro-build/config language. The configuration describes individual machines, and groups them with parallel or sequential to indicate whether the machine’s builds should run sequentially or in parallel. Options specified at parallel or sequential are propagated to each machine in the group.

The distro-build/config language is like racket/base except that the module body must have exactly one expression (plus any number of definitions, etc.) that produces a site-configuration value. The value is exported as site-config from the module. Any module can act as a site-configuration module a long as it exports site-config as a site-configuration value.

Site-configuration values are created with sequential, parallel, and machine:

Site-configuration keyword arguments (where string* means no spaces, etc.):

• #:host string* — defaults to "localhost"; if #:docker is provided, this host name is used as a Docker container name

• #:name string — defaults to #:host’s value; this string is recorded as a description of the installer and can be used in a generated table of installer links; see also Names and Download Pages

• #:port integer — SSH port for the client; defaults to 22

• #:user string*-or-false — SSH user for the client; defaults to #f, which means the current user

• #:dir path-string — defaults to "build/plt" or "build\\plt", or to the current directory if the host is "localhost" and the user is #f

• #:env (list (list string* string) ...) — environment-variable settings to prefix all client-machine interactions for a Unix or Mac OS client; for example '(("PATH" "/usr/local/bin:/usr/bin")) configures the client machine’s PATH enviornment variable to have only "/usr/local/bin" and "/usr/bin"

• #:server string* — the address of the server as accessed by the client (except for Docker clients); when SSH remote tunneling works, then "localhost" should work to reach the server; defaults to the SERVER makefile variable, which in turn defaults to "localhost"; see also #:server-hosts and #:server-port, which must be at the configuration top level

• #:repo string — the git repository for Racket; defaults to "http://‹server›:‹server-port›/.git", except for Docker clients, which access the server’s directory directly; see also #:extra-repo-dir, which must be at the configuration top level

• #:pkgs (list string* ...) — packages to install; defaults to the PKGS makefile variable

• #:test-args (list string ...) — arguments to raco test as run in the installation-staging directory of a client after an installer is created, where testsing happens only if if a non-empty argument list is specified, if the client is not a source-runtime build, and if the client does not have a #:cross-target or #:cross-target-machine configuration; running raco test will only work if "compiler-lib" is among the packages included in the distribution or included in a #:test-pkgs configuration; defaults to '()

• #:test-pkgs (list string* ...) — extra packages to install after an installer is created and before tests are run; note that "compiler-lib" may be needed to provide raco test itself; the set of packages needed for all nested configurations should be included in a top-level #:pkgs or #:test-pkgs specification, so that the packages are prepared for use by clients; defaults to '()

• #:dist-base-url string — a URL that is used to construct a default for #:doc-search and #:dist-catalogs, where the constructed values are consistent with converting a build server’s content into a download site; since URLs are constructed via relative paths, this URL normally should end with a slash

• #:doc-search string — URL to install as the configuration for remote documentation searches in generated installers; "" is replaced with the PLT default; defaults to the #:dist-base-url setting (if present) extended with "doc/local-redirect/index.html" or the DOC_SEARCH makefile variable

• #:install-name string — string used as the name of the installation for package operations in the user package scope, where "" keeps the name as the Racket version; the default is "snapshot" if the value of #:release? is #f, "" otherwise

• #:build-stamp string — a string representing a build stamp, recorded in installers; the default is from the BUILD_STAMP makefile variable or generated if the value of #:release? is #f, "" otherwise

• #:dist-name string — the distribution name; defaults to the DIST_NAME makefile variable

• #:dist-base string* — the distribution’s installater name prefix; defaults to the DIST_BASE makefile variable

• #:dist-dir string* — the distribution’s installation directory; defaults to the DIST_DIR makefile variable

• #:dist-suffix string* — a suffix for the installer’s name, usually used for an operating system variant; defaults to the DIST_SUFFIX makefile variable

• #:dist-vm-suffix string* — a suffix for the installer’s name, usually used for a Racket virtual machine variant, added after #:dist-suffix; defaults to ""

• #:dist-aliases (list (list string*-or-false string*-or-false string*-or-false) ...) — a list of base–suffix–vm-suffix lists representing additional names to link for the installer in a download site, where #f as a list element means “the same as for the main name” and where the first alias is used for a “current” link when enabled at a download site; a list with the #:dist-base, #:dist-suffix, and #:dist-vm-suffix values is effectively appended to the end of the #:dist-aliases list if not present already; defaults to '().

  Added in version 1.9 of package distro-build-server.

• #:dist-catalogs (list string ...) — catalog URLs to install as the initial catalog configuration in generated installer, where "" is replaced with the PLT default catalogs; defaults to the #:dist-base-url value (if present) extended with "catalog/" in a list followed by ""

• #:readme string-or-procedure — the content of a "README" file to include in installers, or a function that takes a hash table for a configuration and returns a string; the default is the make-readme function from distro-build/readme

• #:max-vm real — for VirtualBox clients, the maximum number of VirtualBox virtual machines allowed to run concurrently with this machine, counting the machine; defaults to 1

• #:vbox string — VirtualBox machine name (as shown, for example, in the Virtual Box GUI); if provided, the virtual machine is started and stopped on the server as needed

• #:docker string — Docker image name; if provided and #:vbox is not provided, then a container using the #:host name is created if it does not already exist, started if it is not already running, and stopped on the server after building; the image "racket/distro-build" is suitable as a generic Linux image, and an image such as "racket/distro-build:i386-linux" is suitable for building for a specific architecture

  Added in version 1.8 of package distro-build-server.

• #:docker-platform string-or-false — Docker image platform; specifies a platform other than the default one for a host and #:docker image, which is useful when multiple platforms are supported by both the image and host machine; however, specifying a platform-specific Docker image like "racket/distro-build:i386-linux" is better when running multiple platforms on the same host; defaults to #f, which means a default or image-determined platform

  Added in version 1.14 of package distro-build-server.

• #:platform symbol — 'unix, 'macosx, 'windows, 'windows/bash (which means 'windows though an SSH server providing bash, such as Cygwin’s), or 'windows/cmd (which means 'windows through an SSH server that expects cmd commands); the symbol names the client machine’s system, not the target for cross-compilation; defaults to (system-type)

• #:configure (list string ...) — arguments to configure; if "--disable-portable" is not present, then "--enable-portable" is added to the start of the list; defaults to '()

• #:cross-target string* — specifies a target for cross-compilation, which adds --host=string* to the start of the list of configure arguments; in addition, if no #:racket value is provided, a native racket executable for the client machine is created (by using configure with no arguments) and used for cross-compilation in the same way as a #:racket value; note that cross-compilation for the 'cs variant may also also requires a #:cross-target-machine specification, although it is inferred from #:cross-target if possible

• #:cross-target-machine string* — similar to #:cross-target, but used only for #:variant 'cs, and specifies the target machine for cross-compilation as a string like "ta6nt"; use both #:cross-target-machine and #:cross-target unless the former can be inferred from the latter or unless options in #:configure instead of #:cross-target select the cross-build target

  Added in version 1.3 of package distro-build-server.

• #:racket string-or-false — an absolute path to a native Racket executable to use for compilation, especially cross-compilation; if the value is #f, then the Racket executable generated for the client machine is used to prepare the installer, or a client-native executable is generated automatically if #:cross-target or #:cross-target-machine is specified; a non-#f value for #:racket is propagated to #:configure via --enable-racket

• #:scheme string-or-false — obsolete; was an absolute path to a directory containing Chez Scheme sources

  Added in version 1.3 of package distro-build-server.

• #:target-platform symbol — 'unix, 'macosx, or 'windows, or #f, indicating the target platform’s type (which is different from the client system type in the case of cross-compilation); defaults to #f, which means that the target platform should be inferred from arguments such as #:cross-target

• #:variant symbol — 'bc, '3m (as a synonym for 'bc), 'cgc, or 'cs, indicating the target build; defaults to 'cs or 'bc depending on the running Racket implementation

  Changed in version 1.13 of package distro-build-server: Changed the default to depend on the running Racket implementation.

• #:compile-any? boolean — determines whether to build bytecode in machine-independent form, which works for all Racket variants but is slower to load; a #t value makes sense mainly for a source distribution that includes built packages or an installer used to drive machine-independent package builds; defaults to #f

• #:bits integer — 32 or 64; affects Visual Studio mode

• #:vc string* — provided to "vcvarsall.bat" to select the Visual Studio build mode; the default is "x86" or "x86_amd64", depending on the value of #:bits

• #:sign-identity string — provides an identity to be passed to codesign for code signing on Mac OS (for a package or all executables in a distribution), where an empty string disables signing; the default is ""

• #:notarization-config hash-or-false — configures notarization of a signed Mac OS ".dmg" bundle via xcrun notarytool and xcrun stapler; the required keys are 'primary-bundle-id as a string, 'user as a string, 'team as a string, and 'app-specific-password-file as a string that is a path that contains a password; the allowed optional keys are 'wait-seconds as a nonnegative exact integer (defaults to 120) and 'error-on-fail? as a boolean (defaults to #t)

  Changed in version 1.15 of package distro-build-server: Added 'team and changed 'wait-seconds default to 120.

• #:osslsigncode-args (list string ...) — provides arguments for signing a Windows executable using osslsigncode, where -n, -t, -in, and --out arguments are supplied automatically

• #:hardened-runtime? boolean — if true and if #:sign-identity is non-empty, specifies the hardened runtime and appropriate entitlements while signing; the default is #t if #:sign-identity is non-empty

  Added in version 1.6 of package distro-build-server.

• #:client-installer-pre-process (list string ...) — an executable path followed by initial arguments; the executable is run with the assembled distribution directory (added as an additional argument) before an installer file is created from the directory; the default is an empty list, which disables the pre-processing action

  Added in version 1.5 of package distro-build-server.

• #:client-installer-post-process (list string ...) — an executable path followed by initial arguments; the executable is run with the installer path (added as an additional argument) before an installer file is uploaded from the client; the default is an empty list, which disable the post-processing action

  Added in version 1.2 of package distro-build-server.

• #:server-installer-post-process (list path-string ...) — an executable path followed by initial arguments; the executable is run with the installer path added (as an additional argument) when creating a download site for an installer file on the server machine; the default is an empty list, which disable the post-processing action for the installer

  Added in version 1.2 of package distro-build-server.

• #:make string — a make command prefix to use on Unix and Mac OS clients, where the prefix is not quoted, so it can include space-separated arguments after the executable name; defaults to "make"

  Added in version 1.10 of package distro-build-server.

• #:j integer — parallelism for make on Unix and Mac OS and for raco setup on all platforms; defaults to 1

• #:timeout number — numbers of seconds to wait before declaring failure; defaults to 30 minutes

• #:init string-or-false — if non-#f, a command to run on a client and before any other commands; the default is #f

• #:clean? boolean — if true, then the build process on the client machine starts by removing #:dir’s value; use #f for a shared repo checkout; the default is determined by the CLEAN_MODE makefile variable, unless #:host is "localhost", #:user is #f, and #:dir is not specified, in which case the default is #f

• #:pull? boolean — if true, then the build process on the client machine starts by a git pull in #:dir’s value; use #f, for example, for a repo checkout that is shared with server; the default is #t, unless #:host is "localhost", #:user is #f, and #:dir is not specified, in which case the default is #f

• #:release? boolean — if true, then create release-mode installers; the default is determined by the RELEASE_MODE makefile variable

• #:source? boolean — determines the default value for #:source-runtime? and #:source-pkgs? settings

• #:source-runtime? boolean — if true, then create an archive that contains the run-time system in source form (possibly with built packages), instead of a platform-specific installer; a #t value works best when used for a Unix build, since Unix clients typically have no native-library packages; the default is the value of #:source?

• #:source-pkgs? boolean — if true, then packages are included in the installer/archive only in source form; a true value works best when the #:source-runtime? value is also #t; the default is the value of #:source?

• #:all-platform-pkgs? boolean — if true, then for packages with platform-specific dependencies, the dependencies for all platforms are installed; a #t value can make sense for a bundle that is primarily source but also includes native binaries for third-party libraries; the default is #f

  Added in version 1.4 of package distro-build-server.

• #:static-libs? boolean — if true, then create and include static libraries and associated files for embedding Racket in other applications, where supported; the default is #f

  Added in version 1.7 of package distro-build-server.

• #:versionless? boolean — if true, avoids including the Racket version number in an installer’s name or in the installation path; the default is determined by the VERSIONLESS_MODE makefile variable

• #:dist-base-version string* — a version identifier to include in each installer’s name just as the base name (as determined by #:dist-base) and before the platform, as long as #:versionless? is not specified as true; the default is (version)

  Added in version 1.12 of package distro-build-server.

• #:mac-pkg? boolean — if true, creates a ".pkg" for Mac OS (in single-file format) instead of a ".dmg"; the default is #f

• #:tgz? boolean — if true, creates a ".tgz" archive instead of an installer; the default is #f

• #:pause-before nonnegative-real — a pause in seconds to wait before starting a machine, which may help a virtual machine avoid confusion from being stopped and started too quickly; the default is 0

• #:pause-after nonnegative-real — a pause in seconds to wait after stopping a machine; the default is 0

• #:log-file string — the file name to use for the log file for the machine; defaults to #:name’s value

  Added in version 1.8 of package distro-build-server.

• #:stream-log? boolean — if true, send log output to server’s output and error ports as well as logging them to a file; defaults to #f

  Added in version 1.8 of package distro-build-server.

• #:custom hash-table — a hash table mapping arbitrary keywords to arbitrary values; when a value for #:custom is overriden in a nested configuration, the new table is merged with the overriden one; use such a table for additional configuration entries other than the built-in ones, where additional entires may be useful to a #:readme procedure

Top keywords (expected only in the configuration top-level):

• #:server-port integer — the port of the server as accessed by the client, and also the port started on clients to tunnel back to the server; defaults to the SERVER_PORT makefile variable, which in turn defaults to 9440

• #:server-hosts (list string* ...) — addresses that determine the interfaces on which the server listens; an empty list means all of the server’s interfaces, while (list "localhost") listens only on the loopback device; defaults to the SERVER_HOSTS makefile variable split on commas, which in turn defaults to (list "localhost")

• #:extra-repo-dir path-string-or-false — a server-side directory that contains additional Git repositories to be served to clients, normally Chez Scheme with its submodules; any subdirectory that constains a ".git" directory will be prepared with git update-server-info, and any repository clones created by clients (other than the main Racket repository) will use the served directory; updating on clients requires that each served repository has a "master" branch; defaults to #f, which disables repository redirection on clients

• #:site-dest path-string — destination for completed build, used by the site and snapshot-site makefile targets; the default is "build/site"

• #:current-link-version string — substring of installer names to replace with "current" for “current” links on a snapshot page; the default is the value of #:dist-base-version

  Added in version 1.12 of package distro-build-server.

• #:pdf-doc? boolean — whether to build PDF documentation when assembling a site; the default is #f

• #:fake-installers? boolean — if true, instead of using client machines to build installers, just uses the content of the "README" file that would be included as the content of the installer file; beware that installer names are normally determined on the client side, so the server must guess about each installer name based on the #:name description (e.g., “Windows” in the description implies a Windows installer); the default is #f

  Added in version 1.11 of package distro-build-server.

• #:email-to (list string ...) — a list of addresses to receive e-mail reporting build results; mail is sent via sendmail unless #:smtp-... configuration is supplied

• #:email-from string — address used as the sender of e-mailed reports; the first string in #:email-to is used by default

• #:smtp-server string*, #:smtp-port string*, #:smtp-connect symbol, #:smtp-user string-or-false #:smtp-password string-or-false #:smtp-user+password-file path-string-or-false #:smtp-sending-server string* — configuration for sending e-mail through SMTP instead of sendmail; the #:smtp-port default (25, 465, or 587) is picked based on #:smtp-connect, which can be 'plain, 'ssl, or 'tls and defaults to 'plain; supply a non-#f #:smtp-user and #:smtp-password or #:smtp-user+password-file when authentication is required by the server, where a file is used by reading twice to get a default user and password value; supply #:smtp-sending-server when the server needs a name other than "localhost" for the sender

  Changed in version 1.16 of package distro-build-server: Added #:smtp-user+password-file and #:smtp-sending-server.

• #:site-help hash-table — hash table of extra “help” information for entries on a web page created by the site and snapshot-site makefile targets; the hash keys are strings for row labels in the download table (after splitting on | and removing {...}), and the values are X-expressions (see xml) for the help content

• #:site-help-fallbacks list — list of extra “help” information, like #:site-help, but with regexp keys instead of strings; each element of the list is a 2-element list containing a regexp and an X-expressions, and if no match is found already in #:site-help, the regexps are tried in order on row labels in the download table

  Added in version 1.11 of package distro-build-server.

• #:site-title string — title for the main page generated by the site or snapshot-site makefile target; the default is "Racket Downloads"

• #:max-snapshots number — number of snapshots to keep, used by the snapshot-site makefile target; defaults to 5

• #:week-count number-or-false — if not #f, keeps one snapshot per day for the last week as well as one snapshot per week for the number of week specified; if set, then #:max-snapshots is ignored; defaults to #f

• #:plt-web-style? boolean — indicates whether plt-web should be used to generate a site or snapshot page; the default is #t

• #:fail-on-client-failures boolean — if true, failure on any build client causes the build server to exit with a non-zero return code; the default is #f

  Added in version 1.1 of package distro-build-server.