3 raco distribute: Sharing Stand-Alone Executables

▼ |  | raco: Racket Command-Line Tools

1 | raco make: Compiling Source to Bytecode
2 | raco exe: Creating Stand-Alone Executables
3 | raco distribute: Sharing Stand-Alone Executables
4 | raco planet: Automatic Package Distribution
5 | raco pkg: Package Management
6 | raco setup: Installation Management
7 | raco decompile: Decompiling Bytecode
8 | raco demod: Demodularizing Programs
9 | raco link: Library Collection Links
10 | raco pack: Packing Library Collections
11 | raco unpack: Unpacking Library Collections
12 | raco ctool: Working with C Code
13 | raco test: Run tests
14 | raco docs: Documentation Search
15 | raco expand: Macro Expansion
16 | raco read: Reading and Pretty-Printing
17 | raco scribble: Building Documentation
18 | Adding a raco Command
19 | Installation Configuration and Search Paths

► | 3 | raco distribute: Sharing Stand-Alone Executables

3.1 | API for Distributing Executables
3.2 | API for Bundling Distributions

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

top contents ← prev up next →

### 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🔗ℹ

(require compiler/distribute) | package: base

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🔗ℹ

(require compiler/bundle-dist) | package: compiler-lib

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 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.

> 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.
top contents ← prev up next →