convert docs to Scribble format
This commit is contained in:
Matthew Flatt
parent
dea33cdfa1
commit
7730ddb73c
|
|
@ -1,564 +0,0 @@
|
|||
Site Configuration Modules
|
||||
==========================
|
||||
|
||||
A build farm is normally run via the `installers', `site', or
|
||||
`snapshot-site' target of the Racket repository's top-level
|
||||
makefile. Each of those targets uses `installers', which expects a
|
||||
`CONFIG=...' argument to specify a configuration module file (or uses
|
||||
"build/site.rkt" as the default).
|
||||
|
||||
A site configuration module starts `#lang distro-build/config' and
|
||||
uses keywords to specify various options for the configuration. This
|
||||
format is described is detail further below; for now, it's enough to
|
||||
know that there are various options, each of which is associated with
|
||||
a keyword.
|
||||
|
||||
The machine where `make installers' is run is the server machine.
|
||||
The server machine first prepares packages for installation on
|
||||
clients. The site configuration's top-level entry is consulted for
|
||||
a `#:pkgs' and/or `#:doc-search' option, which overrides any `PKGS'
|
||||
and/or `DOC_SEARCH' configuration from the makefile.
|
||||
|
||||
The site configuration file otherwise describes and configures
|
||||
client machines hierarchically, where configuration options
|
||||
propagate down the hierarchy when they are not overridden more
|
||||
locally.
|
||||
|
||||
Each client is normally built by running commands via `ssh', where the
|
||||
client's host, `#:host' (with and optional `#:port' and/or `#:user')
|
||||
indicate the `ssh' target. Each client machine must be set up with a
|
||||
public-key authentication, because a direct `ssh' is expected to work
|
||||
without a password prompt. An exception is when the host is
|
||||
"localhost" and user is #f, in which case a shell is used directly
|
||||
instead of `ssh'. When `ssh` is used, -R is also used to create a
|
||||
tunnel back to the server, and the client by default uses that tunnel
|
||||
for all communication, and the server by default accepts only
|
||||
connections via "localhost".
|
||||
|
||||
On the client machine, all work is performed at a specified
|
||||
directory as specified by `#:dir'. The directory defaults to
|
||||
"build/plt" (Unix, Mac OS X) or "build\\plt" (Windows), except when
|
||||
the host is "localhost" and the client is #f, in which case the
|
||||
current directory (i.e., the server's directory) is used.
|
||||
|
||||
Normally, the client directory is a git clone:
|
||||
|
||||
- If the directory exists already on a client machine (and the
|
||||
machine is not configured for "clean" mode), then if the directory
|
||||
contains a ".git" subdirectory, it is assumed to be a git clone
|
||||
and updated with `git pull'. The `git pull' operation can be
|
||||
disabled by specifying `#:pull?' as #f, and it defaults to #f
|
||||
in the case that `#:dir' is not specified, the host is
|
||||
"localhost", and the user is #f.
|
||||
|
||||
- If the directory does not exist, a git repository is
|
||||
cloned. The repository can be specified with `#:repo'. By
|
||||
default, the server is used as the source git repository (so
|
||||
that the server and client are in sync), which means that the
|
||||
server's directory must be a git clone.
|
||||
|
||||
Note that neither `ssh' nor `git' turn out to be needed when the host
|
||||
is "localhost", the user is #f, and the directory is not specified
|
||||
(which corresponds to the defaults in all cases).
|
||||
|
||||
If a build fails for a machine, building continues on other
|
||||
machines. Success for a given machine means that its installer
|
||||
ends up in "build/installers" (and failure for a machine means no
|
||||
installer) as recorded in the "table.rktd" file.
|
||||
|
||||
To use the `site' makefile target, the configuration file must at
|
||||
least provide a `#:dist-base-url' value, which is a URL at which the
|
||||
site will be made available. To use the `snapshot-site' makefile
|
||||
target, then `#:site-dest' will need to be specified, normally as a
|
||||
path that ends with the value produced by `(current-stamp)'.
|
||||
|
||||
Hint: When developing a configuration file, use an empty set of
|
||||
packages to a configuration that works as quickly as possible. Then,
|
||||
change the list of packages to the ones that you actually want in the
|
||||
installers.
|
||||
|
||||
Machine Requirements
|
||||
--------------------
|
||||
|
||||
Each Unix or Mac OS X client needs the following available:
|
||||
|
||||
* SSH server with public-key authentication (except "localhost")
|
||||
* git (unless the working directory is ready)
|
||||
* gcc, make, etc.
|
||||
|
||||
Each Windows client needs the following:
|
||||
|
||||
* SSH server with public-key authentication, providing either a
|
||||
Windows command line (like freeSSHd) or bash with access to
|
||||
cmd.exe (like Cygwin's opensshd)
|
||||
* git (unless the working directory is ready)
|
||||
* Microsoft Visual Studio (version >= 9.0, <= 12.0), installed
|
||||
in the default folder:
|
||||
C:\Program Files\Microsoft Visual Studio <vers>
|
||||
or
|
||||
C:\Program Files (x86)\Microsoft Visual Studio <vers>
|
||||
* Nullsoft Scriptable Install System (NSIS) verstion 2.x, installed
|
||||
in the default folder:
|
||||
C:\Program Files\NSIS\makensis.exe
|
||||
or
|
||||
C:\Program Files (x86)\NSIS\makensis.exe
|
||||
or installed so that `makensis' in your PATH.
|
||||
|
||||
Site Configuration
|
||||
-------------------
|
||||
|
||||
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.
|
||||
|
||||
Site-configuration keywords (where <string*> means no spaces, etc.):
|
||||
|
||||
#:host <string*> --- defaults to "localhost"
|
||||
|
||||
#:name <string> --- defaults to host; 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" below
|
||||
|
||||
#:port <integer> --- SSH port for the client; defaults to 22
|
||||
|
||||
#:user <string*/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
|
||||
|
||||
#: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-of-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 '(<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 #:dist-base-url (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 false, "" otherwise.
|
||||
|
||||
#:build-stamp <string> --- a string representing a build stamp,
|
||||
recorded in installes; the default is from the `BUILD_STAMP'
|
||||
makefile variable or generated if the value of `#:release?' is
|
||||
false, "" 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 OS variant; defaults to the `DIST_SUFFIX'
|
||||
makefile variable
|
||||
|
||||
#:dist-catalogs '(<string> ...) --- catalog URLs to install as the
|
||||
initial catalog configuration in generated installed, where "" is
|
||||
replaced with the PLT default catalogs; defaults to
|
||||
`#:dist-base-url' (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' (see below)
|
||||
|
||||
#:max-vm <real> --- max 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); defaults to `(system-type)'
|
||||
|
||||
#:configure '(<string> ...) --- arguments to `configure'
|
||||
|
||||
#: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 `#:bits'
|
||||
|
||||
#:sign-identity <string> --- provides an identity to be passed to
|
||||
`codesign` for code signing on Mac OS X (for all executables in a
|
||||
distribution), where an empty string disables signing; the default
|
||||
is ""
|
||||
|
||||
#: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>; set this to #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'; set to #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'
|
||||
|
||||
#: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 with a Unix client machine, 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
|
||||
|
||||
#:pause-before <nonnegative-number> --- 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-number> --- 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 <listof-of-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 <'plain, 'ssl, or 'tls>
|
||||
#:smtp-user <string-or-#f>
|
||||
#:smtp-password <string-or-#f>
|
||||
--- 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 in turn defaults to 'plain;
|
||||
supply 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 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
|
||||
|
||||
More precisely, 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.
|
||||
|
||||
The `distro-build/config' language also adds the following functions
|
||||
to `racket/base':
|
||||
|
||||
(machine <opt-kw> <opt-val> ... ...) -> site-config?
|
||||
Produces a site configuration based on the given keyword-based
|
||||
options. The support keyword arguments are described above.
|
||||
|
||||
(sequential <opt-kw> <opt-val> ... ... config ...)
|
||||
-> site-config?
|
||||
config : site-config?
|
||||
Produces a site configuration that runs each `config'
|
||||
sequentially. The support keyword arguments are described above.
|
||||
|
||||
(parallel <opt-kw> <opt-val> ... ... config ...)
|
||||
-> site-config?
|
||||
config : site-config?
|
||||
Produces a site configuration that runs each `config' in
|
||||
parallel. The support keyword arguments are described above.
|
||||
|
||||
(site-config? v) -> boolean?
|
||||
(site-config-tag config) -> (or/c 'machine 'sequential 'parallel)
|
||||
config : site-config?
|
||||
(site-config-options config) -> (hash/c keyword? any/c)
|
||||
config : site-config?
|
||||
(site-config-content config) -> (listof site-config?)
|
||||
config : site-config?
|
||||
Site configuation inspection
|
||||
|
||||
(current-mode) -> string?
|
||||
(current-mode s) -> void?
|
||||
s : string?
|
||||
A parameter whose value is the user's requested mode for this
|
||||
configuration, normally as provided via the makefile's
|
||||
`CONFIG_MODE' variable. The default mode is "default". The
|
||||
interpretation of modes is completely up to the
|
||||
site configuration file.
|
||||
|
||||
(current-stamp) -> string?
|
||||
Returns a string to identify the current build, normally a
|
||||
combination of the date and a git commit hash.
|
||||
|
||||
READMEs
|
||||
-------
|
||||
|
||||
The `distro-build/readme' library provides functions for constructing
|
||||
a README file's content. Each function takes a hash table mapping
|
||||
configuration keywords to values.
|
||||
|
||||
(make-readme config) -> string
|
||||
config : hash?
|
||||
Produces basic "README" content, using information about the
|
||||
distribution and the Racket license. The content is constructed
|
||||
using `config' keywords such as `#:name', `#:platform',
|
||||
`#:dist-name', and `#:dist-catalogs', and sometimes `current-stamp'.
|
||||
|
||||
(make-macosx-notes config) -> string
|
||||
config : hash?
|
||||
Produces "README" content to tell Mac OS X users how to install a
|
||||
distribution folder. This function is used by `make-readme' when
|
||||
`#:platform' in `config' is 'macosx.
|
||||
|
||||
Names and Download Pages
|
||||
------------------------
|
||||
|
||||
The `#:name' for an installer is used in an HTML table of download
|
||||
links by the `site' or `snapshot-site' targets. The names are first
|
||||
sorted. Then, for the purposes of building the table, a "|" separated
|
||||
by any number of spaces within a name is treated as a hierarchical
|
||||
delimiter, while anything within "{" and "}" in a hierarchical level
|
||||
is stripped from the displayed name along with surrounding spaces (so
|
||||
that it can affect sorting without being displayed). Anything after ";
|
||||
" within a "|"-separated part is rendered as a detail part of the
|
||||
label (e.g., in a smaller font).
|
||||
|
||||
For example, the names
|
||||
|
||||
"Racket | {2} Linux | 32-bit"
|
||||
"Racket | {2} Linux | 64-bit; built on Ubuntu"
|
||||
"Racket | {1} Windows | 32-bit"
|
||||
"Racket | {1} Windows | 64-bit"
|
||||
"Racket | {3} Source"
|
||||
|
||||
are shown (actually or conceptually) as
|
||||
|
||||
Racket
|
||||
Windows
|
||||
[32-bit] <build on Ubuntu>
|
||||
[64-bit]
|
||||
Linux
|
||||
[32-bit]
|
||||
[64-bit]
|
||||
[Source]
|
||||
|
||||
where the square-bracketed entries are hyperlinks and the
|
||||
angle-bracketed pieces are details.
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
** 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.
|
||||
|
||||
** Installer Web Page ***
|
||||
|
||||
To make a web page that serves both a minimal installer and 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.
|
||||
|
||||
** 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.
|
||||
|
||||
** Multiple Platforms **
|
||||
|
||||
A configuration module that drives multiple clients to build
|
||||
installers might look like this:
|
||||
|
||||
#lang distro-build/config
|
||||
|
||||
(sequential
|
||||
#:pkgs '("drracket")
|
||||
#:server-hosts '() ; Insecure? See below.
|
||||
(machine
|
||||
#:desc "Linux (32-bit, Precise Pangolin)"
|
||||
#:name "Ubuntu 32"
|
||||
#:vbox "Ubuntu 12.04"
|
||||
#:host "192.168.56.102")
|
||||
(machine
|
||||
#:desc "Windows (64-bit)"
|
||||
#:name "Windows 64"
|
||||
#: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, wjich
|
||||
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".
|
||||
|
||||
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 "Linux (32-bit, Precise Pangolin)" to the
|
||||
Linux installer and "Windows (64-bit)" to the Windows installer.
|
||||
686
distro-build-doc/distro-build.scrbl
Normal file
686
distro-build-doc/distro-build.scrbl
Normal file
|
|
@ -0,0 +1,686 @@
|
|||
#lang scribble/manual
|
||||
@(require scribble/bnf
|
||||
(for-label distro-build/config
|
||||
distro-build/readme))
|
||||
|
||||
@title{Building Distributions of Racket}
|
||||
|
||||
The @filepath{distro-build} collection provides tools for creating a
|
||||
Racket distribution---like the ones available at
|
||||
@url{http://download.racket-lang.org}, but perhaps for different
|
||||
versions or with different packages pre-installed.
|
||||
|
||||
The distribution-building tools are meant to be driven by a makefile
|
||||
in the main Racket source repository, which is currently
|
||||
@url{https://github.com/plt/racket}. See @filepath{INSTALL.txt} there
|
||||
for general build information.
|
||||
|
||||
@; ----------------------------------------
|
||||
|
||||
@section{Site Configuration Modules}
|
||||
|
||||
A build farm is normally run via the @tt{installers}, @tt{site}, or
|
||||
@tt{snapshot-site} target of the Racket repository's top-level
|
||||
makefile. The latter two targets chain to the @tt{installers} target,
|
||||
which expects a @tt{CONFIG=...} argument to specify a configuration
|
||||
module file (or uses @filepath{build/site.rkt} as the default).
|
||||
|
||||
A site configuration module starts @racket[@#,hash-lang[]
|
||||
@#,racketmodname[distro-build/config]] and uses keywords to specify
|
||||
various options for the configuration. This format is described is
|
||||
detail in @secref["distro-build-language"]. For now, it's enough to
|
||||
know that there are various options, each of which is associated with
|
||||
a keyword.
|
||||
|
||||
The machine where @exec{make installers} is run is the @deftech{server
|
||||
machine}. The server machine first prepares packages for installation
|
||||
on @deftech{client machines}. The site configuration's top-level entry
|
||||
is consulted for a @racket[#:pkgs] and/or @racket[#:doc-search]
|
||||
option, which overrides any @tt{PKGS} and/or @tt{DOC_SEARCH}
|
||||
configuration from the makefile.
|
||||
|
||||
The site configuration file otherwise describes and configures
|
||||
client machines hierarchically, where configuration options
|
||||
propagate down the hierarchy when they are not overridden more
|
||||
locally.
|
||||
|
||||
Each client is normally built by running commands via @exec{ssh},
|
||||
where the client's host configured with @racket[#:host] (with and
|
||||
optional @racket[#:port] and/or @racket[#:user]) indicate the
|
||||
@exec{ssh} target. Each client machine must be set up with a
|
||||
public-key authentication, because a direct @exec{ssh} is expected to
|
||||
work without a password prompt. An exception is when the host is
|
||||
@racket["localhost"] and user is @racket[#f], in which case a shell is
|
||||
used directly instead of @exec{ssh}. When @exec{ssh} is used, @Flag{R}
|
||||
is also used to create a tunnel back to the server, and the client by
|
||||
default uses that tunnel for all communication, so the server by
|
||||
default accepts only connections via @racket["localhost"].
|
||||
|
||||
On the client machine, all work is performed at a specified directory
|
||||
as specified by @racket[#:dir]. The directory defaults to
|
||||
@filepath{build/plt} (Unix, Mac OS X) or @filepath{build\plt}
|
||||
(Windows), except when the host is @racket["localhost"] and the client
|
||||
is @racket[#f], in which case the current directory (i.e., the
|
||||
server's directory) is used.
|
||||
|
||||
Normally, the client directory is a Git clone:
|
||||
|
||||
@itemlist[
|
||||
|
||||
@item{If the directory exists already on a client machine (and the
|
||||
machine is not configured for ``clean'' mode), then if the
|
||||
directory contains a @filepath{.git} subdirectory, it is assumed
|
||||
to be a git clone and updated with @exec{git pull}. The @exec{git
|
||||
pull} operation can be disabled by specifying @racket[#:pull?] as
|
||||
@racket[#f], and it defaults to @racket[#f] in the case that
|
||||
@racket[#:dir] is not specified, the host is @racket["localhost"],
|
||||
and the user is @racket[#f].}
|
||||
|
||||
@item{If the directory does not exist, a Git repository is cloned.
|
||||
The repository can be specified with @racket[#:repo]. By default,
|
||||
the server is used as the source Git repository (so that the
|
||||
server and client are in sync), which means that the server's
|
||||
directory must be a Git clone.}
|
||||
|
||||
]
|
||||
|
||||
Note that neither @exec{ssh} nor @exec{git} turn out to be needed when
|
||||
the host is @racket["localhost"], the user is @racket[#f], and the
|
||||
directory is not specified (which corresponds to the defaults in all
|
||||
cases).
|
||||
|
||||
If a build fails for a machine, building continues on other machines.
|
||||
Success for a given machine means that its installer ends up in
|
||||
@filepath{build/installers} (and failure for a machine means no
|
||||
installer) as recorded in the @filepath{table.rktd} file.
|
||||
|
||||
To use the @tt{site} makefile target, the configuration file must at
|
||||
least provide a @racket[#:dist-base-url] value, which is a URL at which the
|
||||
site will be made available. To use the @tt{snapshot-site} makefile
|
||||
target, then @racket[#:site-dest] will need to be specified, normally as a
|
||||
path that ends with the value produced by @racket[(current-stamp)].
|
||||
|
||||
Hint: When developing a configuration file, use an empty set of
|
||||
packages to a configuration that works as quickly as possible. Then,
|
||||
change the list of packages to the ones that you actually want in the
|
||||
installers.
|
||||
|
||||
|
||||
@; ----------------------------------------
|
||||
|
||||
@section{Machine Requirements}
|
||||
|
||||
Each Unix or Mac OS X @tech{client machines} needs the following available:
|
||||
|
||||
@itemlist[
|
||||
|
||||
@item{SSH server with public-key authentication (except @racket["localhost"])}
|
||||
|
||||
@item{@exec{git} (unless the working directory is ready)}
|
||||
|
||||
@item{@exec{gcc}, @exec{make}, etc.}
|
||||
|
||||
]
|
||||
|
||||
Each Windows @tech{client machine} needs the following:
|
||||
|
||||
@itemlist[
|
||||
|
||||
@item{SSH server with public-key authentication, providing either a
|
||||
Windows command line (like freeSSHd) or bash with access to
|
||||
@exec{cmd.exe} (like Cygwin's @exec{opensshd})}
|
||||
|
||||
@item{@exec{git} (unless the working directory is ready)}
|
||||
|
||||
@item{Microsoft Visual Studio (version at least 9.0 and no more than 12.0), installed
|
||||
in the default folder:
|
||||
@filepath{C:\Program Files\Microsoft Visual Studio @nonterm{vers}}
|
||||
or
|
||||
@filepath{C:\Program Files (x86)\Microsoft Visual Studio @nonterm{vers}}}
|
||||
|
||||
@item{Nullsoft Scriptable Install System (NSIS) verstion 2.x, installed
|
||||
in the default folder:
|
||||
@filepath{C:\Program Files\NSIS\makensis.exe}
|
||||
or
|
||||
@filepath{C:\Program Files (x86)\NSIS\makensis.exe}
|
||||
or installed so that @exec{makensis} in your @envvar{PATH}.}
|
||||
|
||||
]
|
||||
|
||||
|
||||
@; ----------------------------------------
|
||||
|
||||
@section[#:tag "distro-build-language"]{Site Configuration Language}
|
||||
|
||||
A site configuration module is normally written in the
|
||||
@racketmodname[distro-build/config] language. The configuration
|
||||
describes individual machines, and groups them with @racket[parallel]
|
||||
or @racket[sequential] to indicate whether the machine's builds should
|
||||
run sequentially or in parallel. Options specified at
|
||||
@racket[parallel] or @racket[sequential] are propagated to each
|
||||
machine in the group.
|
||||
|
||||
@defmodulelang[distro-build/config]
|
||||
|
||||
The @racketmodname[distro-build/config] language is like
|
||||
@racketmodname[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
|
||||
@racket[site-config] from the module. Any module can act as a
|
||||
site-configuration module a long as it exports @racket[site-config] as
|
||||
a site-configuration value.
|
||||
|
||||
Site-configuration values are created with @racket[sequential],
|
||||
@racket[parallel], and @racket[machine]:
|
||||
|
||||
@deftogether[(
|
||||
@defproc[(machine ...) site-config?]
|
||||
@defproc[(parallel ... [config site-config] ...) site-config?]
|
||||
@defproc[(sequential ... [config site-config] ...) site-config?]
|
||||
)]{
|
||||
|
||||
Produces a site configuration based on the given keyword-based
|
||||
options as described below. The @racket[sequential] function
|
||||
produces a site configuration that runs each @racket[config]
|
||||
sequentially. The @racket[parallel] function
|
||||
produces a site configuration that runs each @racket[config]
|
||||
in parallel.
|
||||
|
||||
Site-configuration keyword arguments (where @racket[_string*] means no
|
||||
spaces, etc.):
|
||||
|
||||
@itemlist[
|
||||
|
||||
@item{@racket[#:host _string*] --- defaults to @racket["localhost"]}
|
||||
|
||||
@item{@racket[#:name _string] --- defaults to @racket[#: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
|
||||
@secref["name-format"]}
|
||||
|
||||
@item{@racket[#:port _integer] --- SSH port for the client;
|
||||
defaults to @racket[22]}
|
||||
|
||||
@item{@racket[#:user _string*-or-false] --- SSH user for the client;
|
||||
defaults to @racket[#f], which means the current user}
|
||||
|
||||
@item{@racket[#:dir _path-string] --- defaults to
|
||||
@racket["build/plt"] or @racket["build\\plt"], or to the current
|
||||
directory if the host is @racket["localhost"] and the user is
|
||||
@racket[#f]}
|
||||
|
||||
@item{@racket[#:server _string*] --- the address of the server as
|
||||
accessed by the client; when SSH remote tunneling works, then
|
||||
@racket["localhost"] should work to reach the server; defaults to
|
||||
the @tt{SERVER} makefile variable, which in turn defaults to
|
||||
@racket["localhost"]}
|
||||
|
||||
@item{@racket[#: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 @tt{SERVER_PORT}
|
||||
makefile variable, which in turn defaults to @racket[9440]}
|
||||
|
||||
@item{@racket[#: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 @racket[(list
|
||||
"localhost")] listens only on the loopback device; defaults to the
|
||||
@tt{SERVER_HOSTS} makefile variable split on commas, which in turn
|
||||
defaults to @racket[(list "localhost")]}
|
||||
|
||||
@item{@racket[#:repo _string] --- the git repository for Racket;
|
||||
defaults to
|
||||
@filepath{http://@nonterm{server}:@nonterm{server-port}/.git}}
|
||||
|
||||
@item{@racket[#:pkgs (list _string* ...)] --- packages to install;
|
||||
defaults to the @tt{PKGS} makefile variable}
|
||||
|
||||
@item{@racket[#:dist-base-url _string] --- a URL that is used to
|
||||
construct a default for @racket[#:doc-search] and
|
||||
@racket[#: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}
|
||||
|
||||
@item{@racket[#:doc-search _string] --- URL to install as the
|
||||
configuration for remote documentation searches in generated
|
||||
installers; @racket[""] is replaced with the PLT default; defaults
|
||||
to the @racket[#:dist-base-url] setting (if present) extended with
|
||||
@racket["doc/local-redirect/index.html"] or the @tt{DOC_SEARCH}
|
||||
makefile variable}
|
||||
|
||||
@item{@racket[#:install-name _string] --- string used as the name of
|
||||
the installation for package operations in the @tt{user} package
|
||||
scope, where @racket[""] keeps the name as the Racket version; the
|
||||
default is @racket["snapshot"] if the value of @racket[#:release?]
|
||||
is @racket[#f], @racket[""] otherwise}
|
||||
|
||||
@item{@racket[#:build-stamp _string] --- a string representing a
|
||||
build stamp, recorded in installers; the default is from the
|
||||
@tt{BUILD_STAMP} makefile variable or generated if the value of
|
||||
@racket[#:release?] is @racket[#f], @racket[""] otherwise}
|
||||
|
||||
@item{@racket[#:dist-name _string] --- the distribution name;
|
||||
defaults to the @tt{DIST_NAME} makefile variable}
|
||||
|
||||
@item{@racket[#:dist-base _string*] --- the distribution's
|
||||
installater name prefix; defaults to the @tt{DIST_BASE} makefile
|
||||
variable}
|
||||
|
||||
@item{@racket[#:dist-dir _string*] --- the distribution's
|
||||
installation directory; defaults to the @tt{DIST_DIR} makefile
|
||||
variable}
|
||||
|
||||
@item{@racket[#:dist-suffix _string*] --- a suffix for the
|
||||
installer's name, usually used for an operating-system variant;
|
||||
defaults to the @tt{DIST_SUFFIX} makefile variable}
|
||||
|
||||
@item{@racket[#:dist-catalogs (list _string ...)] --- catalog URLs
|
||||
to install as the initial catalog configuration in generated
|
||||
installed, where @racket[""] is replaced with the PLT default
|
||||
catalogs; defaults to the @racket[#:dist-base-url] value (if
|
||||
present) extended with @racket["catalogs"] in a list followed by
|
||||
@racket[""]}
|
||||
|
||||
@item{@racket[#:readme _string-or-procedure] --- the content of a
|
||||
@filepath{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 @racket[make-readme] function from
|
||||
@racketmodname[distro-build/readme]}
|
||||
|
||||
@item{@racket[#:max-vm _real] --- maximum number of VMs allowed to
|
||||
run with this machine, counting the machine; defaults to
|
||||
@racket[1]}
|
||||
|
||||
@item{@racket[#: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}
|
||||
|
||||
@item{@racket[#:platform <symbol>] --- @racket['unix],
|
||||
@racket['macosx], @racket['windows], or @racket['windows/bash]
|
||||
(which means @racket['windows] though an SSH server providing
|
||||
@exec{bash}, such as Cygwin's); defaults to @racket[(system-type)]}
|
||||
|
||||
@item{@racket[#:configure (list _string ...)] --- arguments to
|
||||
@exec{configure}}
|
||||
|
||||
@item{@racket[#:bits _integer] --- @racket[32] or @racket[64];
|
||||
affects Visual Studio mode}
|
||||
|
||||
@item{@racket[#:vc _string*] --- provided to
|
||||
@filepath{vcvarsall.bat} to select the Visual Studio build mode;
|
||||
the default is @racket["x86"] or @racket["x86_amd64"], depending
|
||||
on the value of @racket[#:bits]}
|
||||
|
||||
@item{@racket[#:sign-identity _string] --- provides an identity to
|
||||
be passed to @exec{codesign} for code signing on Mac OS X (for all
|
||||
executables in a distribution), where an empty string disables
|
||||
signing; the default is @racket[""]}
|
||||
|
||||
@item{@racket[#:j _integer] --- parallelism for @tt{make} on Unix
|
||||
and Mac OS X and for @exec{raco setup} on all platforms; defaults
|
||||
to @racket[1]}
|
||||
|
||||
@item{@racket[#:timeout _number] --- numbers of seconds to wait
|
||||
before declaring failure; defaults to 30 minutes}
|
||||
|
||||
@item{@racket[#:clean? _boolean] --- if true, then the build process
|
||||
on the client machine starts by removing @racket[#:dir]'s value;
|
||||
use @racket[#f] for a shared repo checkout; the default is
|
||||
determined by the @tt{CLEAN_MODE} makefile variable, unless
|
||||
@racket[#:host] is @racket["localhost"], @racket[#:user] is
|
||||
@racket[#f], and @racket[#:dir] is not specified, in which case
|
||||
the default is @racket[#f]}
|
||||
|
||||
@item{@racket[#:pull? _boolean] --- if true, then the build process
|
||||
on the client machine starts by a @exec{git pull} in
|
||||
@racket[#:dir]'s value; use @racket[#f], for example, for a repo
|
||||
checkout that is shared with server; the default is @racket[#t],
|
||||
unless @racket[#:host] is @racket["localhost"], @racket[#:user] is
|
||||
@racket[#f], and @racket[#:dir] is not specified, in which case
|
||||
the default is @racket[#f]}
|
||||
|
||||
@item{@racket[#:release? _boolean] --- if true, then create
|
||||
release-mode installers; the default is determined by the
|
||||
@tt{RELEASE_MODE} makefile variable}
|
||||
|
||||
@item{@racket[#:source? _boolean] --- determines the default value for
|
||||
@racket[#:source-runtime?] and @racket[#:source-pkgs] settings}
|
||||
|
||||
@item{@racket[#: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 @racket[#t] value works best when used with a Unix
|
||||
client machine, since Unix clients typically have no
|
||||
native-library packages; the default is the value of
|
||||
@racket[#:source?]}
|
||||
|
||||
@item{@racket[#:source-pkgs? _boolean] --- if true, then packages
|
||||
are included in the installer/archive only in source form; a true
|
||||
value works best when the @racket[#:source-runtime?] value is also
|
||||
@racket[#t]; the default is the value of @racket[#:source?]}
|
||||
|
||||
@item{@racket[#: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
|
||||
@tt{VERSIONLESS_MODE} makefile variable}
|
||||
|
||||
@item{@racket[#:mac-pkg? _boolean] --- if true, creates a
|
||||
@filepath{.pkg} for Mac OS X (in single-file format) instead of a
|
||||
@filepath{.dmg}; the default is @racket[#f]}
|
||||
|
||||
@item{@racket[#: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 @racket[0]}
|
||||
|
||||
@item{@racket[#:pause-after _nonnegative-real] --- a pause in
|
||||
seconds to wait after stopping a machine; the default is
|
||||
@racket[0]}
|
||||
|
||||
@item{@racket[#:custom _hash-table] --- a hash table mapping
|
||||
arbitrary keywords to arbitrary values; when a value for
|
||||
@racket[#: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 @racket[#:readme]
|
||||
procedure}
|
||||
|
||||
]
|
||||
|
||||
Top keywords (recognized only in the configuration top-level):
|
||||
|
||||
@itemlist[
|
||||
|
||||
@item{@racket[#:site-dest _path-string] --- destination for
|
||||
completed build, used by the @tt{site} and @tt{snapshot-site}
|
||||
makefile targets; the default is @racket["build/site"]}
|
||||
|
||||
@item{@racket[#:pdf-doc? _boolean] --- whether to build PDF
|
||||
documentation when assembling a site; the default is @racket[#f]}
|
||||
|
||||
@item{@racket[#:email-to (list _string ...)] --- a list of addresses
|
||||
to receive e-mail reporting build results; mail is sent via
|
||||
@exec{sendmail} unless @racket[#:smtp-...] configuration is
|
||||
supplied}
|
||||
|
||||
@item{@racket[#:email-from _string] --- address used as the sender
|
||||
of e-mailed reports; the first string in @racket[#:email-to] is
|
||||
used by default}
|
||||
|
||||
@item{@racket[#:smtp-server _string*],
|
||||
@racket[#:smtp-port _string*],
|
||||
@racket[#:smtp-connect _symbol],
|
||||
@racket[#:smtp-user _string-or-false]
|
||||
@racket[#:smtp-password _string-or-false]
|
||||
--- configuration for sending e-mail through SMTP instead of
|
||||
@exec{sendmail}; the @racket[#:smtp-port] default (@racket[25],
|
||||
@racket[465], or @racket[587]) is picked based on
|
||||
@racket[#:smtp-connect], which can be @racket['plain],
|
||||
@racket['ssl], or @racket['tls] and defaults to @racket['plain];
|
||||
supply a non-@racket[#f] @racket[#:smtp-user] and
|
||||
@racket[#:smtp-password] when authentication is required by the
|
||||
server}
|
||||
|
||||
@item{@racket[#:site-help _hash-table] --- hash table of extra
|
||||
``help'' information for entries on a web page created by the
|
||||
@tt{site} and @tt{snapshot-site} makefile targets; the hash keys
|
||||
are strings for row labels in the download table (after splitting
|
||||
on @litchar{|} and removing @litchar["{"]...@litchar["}"]), and
|
||||
the values are X-expressions (see @racketmodname[xml]) for the
|
||||
help content}
|
||||
|
||||
@item{@racket[#:site-title _string] --- title for the main page
|
||||
generated by the @tt{site} or @tt{snapshot-site} makefile target;
|
||||
the default is @racket["Racket Downloads"]}
|
||||
|
||||
@item{@racket[#:max-snapshots _number] --- number of snapshots to
|
||||
keep, used by the @tt{snapshot-site} makefile target}
|
||||
|
||||
@item{@racket[#:plt-web-style? _boolean] --- indicates whether
|
||||
@racket[plt-web] should be used to generate a site or snapshot
|
||||
page; the default is @racket[#t]}
|
||||
|
||||
]}
|
||||
|
||||
|
||||
@deftogether[(
|
||||
@defproc[(site-config? [v any/c]) boolean?]
|
||||
@defproc[(site-config-tag [config site-config?])
|
||||
(or/c 'machine 'sequential 'parallel)]
|
||||
@defproc[(site-config-options [config site-config?])
|
||||
(hash/c keyword? any/c)]
|
||||
@defproc[(site-config-content [config site-config?])
|
||||
(listof site-config?)]
|
||||
)]{
|
||||
|
||||
Recognize and inspect site configurations.}
|
||||
|
||||
|
||||
@defparam[current-mode s string?]{
|
||||
|
||||
A parameter whose value is the user's requested mode for this
|
||||
configuration, normally as provided via the makefile's
|
||||
@tt{CONFIG_MODE} variable. The default mode is @racket["default"]. The
|
||||
interpretation of modes is completely up to the site configuration
|
||||
file.}
|
||||
|
||||
|
||||
@defproc[(current-stamp) string?]{
|
||||
|
||||
Returns a string to identify the current build, normally a combination
|
||||
of the date and a git commit hash.}
|
||||
|
||||
|
||||
@; ----------------------------------------
|
||||
|
||||
@section{READMEs}
|
||||
|
||||
@defmodule[distro-build/readme]{The
|
||||
@racketmodname[distro-build/readme] library provides functions for
|
||||
constructing a @filepath{README} file's content. Each function takes a
|
||||
hash table mapping configuration keywords to values.}
|
||||
|
||||
@defproc[(make-readme [config hash?]) string?]{
|
||||
|
||||
Produces basic @filepath{README} content, using information about the
|
||||
distribution and the Racket license. The content is constructed using
|
||||
@racket[config] keys such as @racket[#:name], @racket[#:platform],
|
||||
@racket[#:dist-name], and @racket[#:dist-catalogs], and sometimes
|
||||
@racket[current-stamp].}
|
||||
|
||||
|
||||
@defproc[(make-macosx-notes [config hash?]) string?]{
|
||||
|
||||
Produces @filepath{README} content to tell Mac OS X users how to install a
|
||||
distribution folder. This function is used by @racket[make-readme] when
|
||||
@racket[#:platform] in @racket[config] is @racket['macosx].}
|
||||
|
||||
|
||||
@; ----------------------------------------
|
||||
|
||||
@section[#:tag "name-format"]{Names and Download Pages}
|
||||
|
||||
The @racket[#:name] value for an installer is used in an HTML table of
|
||||
download links by the @tt{site} or @tt{snapshot-site} targets. The
|
||||
names are first sorted. Then, for the purposes of building the table,
|
||||
a @litchar["|"] separated by any number of spaces within a name is
|
||||
treated as a hierarchical delimiter, while anything within
|
||||
@litchar["{"] and @litchar["}"] in a hierarchical level is stripped
|
||||
from the displayed name along with surrounding spaces (so that it can
|
||||
affect sorting without being displayed). Anything after
|
||||
@litchar[";\x20"] within a @litchar{|}-separated part is rendered as a
|
||||
detail part of the label (e.g., in a smaller font).
|
||||
|
||||
For example, the names
|
||||
|
||||
@racketblock[
|
||||
"Racket | {2} Linux | 32-bit"
|
||||
"Racket | {2} Linux | 64-bit; built on Ubuntu"
|
||||
"Racket | {1} Windows | 32-bit"
|
||||
"Racket | {1} Windows | 64-bit"
|
||||
"Racket | {3} Source"
|
||||
]
|
||||
|
||||
are shown (actually or conceptually) as
|
||||
|
||||
@verbatim[#:indent 2]|{
|
||||
Racket
|
||||
Windows
|
||||
[32-bit] <built on Ubuntu>
|
||||
[64-bit]
|
||||
Linux
|
||||
[32-bit]
|
||||
[64-bit]
|
||||
[Source]
|
||||
}|
|
||||
|
||||
where the square-bracketed entries are hyperlinks and the
|
||||
angle-bracketed pieces are details.
|
||||
|
||||
@; ----------------------------------------
|
||||
|
||||
@section{Examples}
|
||||
|
||||
Here are some example configuration files.
|
||||
|
||||
@subsection{Single Installer}
|
||||
|
||||
The simplest possible configuration file is
|
||||
|
||||
@codeblock{
|
||||
#lang distro-build/config
|
||||
(machine)
|
||||
}
|
||||
|
||||
In fact, this configuration file is created automatically as
|
||||
@filepath{build/site.rkt} (if the file does not exist already) and
|
||||
used as the default configuration. With this configuration,
|
||||
|
||||
@commandline{make installers}
|
||||
|
||||
creates an installer in @filepath{build/installers} for the platform
|
||||
that is used to create the installer.
|
||||
|
||||
|
||||
@subsection{Installer Web Page}
|
||||
|
||||
To make a web page that serves both a minimal installer and packages,
|
||||
create a @filepath{site.rkt} file with
|
||||
|
||||
@codeblock{
|
||||
#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
|
||||
|
||||
@commandline{make site CONFIG=site.rkt}
|
||||
|
||||
creates a @filepath{build/site} directory that you can move to your
|
||||
web server's @filepath{snapshot} directory, so that
|
||||
@filepath{build/site/index.html} is the main page, and so on.
|
||||
|
||||
|
||||
@subsection{Accumulated Shapshots Web Page}
|
||||
|
||||
To make a web site that provides some number (5, by default) of
|
||||
snapshots, use @racket[(current-stamp)] when constructing the
|
||||
@racket[#:dist-base-url] value. Also, use @racket[(current-stamp)] as
|
||||
the directory for assembling the site:
|
||||
|
||||
@codeblock{
|
||||
#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,
|
||||
|
||||
@commandline{make snapshot-site CONFIG=site.rkt}
|
||||
|
||||
creates a @filepath{build/site} directory that you can move to your web
|
||||
server's @filepath{snapshots} directory, so that @filepath{build/site/index.html} is the
|
||||
main page that initially points to @filepath{build/site/@nonterm{stamp}/index.html},
|
||||
and so on. To make a newer snapshot, update the Git repository, leave
|
||||
@filepath{build/site} in place, and run
|
||||
|
||||
@commandline{make snapshot-site CONFIG=site.rkt}
|
||||
|
||||
again. The new installers will go into a new <stamp> subdirectory, and
|
||||
the main @filepath{index.html} file will be rewritten to point to them.
|
||||
|
||||
|
||||
@subsection{Multiple Platforms}
|
||||
|
||||
A configuration module that drives multiple clients to build
|
||||
installers might look like this:
|
||||
|
||||
@codeblock{
|
||||
#lang distro-build/config
|
||||
|
||||
(sequential
|
||||
#:pkgs '("drracket")
|
||||
#:server-hosts '() ; Insecure? See below.
|
||||
(machine
|
||||
#:desc "Linux (32-bit, Precise Pangolin)"
|
||||
#:name "Ubuntu 32"
|
||||
#:vbox "Ubuntu 12.04"
|
||||
#:host "192.168.56.102")
|
||||
(machine
|
||||
#:desc "Windows (64-bit)"
|
||||
#:name "Windows 64"
|
||||
#: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 @racket["192.168.56.1"]
|
||||
and @racket["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 @filepath{Ubuntu 12.04}). It contacts the server
|
||||
still as @tt{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 @exec{bash}-based SSH server
|
||||
like Cygwin) and communicates back to the server as
|
||||
@racket["10.0.0.1"] instead of using an SSH tunnel. To make that work,
|
||||
@racket[#:server-hosts] is specified as the empty list to make the
|
||||
server listen on all interfaces (instead of just
|
||||
@racket["localhost"])---which is possibly less secure than the default
|
||||
restriction that allows build-server connections only via
|
||||
@racket["localhost"].
|
||||
|
||||
With this configuration file in @filepath{site.rkt},
|
||||
|
||||
@commandline{make installers CONFIG=site.rkt}
|
||||
|
||||
produces two installers, both in @filepath{build/installers}, and a
|
||||
hash table in @filepath{table.rktd} that maps
|
||||
@racket["Linux (32-bit, Precise Pangolin)"] to the Linux installer
|
||||
and @racket["Windows (64-bit)"] to the Windows installer.
|
||||
15
distro-build-doc/info.rkt
Normal file
15
distro-build-doc/info.rkt
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
#lang info
|
||||
|
||||
(define collection "distro-build")
|
||||
|
||||
(define deps '(["base" #:version "6.1.1.6"]
|
||||
"distro-build-server"
|
||||
"distro-build-client"
|
||||
"web-server-lib"))
|
||||
(define build-deps '("at-exp-lib"))
|
||||
|
||||
(define pkg-desc "documentation part of \"distro-build\"")
|
||||
|
||||
(define pkg-authors '(mflatt))
|
||||
|
||||
(define scribblings '(("distro-build.scrbl" (multi-page))))
|
||||
|
|
@ -2,8 +2,10 @@
|
|||
|
||||
(define collection 'multi)
|
||||
|
||||
(define deps '("distro-build-lib"))
|
||||
(define implies '("distro-build-lib"))
|
||||
(define deps '("distro-build-lib"
|
||||
"distro-build-doc"))
|
||||
(define implies '("distro-build-lib"
|
||||
"distro-build-doc"))
|
||||
|
||||
(define pkg-desc "Tools for constructing a distribution of Racket")
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user