ros-dump(1) ros-dump(1)
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. OP-
TIONS2 specify the image reduction options we describe later. MODE is ei-
ther output or executable.
Description
ros-dump creates a dumped lisp image of the state after processing all op-
tions OPTIONS1.
It has two modes output and executable. In both modes, the global environ-
ment (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 imple-
mentations, 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 im-
age.
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. Other-
wise, 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 im-
age.
Care should be taken to ensure the resulting program works as expected, as
some of these operation may destroy the common assumptions of the conform-
ing 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 sym-
bols in PACKAGE, calls makeunbound and fmakeunbound on each symbol
and deletes the package. Package names are automatically string-up-
case'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. Pu-
rification 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 depreca-
tion 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 per-
formed. 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 sys-
tems of SBCL by also removing the inlining information, IR1 trans-
former and IR2 (VOP).
SEE ALSO
sbcl(1) ros(1) ros-init(1)
AUTHORS
Roswell Project Team.
ros-dump(1)
Synopsis | Description | Dump modes | Image Reduction Options | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ros-dump&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>