Build Options

=============

Instead of using this source repository, consider getting source for

the current Racket release from

http://download.racket-lang.org/

or get a source snapshot (updated daily) from

http://pre.racket-lang.org/installers/

The "Source + built packages" options from those sites will build and

install especially quickly, because platform-independent bytecode and

documentation are pre-built.

In contrast to this repository, release and snapshot source

distributions will work in the

configure --prefix=... && make && make install

way that you probably expect.

If you stick with this repository, then you have several options:

* In-place build --- the default, creates a build in the "racket"

subdirectory and installs packages that you specify, or

"main-distribution" plus "main-distribution-test" by default. Any

package implementations that reside in the "pkgs" subdirectory are

linked in place. This is the most natural mode for developing

Racket itself or staying on the bleeding edge. See "Quick

Instructions: In-place Build" below.

* Unix-style install --- installs to a given destination directory

(on platforms other Windows), leaving no reference to the source

directory. This is the most natural mode for installing once from

the source repository. See "Quick Instructions: Unix-style Install"

below.

* Minimal --- as described in the "src" subdirectory of "racket"

(i.e., ignore this directory and "pkgs"). You can build a minimal

Racket using the usual `configure && make && make install` steps

(or similar for Windows), and then you can install packages from

the catalog server with `raco pkg`.

* Installers --- create installers for a variety of platforms by

farming out work to machines that run those platforms. This is the

way that Racket snapshots and releases are created, and you can

create your own. See "Building Installers" below.

* In-place Racket-on-Chez build --- when you use `make cs`. Unless

you use various options described in "More Instructions: Building

Racket-on-Chez" below, this process downloads Chez Scheme from

GitHub, builds a traditional `racket` with minimal packages, builds

Chez Scheme, and then builds Racket-on-Chez using Racket and Chez

Scheme. Final executables that end in "cs" or "CS" are the

Racket-on-Chez variants.

Quick Instructions: In-place Build

==================================

On Unix (including Linux) and Mac OS, `make` (or `make in-place`)

creates a build in the "racket" directory.

On Windows with Microsoft Visual Studio (any version between 2008/9.0

and 2017/15.0), `nmake win32-in-place` creates a build in the "racket"

directory. For information on configuring your command-line

environment for Visual Studio, see "racket/src/worksp/README".

On Windows with MinGW, `make PLAIN_RACKET=racket/racket`, since MinGW

uses Unix-style tools but generates a Windows-layout Racket build.

In all cases, an in-place build includes (via links) a few packages

that are in the "pkgs" directory. To get new versions of those

packages, as well as the Racket core, then use `git pull`. Afterward,

or to get new versions of any other package, use `make in-place`

again, which includes a `raco pkg update` step.

See "More Instructions: Building Racket" below for more information.

Quick Instructions: Unix-style Install

======================================

On Unix (including Linux), `make unix-style PREFIX=<dir>` builds and

installs into "<dir>" (which must be an absolute path) with binaries

in "<dir>/bin", packages in "<dir>/share/racket/pkgs", documentation

in "<dir>/share/racket/doc", etc.

On Mac OS, `make unix-style PREFIX=<dir>` builds and installs into

"<dir>" (which must be an absolute path) with binaries in "<dir>/bin",

packages in "<dir>/share/pkgs", documentation in "<dir>/doc", etc.

On Windows, Unix-style install is not supported.

A Unix-style install leaves no reference to this source directory.

To split the build and install steps of a Unix-style installation,

supply `DESTDIR=<dest-dir>` with `make unix-style PREFIX=<dir>`, which

assembles the installation in "<dest-dir>" (which must be an absolute

path). Then, copy the content of "<dest-dir>" to the target root

"<dir>".

See "More Instructions: Building Racket" below for more information.

More Instructions: Building Racket

==================================

The "racket" directory contains minimal Racket, which is just enough

to run `raco pkg` to install everything else. The first step of `make

in-place` or `make unix-style` is to build minimal Racket, and you can

read "racket/src/README" for more information.

