3 raco distribute: Sharing Stand-Alone Executables

The raco distribute command combines a stand-alone executable created by raco exe with all of the shared libraries that are needed to run it, along with any run-time files declared via define-runtime-path. The resulting package can be moved to other machines that run the same operating system.

On Windows and Mac OS, native libraries tend to be included with the output of raco distribute. On Unix platforms, native libraries tend not to be included, so system libraries will be used on the host machine. The difference is whether a Racket installation itself includes bundled native libraries or relies on system-installed libraries. Adding a symbolic link in Racket’s "lib" directory to a system-installed library causes that library to be included with a distribution directory created by raco distribute; see also define-runtime-path.

After the raco distribute command, supply a directory to contain the combined files for a distribution. Each command-line argument is an executable to include in the distribution, so multiple executables can be packaged together. For example, on Windows,

  raco distribute greetings hello.exe goodbye.exe

creates a directory "greetings" (if the directory doesn’t exist already), and it copies the executables "hello.exe" and "goodbye.exe" into "greetings". It also creates a "lib" sub-directory in "greetings" if needed to contain DLLs, and in that case it adjusts the copied "hello.exe" and "goodbye.exe" to use the DLLs in "lib".

The number of needed support files depends in part on the way that executables for a distribution are created. Supplying --embed-dlls or --orig-exe to raco exe reduces the need for support files, but at the expense of making the distribution larger if it contains multiple executables.

The layout of files within a distribution directory is platform-specific:

• On Windows, executables are put directly into the distribution directory, and DLLs and other run-time files go into a "lib" sub-directory.

• On Mac OS, GUI executables go into the distribution directory, other executables go into a "bin" subdirectory, and frameworks (i.e., shared libraries) go into a "lib" sub-directory along with other run-time files. As a special case, if the distribution has a single --gui-exe executable, then the "lib" directory is hidden inside the application bundle.

• On Unix, executables go into a "bin" subdirectory, shared libraries (if any) go into a "lib" subdirectory along with other run-time files, and wrapped executables are placed into a "lib/plt" subdirectory with version-specific names. This layout is consistent with Unix installation conventions; the version-specific names for shared libraries and wrapped executables means that distributions can be safely unpacked into a standard place on target machines without colliding with an existing Racket installation or other executables created by raco exe.

A distribution also has a "collects" directory that is used as the main library collection directory for the packaged executables. By default, the directory is empty. Use the ++collects-copy flag of raco distribute to supply a directory whose content is copied into the distribution’s "collects" directory. The ++collects-copy flag can be used multiple times to supply multiple directories.

When multiple executables are distributed together, then separately creating the executables with raco exe can generate multiple copies of collection-based libraries that are used by multiple executables. To share the library code, instead, specify a target directory for library copies using the --collects-dest flag with raco exe, and specify the same directory for each executable (so that the set of libraries used by all executables are pooled together). Finally, when packaging the distribution with raco distribute, use the ++collects-copy flag to include the copied libraries in the distribution.

3.1 API for Distributing Executables

The arrangement of the executables and support files in dest-dir depends on the platform. In general, assemble-distribution tries to do the Right Thing, but a non-#f value for relative-base specifies a path for reaching the assembled content relative to the executable at run time. When executables? is #f, then the default access path is dest-dir, with its relativeness preserved.

If a #:collects-path argument is given, it overrides the default location of the main "collects" directory for the packaged executables. It should be relative to the dest-dir directory (typically inside it).

The content of each directory in the #:copy-collects argument is copied into the main "collects" directory for the packaged executables.

Changed in version 6.3 of package base: Added the #:executables? and #:relative-base arguments.

3.2 API for Bundling Distributions

The created archive contains a directory with the same name as dir—except on Mac OS when for-exe? is true and dir contains a single a single file or directory, in which case the created disk image contains just the file or directory. The default for for-exe? is #f.

Archive creation fails if dist-file exists.