1 Building Racket from Source
In a checkout of the Racket Git repository , you could try just running
make
but we recommend that you at least consider the information in Git Repository versus Source Distribution and Git Repository Build Modes.
1.1 Git Repository versus Source Distribution
Instead of building from the Git repository, consider getting source for the current Racket release from
or get a source snapshot (updated daily) from
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 the Git repository, release and snapshot source distributions will work in the
configure --prefix=... && make && make install
way that you probably expect.
1.2 Git Repository Build Modes
The rest of this chapter assumes that you’re sticking with the source repository. In that case, you still have several options:
In-place build —
This mode is the default. It creates a build in the "racket" subdirectory and installs packages that you specify (or the "main-distribution" plus "main-distribution-test" package 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 for more instructions. Unix-style install —
This mode installs to a given destination directory (on platforms other than 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 for more instructions. Minimal —
This mode is like a source distribution, and it is described in the "src" subdirectory of "racket" (i.e., ignore the repository’s root directory and "pkgs" subdirectory). 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 —
This mode creates Racket distribution 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 Distributing Racket Variants for more instructions. In-place Racket on Chez Scheme build —
This mode builds using Chez Scheme via make cs. Unless you use various options described in More Instructions: Building Racket on Chez Scheme, this process downloads Chez Scheme from GitHub, builds a traditional racket with minimal packages, builds Chez Scheme, and then builds Racket on Chez Scheme using Racket and Chez Scheme. Final executables with names that end in cs or CS are the Racket on Chez Scheme variants.
1.3 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 2019/16.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.txt".
On Windows with MinGW, use 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 for more information.
1.4 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 the 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 for more information.
1.5 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="‹options›" to make in-place or make unix-style. (The _qq suffix on the variable name CONFIGURE_ARGS_qq 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.
1.6 More Instructions: Building Racket on Chez Scheme
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 Scheme 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=‹dir› instead of downloading a new copy:
make cs RACKET=racket SCHEME_SRC=path/to/ChezScheme
For now, Racket on Chez requires the variant of Chez Scheme at https://github.com/racket/ChezScheme
Use make both to build both traditional Racket and Racket on Chez Scheme, where packages are updated and documentation is built only once (using traditional Racket).
1.7 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.
1.7.1 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, from 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="‹options›" 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="‹exec› -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=‹options› 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.
1.7.2 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›
1.7.3 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 ‹path›.
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 in the repository root.