If you would like to provide arguments to `configure` for the minimal

Racket build, then you can supply them with by adding

`CONFIGURE_ARGS_qq="..."` to `make in-place` or `make

unix-style`. (The `_qq` suffix on the variable name is a convention

that indicates that single- and double-quote marks are allowed in the

value.)

The "pkgs" directory contains packages that are tied to the Racket

core implementation and are therefore kept in the same Git

repository. A `make in-place` links to the package in-place, while

`make unix-style` copies packages out of "pkgs" to install them.

To install a subset of the packages in "pkgs", supply `PKGS` value to

`make`. For example,

make PKGS="gui-lib readline-lib"

links only the "gui-lib" and "readline-lib" packages and their

dependencies. The default value of `PKGS` is "main-distribution

main-distribution-test". If you run `make` a second time, all

previously installed packages remain installed and are updated, while

new packages are added. To uninstall previously selected package, use

`raco pkg remove`.

To build anything other than the latest sources in the repository

(e.g., when building from the "v6.2.1" tag), you need a catalog

that's compatible with those sources. Note that a release distribution

is configured to use a catalog specific to that release, so you can

extract the catalog's URL from there.

Using `make` (or `make in-place`) sets the installation's name to

"development", unless the installation has been previously configured

(i.e., unless the "racket/etc/config.rktd" file exists). The

installation name affects, for example, the directory where

user-specific documentation is installed. Using `make` also sets the

default package scope to `installation`, which means that

packages are installed by default into the installation's space instead

of user-specific space. The name and/or default-scope configuration

can be changed through `raco pkg config`.

Note that `make -j <n>` controls parallelism for the makefile part of

a build, but not for the `raco setup` part. To control both the

makefile and the `raco setup` part, use

make CPUS=<n>

which recurs with `make -j <n> JOB_OPTIONS="-j <n>"`. Setting `CPUS`

also works with `make unix-style`.

Use `make as-is` (or `nmake win32-as-is`) to perform the same build

actions as `make in-place`, but without consulting any package

catalogs or package sources to install or update packages. In other

words, use `make as-is` to rebuild after local changes that could

include changes to the Racket core. (If you change only packages, then

`raco setup` should suffice.)

If you need even more control over the build, carry on to "Even More

Instructions: Building Racket Pieces" further below.

More Instructions: Building Racket-on-Chez

==========================================

The `make cs` target (or `make cs-as-is` for a rebuild, or `nmake

win32-cs` on Windows with Visual Studio) builds a variant of Racket

that runs on Chez Scheme. By default, the executables for the

Racket-on-Chez variant all have a "cs" or "CS" suffix, and they

coexist with a traditional Racket build by keeping compiled files in a

machine-specific subdirectory of the "compiled" directory. You can

remove the "cs" suffix and the subdirectory in "compiled" by providing

`RACKETCS_SUFFIX=""` to `make`. (One day, if all goes well, the

default for `RACKETCS_SUFFIX` will change from "cs" to "".)

Building Racket-on-Chez requires an existing Racket and Chez Scheme.

If you use `make cs` with no further arguments, then the build process

will bootstrap by building a traditional variant of Racket and by

downloading and building Chez Scheme.

If you have a sufficiently recent Racket installation already with at

least the "compiler-lib" package installed, you can supply

`RACKET=...` with `make cs` to skip that part of the bootstrap. And if

you have a Chez Scheme source directory already[*], you can supply

that with `SCHEME_SRC=...` instead of downloading a new copy.

make cs RACKET=racket SCHEME_SRC=path/to/ChezScheme

Use `make both` to build both traditional Racket and Racket-on-Chez,

where packages are updated documentation is built only once (using

traditional Racket).

[*] For now, Racket-on-Chez requires the variant of Chez Scheme at

https://github.com/racket/ChezScheme

Even More Instructions: Building Racket Pieces

==============================================

Instead of just using `make in-place` or `make unix-style`, you can

take more control over the build by understanding how the pieces fit

together.

Building Minimal Racket

