ros-dump - make a dumped image of a roswell script

Synopsis

ros [OPTIONS1...] dump [OPTIONS2...] MODE args...

OPTIONS1 specify the standard roswell options such as -L or -m LISP. OPTIONS2 specify the image reduction options we describe later. MODE is either output or executable.

Description

ros-dump creates a dumped lisp image of the state after processing all options OPTIONS1.

It has two modes output and executable. In both modes, the global environment (e.g. global binding to special variables such as *package*) of the state just after the restart is the environment which was effective when the script was dumped.

The dumped image is generally not compatible between the different implementations, and also between the versions.

Dump modes

output [-f] [-o OUTPUT] NAME

It loads the roswell script NAME and saves the current lisp state to an image.

The image file is by default written to an internal directory of roswell in an organized manner, i.e., somewhere under $ROSWELL_INSTALL_DIR deduced by the current implementation, its version and the given NAME.

When the output file already exists, the command fails with an error code.

The image can be loaded by ros -m IMAGE. When restarting from the image, standard roswell subcommands and additional arguments to the script are also available, for example ros run to resume with a repl, or --restart FUNC to call a specific function, leaving some flexibility.

-o OUTPUT: The image is written to OUTPUT instead of the default location.
-f: Force output when the output already exists.

executable NAME [-o OUTPUT]

When a script is dumped with executable, the dumped image becomes an self-contained executable binary which implies --restart main.

If OUTPUT is given, the resulting binary is written to this file. Otherwise, the output filename is deduced from NAME and is written in the same directory. On Windows and if SCRIPT has .ros extension, the filename will be SCRIPT.exe. On the other systems, the result will be SCRIPT (without extension).

This feature is supported on SBCL, CCL, CMUCL, CLISP, ECL.

Image Reduction Options

These options unlink some references to the runtime objects and allow gcs to reclaim some memory, which eventually reduces the size of the dumped image.

Care should be taken to ensure the resulting program works as expected, as some of these operation may destroy the common assumptions of the conforming programs. For example, package-related reduction options may inhibit the runtime calls to READ after the restart.

Reduction options are processed in the left-to-right manner.

–disable-compression, –enable-compression, -c: These options disable/enable/enable the core compression feature in SBCL. Thus this option is meaningful only on SBCL. Compression is enabled by default.
–remove-docstrings: This option removes all docstrings from all symbols in the entire lisp image.
–delete-package PKG: This option can be specified multiple times. It uninterns the symbols in PACKAGE, calls makeunbound and fmakeunbound on each symbol and deletes the package. Package names are automatically string-upcase’d.
–delete-all-packages: This option applies –delete-package PKG on all packages, except some blacklisted packages (keyword, roswell, ROS.SCRIPT.DUMP, and the package of the main function symbol).
–delete-packages-except PACKAGE: This option can be specified multiple times. It is identical to –delete-all-packages except that it adds PACKAGE to the blacklist. Package names are automatically string-upcase’d.
–destroy-packages-sbcl: This is an sbcl-specific option which is even more aggressive than the above methods (>10MB reduction). It destroys the package system by modifying the internal tables for packages, cleaning up the caches for package-use-list etc. The blacklist is shared among –delete-all-packages and –destroy-packages-sbcl. However, this method does not call fmakunbound/makunbound, so combining the two methods can result in a more aggressive image size reduction. Due to the nature of this option, it is desirable to specify it as the last method (i.e. rightmost).
–purify, –no-purify: This is common to CCL, SBCL, CMUCL. Moves all objects to the static space where GC does not scan, for the later performance of GC. Purification is enabled by default.
–impurify, –no-impurify: This is an CCL-specific option (enabled by default). It moves all objects to the dynamic space before saving the image. This allows the static-space objects to be GC’ed. When purification is enabled, it impurifies all objects before running the purifying GC.
–delete-debug-info: This removes the debug infomation of functions (used to show the stack frame etc), as well as the source locations and the deprecation information of various symbols. SBCL only. This option has a large effect (+10MB reduction).
–delete-macro-definitions, –delete-compiler-macro-definitions: This removes all definitions of macros and compiler-macros, assuming that no runtime compilation/interpretation of code will be performed. This option should be portable across implementations. It has ~2MB reduction on SBCL.
–delete-compiler-information-sbcl: This is an SBCL-specific option which is more aggressive than the above methods (~4MB reduction). In addition to the macro and the compiler-macro definitions, it destroys the internal compiler systems of SBCL by also removing the inlining information, IR1 transformer and IR2 (VOP).

AUTHORS

Roswell Project Team.