Building a Standalone Racket Executable with raco exe

Desired Outcome

Produce a single platform specific executable that runs a Racket program without requiring a separate Racket installation.

Prerequisites

• A working Racket installation (version 6.0 or later) providing the racket and raco commands.
• The source file you want to bundle, for example myapp.rkt.
• Access to a terminal or command prompt with permission to write files in the target directory.

Procedure

1. Open a terminal and navigate to the directory containing the source file.
2. Determine whether the program uses GUI components. If the source begins with #lang racket/gui or creates windows, you must build a GUI executable; otherwise a console executable is sufficient.
3. Run the raco exe command. For a console executable:

raco exe -o  .rkt

Replace with the desired executable name (for example myapp) and with the base name of your source file.

4. If you need a GUI executable, add the -gui flag:

raco exe -gui -o  .rkt

5. Optional: preserve the original source filename for debugging with --orig-exe:

raco exe --orig-exe -o  .rkt

6. Optional: reduce the binary size. After building, you can run strip (on Unix) or upx if available:

strip 

or

upx 

Expected Checks

1. Run the generated executable on a machine that does not have Racket installed. For a console program, verify that its output matches the output of racket .rkt.
2. Check the file type with platform specific tools. On Unix like systems:

file 

should report something like ELF 64 bit LSB executable, x86 64 for Linux or Mach O 64 bit executable x86_64 for macOS.

3. On Windows, use sigcheck or the file properties to confirm it is a PE executable for the correct architecture (x86 or x64).
4. If the program uses GUI, launch the executable and confirm that a window appears and responds to interaction. Absence of a window usually indicates the -gui flag was omitted or the source does not declare #lang racket/gui.

Recovery Options

• If the executable fails with a missing library error, locate the required DLL or .so file referenced via ffi/unsafe and either copy it alongside the executable or bundle it manually.
• If the program behaves differently than when run with racket, rebuild without optimization flags (the default raco exe already uses the standard compilation level).
• To start over, delete the generated executable (rm on Unix or del .exe on Windows) and repeat the procedure.