-----------------------

Instead of using the top-level makefile, you can go into "racket/src"

and follow the "README.txt" there, which gives you more configuration

options.

If you don't want any special configuration and you just want the base

build, you can use `make base` (or `nmake win32-base`) with the

top-level makefile.

Minimal Racket does not require additional native libraries to run,

but under Windows, encoding-conversion, extflonum, and SSL

functionality is hobbled until native libraries from the

`racket-win32-i386` or `racket-win32-x86_64` package are installed.

On all platforms, fom the top-level makefile, `JOB_OPTIONS` as a

makefile variable and `PLT_SETUP_OPTIONS` as an environment variable

are passed on to the `raco setup` that is used to build minimal-Racket

libraries. See the documentation for `raco setup` for information on

the options.

For cross compilation, add configuration options to

`CONFIGURE_ARGS_qq="..."` as described in the "README.txt" of

"racket/src", but also add a `PLAIN_RACKET=...` argument for the

top-level makefile to specify the same executable as in an

`--enable-racket=...` for `configure`. In general, the `PLAIN_RACKET`

setting should have the form `PLAIN_RACKET="... -C"` to ensure that

cross-compilation mode is used and that any foreign libraries needed

for build time can be found, but many cross-compilation scenarios work

without `-C`.

Specify `SETUP_MACHINE_FLAGS=...` to set Racket flags that control the

target machine of compiled bytecode for `raco setup` and `raco pkg

install`. For example `SETUP_MACHINE_FLAGS=-M` causes the generated

bytecode to be machine-independent, which is mainly useful when the

generated installation will be used as a template for other platforms

or for cross-compilation.

Installing Packages

-------------------

After you've built and installed minimal Racket, you could install

packages via the package-catalog server, completely ignoring the

content of "pkgs".

If you want to install packages manually out of the "pkgs" directory,

the `local-catalog` target creates a catalog as "racket/local/catalog"

that merges the currently configured catalog's content with pointers

to the packages in "pkgs". A Unix-style build works that way: it

builds and installs minimal Racket, and then it installs packages out

of a catalog that is created by `make local-catalog`.

To add a package catalog that is used after the content of "pkgs" but

before the default package catalogs, specify the catalog's URL as the

`SRC_CATALOG` makefile variable:

make .... SRC_CATALOG=<url>

Linking Packages for In-place Development Mode

----------------------------------------------

With an in-place build, you can edit packages within "pkgs" directly

or update those packages with `git pull` plus `raco setup`, since the

packages are installed with the equivalent of `raco pkg install -i

--static-link ...`.

Instead of actually using `raco pkg install --static-link ...`, the

`pkgs-catalog` makefile target creates a catalog that points to the

packages in "pkgs", and the catalog indicates that the packages are to

be installed as links. The `pkgs-catalog` target further configures

the new catalog as the first one to check when installing

packages. The configuration adjustment is made only if no

configuration file "racket/etc/config.rktd" exists already.

All other packages (as specified by `PKGS`) are installed via the

configured package catalog. They are installed in installation scope, but

the content of "racket/share/pkgs" is not meant to be edited. To

reinstall a package in a mode suitable for editing and manipulation

with Git tools, use

raco pkg update --clone extra-pkgs/<pkg-name>

The "extra-pkgs" directory name is a convention that is supported by a

".gitignore" entry.

The Whole Enchilada: Building Installers

========================================

To build installers that can be distributed to other users, do not use

`make in-place` or `make unix-style`, but instead start from a clean

repository.

Use one non-Windows machine as a server, where packages will be

pre-built. Then, as described below, create platform-specific

installers on N client machines, each of which contacts the server

machine to obtain pre-built packages. The server can act as a client,

naturally, to create an installer for the server's platform.

GNU `make` is required on the server machine, `nmake` is required on

Windows client machines, and any `make` should work on other client

machines.

Running Build Farms

-------------------

The `installers` target of the makefile will do everything to generate

installers: build a server on the current machine, run clients on

