custom-load:   Cautious Bytecode Loaders
1 Custom Compiled-Load Handlers
make-custom-load/  use-compiled
2 Automatic Installation of Loader

custom-load: Cautious Bytecode Loaders

Ryan Culpepper <>

This package provides a function for building compiled-load handlers that avoid loading stale ".zo" files, thus avoiding errors of the form “link: module mismatch.”

To be more precise, a “link: module mismatch” error arises when Racket loads a ".zo" file with an ancestor whose ".zo" file is stale or missing; the ancestor is recompiled in a way inconsistent with the descendant, but it is too late to recompile to descendant, because its bytecode is already loaded. The handlers produced by this library recursively check ancestors before loading a descendant’s ".zo" file.

This library uses a logger named custom-load; to see its output, try setting PLTSTDERR="info@custom-load".

1 Custom Compiled-Load Handlers

 (require custom-load) package: custom-load


(make-custom-load/use-compiled [#:blacklist blacklist 
  #:load-zo load-zo 
  #:load-src load-src]) 
(-> path?
    (or/c #f symbol? (cons/c (or/c #f symbol?) (listof symbol?)))
  blacklist : (treeof (or/c regexp? (-> path? any/c)))
   = (lambda (file) #f)
  load-zo : 
(-> path?
    (or/c #f symbol? (cons/c (or/c #f symbol?) (listof symbol?)))
   = (current-load/use-compiled)
  load-src : 
(-> path?
    (or/c #f symbol? (cons/c (or/c #f symbol?) (listof symbol?)))
   = (lambda (file want) ((current-load) file want))
Returns a function, loader, suitable for use as a compiled-load handlerthat is, as a value of the current-load/use-compiled parameter.

When loader is called to load file, it performs the following checks, loading the ".zo" version of file only if all of them pass.

To load file from source, loader calls (load-src file what), where what is the module or submodule requested (see compiled-load handler). The current-load-relative-directory parameter is first set to the directory containing file.

To load file from ".zo" file, loader calls (load-zo file name). Note that load-zo is called with the original file, not with the zo-file; thus the previous value of (current-load/use-compiled) is an appropriate value of load-zo.

The blacklist argument is useful when using an instrumenting compiler that intercepts loads of certain modules and recompiles them after performing some sort of instrumentation. Examples include debuggers, profilers, and coverage testers. Set the blacklist argument to a predicate that recognizes the files to be instrumented and supply the following function for load-src:

(lambda (file what)
  (cond [(blacklist? file)
         ; compile this file with instrumentation
         ((current-load) file what)]))

As an alternative to supplying a load-src argument, you can also override current-load, chaining to the previous value in the default branch.

2 Automatic Installation of Loader

 (require custom-load/top) package: custom-load

Requiring the custom-load/top module automatically installs a custom loader as the value of current-load/use-compiled, using the old value as the load-zo argument.

You can also run a program with a custom loader using a command line like racket -l custom-load/top -t program.rkt.


(current-zo-blacklist)  (-> path? any/c)

(current-zo-blacklist pred)  void?
  pred : (treeof (or/c (-> path? any/c) regexp?))
Parameter holding the zo blacklist predicate used by the compiled-load handler installed by custom-load/top.