8 Examples🔗ℹ

Here are some example configuration files.

8.1 Single Installer🔗ℹ

The simplest possible configuration file is

#lang distro-build/config

(machine)

In fact, this configuration file is created automatically as "build/site.rkt" (if the file does not exist already) and used as the default configuration. With this configuration,

  make installers

creates an installer in "build/installers" for the platform that is used to create the installer.

Beware that the default configuration creates a relatively large distribution, because it contains "main-distribution" and "main-distribution-test". Also, the default configuration uses a single sequential job for the client phase, instead of parallelizing. Consider providing #:pkgs and/or #:j options to machine.

While the client part of this build is running, output is written to "build/log/localhost" (since #:name defaults to #:host, and #:host defaults to "localhost").

8.2 Cross-Build via Docker🔗ℹ

To build for Mac OS on a host machine that can run Docker containers (see Available Docker Images), create a "build/site.rkt" file with

#lang distro-build/config

(machine

;; FIXME: the name of the container to be created for building

#:host "example-osxcross-aarch64"

;; Image name

#:docker "racket/distro-build:osxcross-aarch64"

;; Cross-compile configuration

#:cross-target-machine "tarm64osx"

#:cross-target "aarch64-apple-darwin20.2"

#:configure '("CC=aarch64-apple-darwin20.2-cc"))

The container name provided as #:host enables using the same container for incremental rebuilds, instead of starting from scratch each time.

See Single Installer for advice about providing #:pkgs and #:j options. Depending on the distribution, a #:timeout larger than the default of (* 60 30) seconds may also be needed, since cross compilation is much more work for a client.

While the client part of this build is running, output is written to "build/log/example-osxcross-aarch64" (since #:name defaults to #:host).

8.3 Multiple Platforms🔗ℹ

A configuration module that drives multiple Docker containers in parallel to build for both 64-bit Windows (x64) and Mac OS (Intel) might look like this:

#lang distro-build/config

(sequential

;; Minimal Racket:

#:pkgs '()

;; Up to 2 jobs in each of 2 containers:

#:j 2

(parallel ; could replace with `sequential`

(machine

#:name "Windows (64-bit x64)"

#:host "example-windows-x86_64" ; FIXME: container name

#:docker "racket/distro-build:crosswin"

#:cross-target-machine "ta6nt"

#:cross-target "x86_64-w64-mingw32")

(machine

#:name "Mac OS (64-bit Intel)"

#:host "example-macosx-x86_64" ; FIXME: container name

#:docker "racket/distro-build:osxcross-x86_64"

#:cross-target-machine "ta6osx"

#:cross-target "x86_64-apple-darwin13"

#:configure '("CC=x86_64-apple-darwin13-cc"))))

With this configuration file in "site.rkt",

  make installers CONFIG=site.rkt

produces two installers, both in "build/installers", and a hash table in "table.rktd" that maps "Windows (64-bit x64)" to the Windows installer and "Mac OS (64-bit Intel)" to the Mac OS installer.

While the client parts of this build are running, output is written to "build/log/Windows (64-bit x64)" and "build/log/Mac OS (64-bit Intel)".

8.4 Installer Web Page🔗ℹ

To make a web page that serves both a minimal installer and main-installation packages, create a "site.rkt" file with

#lang distro-build/config

(sequential

;; The packages that will be available:

#:pkgs '("main-distribution")

;; FIXME: the URL where the installer and packages will be:

#:dist-base-url "http://my-server.domain/snapshot/"

(machine

;; FIXME: the way the installer is described on the web page:

#:name "Minimal Racket | My Platform"

;; The packages in this installer:

#:pkgs '()))

then

  make site CONFIG=site.rkt

creates a "build/site" directory that you can move to your web server’s "snapshot" directory, so that "build/site/index.html" is the main page, and so on.

8.5 Accumulated Shapshots Web Page🔗ℹ

To make a web site that provides some number (5, by default) of snapshots, use (current-stamp) when constructing the #:dist-base-url value. Also, use (current-stamp) as the directory for assembling the site:

#lang distro-build/config

(sequential

;; The packages that will be available:

#:pkgs '("gui-lib")

;; FIXME: the URL where the installer and packages will be:

#:dist-base-url (string-append "http://my-server.domain/snapshots/"

(current-stamp) "/")

;; The local directory where a snapshot is written

#:site-dest (build-path "build/site" (current-stamp))

(machine

;; FIXME: the way the installer is described on the web page:

#:name "Minimal Racket | My Platform"

;; The packages in this installer:

#:pkgs '()))

Then,

  make snapshot-site CONFIG=site.rkt

creates a "build/site" directory that you can move to your web server’s "snapshots" directory, so that "build/site/index.html" is the main page that initially points to "build/site/‹stamp›/index.html", and so on. To make a newer snapshot, update the Git repository, leave "build/site" in place, and run

  make snapshot-site CONFIG=site.rkt

again. The new installers will go into a new <stamp> subdirectory, and the main "index.html" file will be rewritten to point to them.

8.6 Main Download Site🔗ℹ

A configuration module that drives a build like the main Racket download page (which will take hours) might look like this:

#lang distro-build/config

(require distro-build/main-distribution)

(sequential

;; FIXME: the URL where the installer and packages will be:

#:dist-base-url (string-append "http://my-server.domain/snapshots/"

(current-stamp) "/")

#:splice (make-spliceable-limits)

(make-machines #:minimal? #t)

(make-machines))

8.7 Multiple Platforms on Multiple Machines🔗ℹ

A configuration module that drives multiple client machines—virtual and remote—to build installers might look like this:

#lang distro-build/config

(sequential

#:pkgs '("drracket")

#:server-hosts '() ; Insecure? See below.

(machine

#:name "Linux (32-bit, Precise Pangolin)"

#:vbox "Ubuntu 12.04"

#:host "192.168.56.102")

(machine

#:name "Windows (64-bit)"

#:host "10.0.0.7"

#:server "10.0.0.1"

#:dir "c:\\Users\\racket\\build\\plt"

#:platform 'windows

#:bits 64))

The configuration describes using the hosts "192.168.56.1" and "10.0.0.7" for Linux and Windows builds, respectively, which are run one at a time.

The Linux machine runs in VirtualBox on the server machine (in a virtual machine named "Ubuntu 12.04"). It contacts the server still as localhost, and that works because the SSH connection to the Linux machine creates a tunnel (at the same port as the server’s, which defaults to 9440).

The Windows machine uses freeSSHd (not a bash-based SSH server like Cygwin) and communicates back to the server as "10.0.0.1" instead of using an SSH tunnel. To make that work, #:server-hosts is specified as the empty list to make the server listen on all interfaces (instead of just "localhost")—which is possibly less secure than the default restriction that allows build-server connections only via "localhost".