hosts specified via `CONFIG`, and start/stop VirtualBox virtual machines

that act as client machines.

See the documentation of the "distro-build" package for a description

of the site-configuration module and requirements on client hosts.

If "my-site-config.rkt" is a configuration module, then

make installers CONFIG=my-site-config.rkt

drives the build farm, and the resulting installers are in

"build/installers", with a hash table mapping descriptions to

installer filenames in "build/installer/table.rktd". A log file

for each client is written to "build/log".

If you have the "distro-build-server" package installed in some Racket

build (not the one for building installers), you can use

make describe-clients CONFIG=my-site-config.rkt

to see, without building anything, the effect of the configuration and

the planned build steps.

The default `CONFIG` path is "build/site.rkt", so you could put your

configuration file there and omit the `CONFIG` argument to `make`. A

default configuration file is created there automatically. Supply

`CONFIG_MODE=...` to pass a configuration mode on to your

site-configuration module (accessible via the `current-mode`

parameter). Supply `CLEAN_MODE=--clean` to make the default `#:clean?`

configuration for a client #t instead of #f, supply

`RELEASE_MODE=--release` to make the default `#:release?`

configuration #t, supply `SOURCE_MODE=--source` to make the default

`#:source?` configuration #t, and supply `VERSIONLESS_MODE=--version`

to make the default `#:versionless?` configuration #t.

A configuration file can specify the packages to include, host address

of the server, distribution name, installer directory, and

documentation search URL, but defaults can be provided as `make`

arguments via `PKGS`, `SERVER` plus `SERVER_PORT` plus `SERVER_HOSTS`,

`DIST_NAME`, `DIST_BASE`, and `DIST_DIR`, `DOC_SEARCH`,

respectively. The site configuration's top-level options for packages

and documentation search URL are used to configure the set of packages

that are available to client machines to include in installers.

For each installer written to "build/installers", the installer's name

is

<dist-base>-<version>-<platform>-<dist-suffix>.<ext>

where <dist-base> defaults to "racket" (but can be set via

`DIST_BASE`), <platform> is from `(system-library-subpath #f)` but

normalizing the Windows results to "i386-win32" and "x86_63-win32",

-<dist-suffix> is omitted unless a `#:dist-suffix` string is specified

for the client in the site configuration, and <ext> is

platform-specific: ".sh" for Unix (including Linux), ".dmg" or ".pkg"

for Mac OS, and ".exe" for Windows.

The server supports both 'cs and '3m clients by creating built

