On this page:
3.1 API for Distributing Executables
assemble-distribution
3.2 API for Bundling Distributions
bundle-directory
bundle-put-file-extension+  style+  filters

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:

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 compiler/distribute library provides a function to perform the same work as raco distribute.

procedure

(assemble-distribution dest-dir    
  exec-files    
  [#:executables? executables?    
  #:relative-base relative-base    
  #:collects-path path    
  #:copy-collects dirs])  void?
  dest-dir : path-string?
  exec-files : (listof path-string?)
  executables? : any/c = #t
  relative-base : (or/c path-string? #f) = #f
  path : (or/c #f (and/c path-string? relative-path?)) = #f
  dirs : (listof path-string?) = null
Copies the executables in exec-files to the directory dest-dir, along with DLLs, frameworks, shared libraries, and/or runtime files that the executables need to run a different machine. If executables? is #f, then the exec-files are treated as plain data files, instead of executables, and they are modified in-place.

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 compiler/bundle-dist library provides a function to pack a directory (usually assembled by assemble-distribution) into a distribution file. On Windows, the result is a ".zip" archive; on Mac OS, it’s a ".dmg" disk image; on Unix, it’s a ".tgz" archive.

procedure

(bundle-directory dist-file dir [for-exe?])  void?

  dist-file : file-path?
  dir : file-path?
  for-exe? : any/c = #f
Packages dir into dist-file. If dist-file has no extension, a file extension is added automatically (using the first result of bundle-put-file-extension+style+filters).

The created archive contains a directory with the same name as direxcept 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.

procedure

(bundle-put-file-extension+style+filters)

  
(or/c string? #f)
(listof (or/c 'packages 'enter-packages))
(listof (list/c string? string?))
Returns three values suitable for use as the extension, style, and filters arguments to put-file, respectively to select a distribution-file name.