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"

• #: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; 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"; 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-catalogs (list string ...) — catalog URLs to install as the initial catalog configuration in generated installed, where "" is replaced with the PLT default catalogs; defaults to the #:dist-base-url value (if present) extended with "catalogs" 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 — maximum number of VMs allowed to run with this machine, counting the machine; defaults to 1

• #:vbox string — Virtual Box 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

• #: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

• #: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 — an absolute path to a directory containing Chez Scheme sources, used only for #:variant 'cs; if the value is #f, then a build directory is created by cloning a Chez Scheme Git repository; a non-#f value for #:scheme is propagated to #:configure via --enable-scheme

  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 — '3m, 'cgc, or 'cs, indicating the target build; defaults to '3m

• #: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 distirbution that includes built packages; 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 ""

• #: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.

• #: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

• #: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

• #: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"

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

• #: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 — 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 when authentication is required by the 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-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.