packages in machine-independent form (which is then recompiled to the

client's native format, still much faster than compiling from source).

Set `SERVER_COMPILE_MACHINE=` to disable machine-independent format

for built packages.

Generating Installer Web Sites

------------------------------

The `site` target of the makefile uses the `installers` target to

generate a set of installers, and then it combines the installers,

packages, a package catalog, and log files into a directory that is

suitable for access via a web server.

Supply the same `CONFIG=...` and `CONFIG_MODE=...` arguments for

`site` as for `installers`. The configuration file should have a

`#:dist-base-url` entry for the URL where installers and packages will

be made available; the `installers` target uses `#:dist-base-url` to

embed suitable configuration into the installers. Specifically,

installers are configured to access pre-built packages and

documentation from the site indicated by `#:dist-base-url`.

Note that `#:dist-base-url` should almost always end with "/", since

others URLs will be constructed as relative to `#:dist-base-url`.

The site is generated as "build/site" by default. A `#:site-dest`

entry in the configuration file can select an alternate destination.

Use the `site-from-installers` makefile target to perform the part of

`site` that happens after `installers` (i.e., to generate a `site`

from an already-generated set of installers).

Managing Snapshot Web Sites

---------------------------

The `snapshot-site` makefile target uses `site` (so supply the same

`CONFIG=...` and `CONFIG_MODE=...` arguments), and then treats the

resulting site as a snapshot with additional snapshot-management

tasks.

For snapshot management, the destination of the files generated for

`site` (as specified by `#:site-dest`) should be within a directory of

snapshots. The configuration file can use `(current-stamp)` to get a

string that represents the current build, and then use the string both

for `#:dist-base-url` and `#:site-dest`. Normally, the stamp string is

a combination of the date and Git commit hash.

Snapshot management includes creating an "index.html" file in the

snapshots directory (essentially a copy of the snapshot's own

"index.html") and pruning snapshot subdirectories to keep the number

of snapshots at the amount specified by `#:max-snapshots`

configuration-file entry (with a default value of 5).

Use the `snapshot-at-site` makefile target to perform the part of

`snapshot-site that happens after `site (i.e., to manage snapshots

around an already-generated site).

Separate Server and Clients

---------------------------

Instead of using the `installers` makefile target and a site

configuration file, you can run server and client processes manually.

Roughly, the steps are

1. On the server machine:

make server PKGS="..."

See 1b below for more information on variables other than `PKGS`

that you can provide with `make`.

2. On each client machine:

make client SERVER=... PKGS="..."

or

nmake win32-client SERVER=... PKGS="..."

See 2b below for more information on variables other than `SERVER`

and `PKGS` that you can provide with `make`.

In more detail:

1a. Build "racket" on a server.

The `base` target of the makefile will do that, if you haven't

done it already. (The server only works on non-Windows platforms,

currently.)

1b. On the server, build packages and start a catalog server.

The `server-from-base` target of the makefile will do that.

Alternatively, use the `server` target, which combines `base` and

`server-from-base` (i.e., steps 1a and 1b).

The `SERVER_PORT` variable of the makefile choose the port on

which the server listens to clients. The default is port 9440.

The `SERVER_HOSTS` variable of the makefile determines the

interfaces at which the server listens. The default is

"localhost" which listens only on the loopback device (for

security). Supply the empty string to listen on all

interfaces. Supply multiple addresses by separating them with a

comma.

The `PKGS` variable of the makefile determines which packages are

built for potential inclusion in a distribution.

The `DOC_SEARCH` variable of the makefile determine a URL that is

embedded in rendered documentation for cases where a remote

search is needed (because other documentation is not installed).

The `SRC_CATALOG` variable determines the catalog that is used to

get package sources and native-library packages. The default is

"http://pkgs.racket-lang.org".

The `SERVER_PKG_INSTALL_OPTIONS` variable determines extra flags

that are passed to `raco pkg install` when installing on the

server (to create package builds that are sent to clients). For

example, `SERVER_PKG_INSTALL_OPTIONS=--source` could be useful

to ensure that the server always builds from sources.

The `PACK_BUILT_OPTIONS` variable can be set to `--mode <mode>`

to set the package mode for built packages. The default `infer`

mode infers uses the package's `distribution-preference`

"info.rkt" field, if any, infers `binary` if the package has any

native libraries and no Racket sources, and infers `built`

otherwise.

The server provides README files from the "build/readmes"

directory. If "README.txt" does not exist when the sever is

started, a default file is created (and clients download

"README.txt" by default).

If you stop the server and want to restart it, use the

`built-package-server` makefile target instead of starting over

with the `server` target.

2a. On each client (one for each platform to bundle), build "racket".

This is the same as step 1, but on each client. If the client and

server are the same, there's nothing more to do for step 3.

2b. On each client, create an installer.

The `client` (or `win32-client`) target of the makefile will do

that.

Provide `SERVER` as the hostname of the server machine, but a

"localhost"-based tunnel back to the server is more secure and

avoids the need to specify `SERVER_HOSTS` when starting the

server in step 1b. Also, provide `SERVER_PORT` if an alternate

port was specified in step 1b.

Provide the same `PKGS` (or a subset) as in step 1b if you want a

different set than the ones listed in the makefile. Similarly,

`DOC_SEARCH` normally should be the same as in step 1b, but for a

client, it affects future documentation builds in the

installation.

Alternatively, use the `client` target, which combines `base` and

`client-from-base` (i.e., steps 2a and 2b).

On Windows, you need NSIS installed, either in the usual location

or with `makensis` in your command-line path.

To create a release installer, provide `RELEASE_MODE` as

"--release" to `make`. A release installer has slightly different

defaults that are suitable for infrequently updated release

installations, as opposed to frequently updated snapshot

installations.

To create a source archive, provide `SOURCE_MODE` as "--source"

to `make`.

To create an archive that omits the version number and also omit

and version number in installer paths, provide `VERSIONLESS_MODE` as

"--versionless" to `make`.

To change the human-readable name of the distribution as embedded

in the installer, provide `DIST_NAME` to `make`. The default

distribution name is "Racket". Whatever name you pick, the Racket

version number is automatically added for various contexts.

To change the base name of the installer file, provide `DIST_BASE`

to `make`. The default is "racket".

To change the directory name for installation on Unix (including

Linux), provide `DIST_DIR` to `make`. The default is "racket".

To add an extra piece to the installer's name, such as an

identifier for a variant of Linux, provide `DIST_SUFFIX` to

`make`. The default is "", which omits the prefix and its

preceding hyphen.

To set the description string for the installer, provide

`DIST_DESC` to `make`. The description string is recorded

alongside the installer.

To set the initial package catalogs URLs for an installation,

provide `DIST_CATALOGS_q` to `make`. Separate multiple URLs with

a space, and use an empty string in place of a URL to indicate

that the default catalogs should be used. The "_q" in the

variable name indicates that its value can include double quotes

(but not single quotes) --- which are needed to specify an empty

string, for example.

To select a "README" file for the client, provide `README` to

`make`. The `README` value is used as a file name to download

from the server.

To create a ".tgz" archive instead of an installer (or any

platform), set `TGZ_MODE` to "--tgz".

For a Mac OS installer, set `SIGN_IDENTITY` as the name to

which the signing certificate is associated. Set `MAC_PKG_MODE`

to "--mac-pkg" to create a ".pkg" installer instead of a ".dmg"

image.

For a Windows installer, set `OSSLSIGNCODE_ARGS_BASE64` as a

Base64 encoding of an S-expression for a list of argument strings

for `osslsigncode`. The `-n`, `-t`, `-in`, and `-out` arguments

are provided to `osslsigncode` automatically, so supply the

others.

The `SERVER_CATALOG_PATH` and `SERVER_COLLECTS_PATH` makefile

variables specify paths at `SERVER` plus `SERVER_PORT` to access

the package catalog and pre-built "collects" tree needed for a

client, but those paths should be empty for a server started with

`make server`, and they are used mainly by `make

client-from-site` (described below).

The `UPLOAD` makefile variable specifies a URL to use as an

upload destination for the created installed, where the

installer's name is added to the end of the URL, or leave as

empty for no upload.

On each client, step 2b produces a "bundle/installer.txt" file that

contains the path to the generated installer on one line, followed by

the description on a second line. The installer is also uploaded to

the server, which leaves the installer in a "build/installers"

directory and records a mapping from the installer's description to

its filename in "build/installers/table.rktd".

If you provide `JOB_OPTIONS=...` for either a client or server build,

the options are used both for `raco setup` and `raco pkg

install`. Normally, `JOB_OPTIONS` is used to control parallelism.

Creating a Client from an Installer Web Site

--------------------------------------------

If you (or someone else) previously created an installer site with

`make site`, then `make client-from-site` in a clean repository

creates an installer for the current platform drawing packages

from the site.

At a minimum, provide `SERVER`, `SERVER_PORT` (usually 80), and

`SITE_PATH` (if not empty, include a trailing "/") makefile variables

to access a site at

http://$(SERVER):$(SERVER_PORT)/$(SITE_PATH)

The `client-from-site` makefile target chains to `make client` while

passing suitable values for `DIST_CATALOGS_q`, `DOC_SEARCH`,

`SERVER_CATALOG_PATH`, and `SERVER_COLLECTS_PATH`. Supply any other

suitable variables, such as `DIST_NAME` or `RELEASE_MODE`, the same as

for `make client`.