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 X 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"

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

• #:repo string — the git repository for Racket; defaults to "http://‹server›:‹server-port›/.git"

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

• #: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, or 'windows/bash (which means 'windows though an SSH server providing bash, such as Cygwin’s); 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

• #: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 is specified; a non-#f value for #:racket is propagated to #:configure via --enable-racket

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

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

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

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

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

• #: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 X (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 (recognized only in the configuration top-level):

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

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