Changes to INSTALL and installation procedure

Loading a Package from an Image File

There are several reasons to need this.

• Semantics.

  If the package source does some computation other than just assigning functions, it may be difficult or impossible to get the desired effect through the form of parse-eval used when the library is attached.

  For example, the RSMethods package and all packages that use it will need to define formal classes and methods and save the resulting objects in the package. By definition, these computations default to save the results in the global environment (where=1). It is possible to trick the computations to save the results in the package's environment, but the mechanism needed is messy and unintuitive, and not something we want to pass on to future contributors. (Packages RSMethods and OOP in the Omegahat collection are examples of how it can be done.)

• Efficiency.

  The special computations needed for installing some of the newer packages can take considerable time. This is true of the RSMethods example and of some of the inter-system interface packages. When we embed R in other systems, startup time becomes a more serious issue. Even for conventional, but large, packages, startup time can be nontrivial.

The proposed, optional alternative works as follows.

1. At install time, the package source is run through R in batch mode, and the resulting image file is saved.
2. When the library is attached, an automatically generated version of .First.lib loads the image and then invokes the actual .First.lib from the package, if any.

This version of installation can be triggered either by an option (-s or --save) to the INSTALL command, or by the presence of a file INSTALL.R in the package directory. (Because some packages may require installation this way, we need a package-specific mechanism to trigger it. The command option --no-save overrides the INSTALL.R file.)

If the INSTALL.R file is empty, its presence causes the version of .First.lib mentioned above to be copied to the installed package source. If the file is non-empty, its contents are copied instead, allowing the package designer to customize the installation procedure (so far, no example requiring this has come up).

The procedure of saving and loading an image of the package objects should be compatible with the standard installation for objects assigned directly in the source. If the package source does something with strictly session scope, this would need to be done in the .First.lib with the new installation. One likely example is requiring other packages: the calls to require need to be done from .First.lib.

The environment variable R_SAVE_IMAGE is set to true and can be used by the package code to take different action when the code is being run to create a loadable image. Two examples of packages set up for optional installation in this form are in the Omegahat packages download area: the RSMethods package, and the (unadvertised but available) OOP package for object-oriented programming.

For the proposed changes, see the INSTALL script and the diff's against the current version.