Cross-Compilation and Multi-Version Manager:   raco cross
1 Platforms, Versions, and Workspaces for raco cross
2 Running raco cross
3 Snapshots and raco cross
4 Dealing with Missing Installers
8.2

Cross-Compilation and Multi-Version Manager: raco cross

The raco cross command (implemented in the "raco-cross" package) provides a convenient interface to cross-compilation for Racket. It’s especially handy generating executables that run on platforms other than the one used to create the executable.

For example,

  raco cross --target x86_64-linux exe example.rkt

creates an executable named "example" that runs on x86_64 Linux. That is, it sets up a combination of distributions for the current platform and for the x86_64-linux platform, and it runs raco exe as if from the local x86_64-linux installation.

For Racket CS, cross-building executables works for version 8.1.0.6 and later. For Racket BC, cross-build executables works for 7.0 and later. The specific platforms available as cross-compilation targets depends on the set of distributions that are available from an installer site.

The generated "example" executable is not necessarily portable by itself to other machines. As is generally the case with raco exe, the executable needs to be turned into a distribution with raco dist (which is also supplied by the "compiler-lib" package):

  raco cross --target x86_64-linux dist example-dist example

The result directory "example-dist" is then ready to be copied to a x86_64 Linux machine and run there.

Since raco cross depends on facilities for managing Racket implementations for different versions and platforms, it can also act as a launcher for a selected native implementation of Racket. For example,

  raco cross --version 7.8 racket

installs and runs a minimal installation of Racket version 7.8 for the current platform (assuming that the combination of version, platform, and virtual machine is available).

Use the --native flag to create an installation for a platform other than the current machine’s default, but where the current machine can run executables directly. For example, on Windows where raco runs a 64-bit Racket build,

  raco cross --native --platform i383-win32 --vm bc racket

installs and runs a 32-bit build of Racket BC for Windows and runs it directly.

1 Platforms, Versions, and Workspaces for raco cross

The raco cross command takes care of the following tasks:

The version and CS/BC variant of Racket where "raco-cross" is installed and run doesn’t need to be related to the target version and variant. The raco cross command will download and install a version and variant of Racket for the current machine as needed.

The Racket distributions that are downloaded and managed by raco cross are installed in a workspace directory. A workspace directory is tied to a specific Racket version. By default, the workspace directory is (build-path (find-system-path 'addon-dir) "raco-cross" vers) where vers is the specified version. The workspace directory is independent of the Racket installation that is used to run raco cross.

When building for a given target, often packages need to be installed via raco cross only for that target. In some cases, however, compilation may require platform-specific native libraries, and the packages must also be installed for the host platform via raco cross (with no --target flag). For example, if compiling a module requires rendering images at compile time, then
  raco cross pkg install draw-lib
most likely will be needed to install the packages for the current machine, as well as
  raco cross --target target pkg install draw-lib
to install for the target platform.

Cross-compilation support depends on having suitable distributions for both the host platform and the target platform. (Use --browse to check which are available, and see also Dealing with Missing Installers.) Some operating systems support more than one platform at a time, and it may be necessary to select a specific host platform to work with a particular target platform. For example, Mac OS on Apple Silicon can run both aarch64-macosx and x86_64-macosx natively, and distribution bundles for Racket BC tend to be available only for x86_64-macosx, so --target x86_64-win32 --vm bc may require --host x86_64-macosx. The --host for a combination of target platform, virtual machine, and version is recorded when the target distribution is installed, so --host is needed only the first time. If the host distribution is already installed, it must be installed as a native distribution.

2 Running raco cross

The general form to run raco cross is
  raco cross option ... command arg ...
which is analogous to running
  raco command arg ...
but with a cross-compilation mode selected by the options. As a special case, command can be racket, which is analogous to running just racket instead of raco racket. Finally, you can omit the command and args, in which case raco cross just downloads and prepares the workspace’s distribution for the target configuration. A target configuration is a combination of platform, version, virtual machine, and whether compiling to machine-independent form.

The following options are recognized:

3 Snapshots and raco cross

By default, raco cross uses a --version argument to locate a suitable distribution from the main Racket download mirror. You can specify an alternative download site with --installers, but at snapshots sites, the Racket version number changes both too quickly too be a convenient designation of the build and too slowly to reliably distinguish the build.

Snapshot sites normally have a main page that provides links with “current” instead of the version number, and they also have build-specific pages (with a hash code and/or date in the URL) to provide the same links. The build-specific pages persist for a few days or weeks, depending on the snapshot site, while the main page turns over more quickly.

The best way to work with snapshots in raco cross is to give each one its own workspace, instead of using the default workspace. That way, you can use current as the version, and you can adjust --installers and --workspace together as suits your purpose.

For example, to run the last Racket from the Utah snapshot, you could write

  raco cross \

   --installers https://www.cs.utah.edu/plt/snapshots/current/installers/ \

   --version current \

   --workspace /tmp/todays-snapshot \

   racket

The version and installers URL are recorded with a workspace, so those only need to be specified the first time that the workspace is used.

The Utah snapshot updates daily, so tomorrow, throw away "/tmp/todays-snapshot" and start again. If, instead, you need to work with a snapshot build for a few days, locate the snapshot ID at the bottom of the main snapshot page, and use that in a more persistent workspace:

  raco cross \

   --installers https://www.cs.utah.edu/plt/snapshots/20210512-8b4b6cf/installers/ \

   --version current \

   --workspace /home/mflatt/snapshots/20210512-8b4b6cf \

   racket

4 Dealing with Missing Installers

If the download site does not include an installer for your host platform, and if it’s a Unix-like host platform with conventional build tools installed, then a host Racket installation can be created with --use-source.

For target platforms, raco cross does not directly support building form source. To build your own: