Previous: Module Monkey, Up: Module System Internals

36.3.3 Prior Suffering

This section describes how to support usage of fixed global bindings for the module system internals, and how to migrate a site installation away from that. New code should use the module interface to the module system internals (see Module Monkey).

36.3.3.1 Migration phases

Normally there are three phases to a migration, carried out by the site administrator, and implemented by creating/modifying the init file in the site directory: $(GUILE_SITE)/init.scm. This is done by adding to this file the use-modules form: 

     (use-modules (ice-9 module-system-compat))

and a properly configured call to the activation proc activate-global-module-system-bindings!.

Phase 1: "Full" Backwards Support
You know that there exists installed code that merrily does the Wrong Thing, that is, using undocumented module system internals. However you don't know which code, precisely, and more importantly, you don't have the time or energy to make the requisite changes.

For this phase, call the activation proc without any args.

Phase 2: "Selective" Backwards Support
You have precisely identified which undocumented module system internals have been used in the installed code, but have not yet installed new code that makes use of (ice-9 gumm).

For this phase, call the activation proc, passing the explicitly identified bindings.

Phase 3: No Backwards Support
All the installed code makes use of (ice-9 gumm); there are no longer any naked calls to the undocumented module internals.

For this phase, you can comment out the use-modules form and the call to the activation proc. See below for reasons why not to remove them entirely.

Due to packages outside your control, it may be that you never reach Phase 3 (or even Phase 2). That's ok, too.

— Scheme Procedure: activate-global-module-system-bindings! [sel...]

Make global bindings for the selected symbols sel, which must be from the following list: 

          the-root-module
          the-scm-module
          module-ref
          resolve-module
          current-module
          eval-in-module
          module-public-interface
          set-module-public-interface!

Throw error if a specified symbol is not in the list. If sel is null, make bindings for the entire list of symbols. This proc only works on its first call. Subsequent calls do nothing.

Here is an example $(GUILE_SITE)/init.scm file that supports old-style executable modules, requiring module-ref and resolve-module; environment capturing code, requiring current-module; and tricky compiled module code that munges the public interface directly, such as that used in Guile-PG 0.17 and 0.18. 

     (use-modules (ice-9 module-system-compat))
     (activate-global-module-system-bindings!
      'module-ref
      'current-module
      'set-module-public-interface!
      'module-public-interface
      'resolve-module)

Note that this example demonstrates Phase 2 usage.

36.3.3.2 Automatic support from make install

To ensure the least amount of surprise for everyone, the installation process automatically adds Phase 1 support but only if either the init file does not exist, or if the string activate-global-module-system-bindings cannot be found therein.

For this reason, if the site eventually moves to Phase 3, and the forms are no longer necessary, you should at least maintain a small comment in the file, like so: 

     ;; Hey, activate-global-module-system-bindings
     ;; is no longer necessary -- we are in phase 3!

Doing so prevents future installations from modifying the file.