mirror of
https://github.com/roswell/roswell.git
synced 2026-09-10 07:16:17 -04:00
161 lines
6.1 KiB
Groff
161 lines
6.1 KiB
Groff
.\" Automatically generated by Pandoc 2.5
|
|
.\"
|
|
.TH "ros-dump" "1" "" "" ""
|
|
.hy
|
|
.PP
|
|
ros\-dump \- make a dumped image of a roswell script
|
|
.SH Synopsis
|
|
.PP
|
|
\f[B]ros [OPTIONS1\&...] dump [OPTIONS2\&...] MODE\f[R] args\&...
|
|
.PP
|
|
\f[C]OPTIONS1\f[R] specify the standard roswell options such as
|
|
\f[C]\-L\f[R] or \f[C]\-m LISP\f[R].
|
|
\f[C]OPTIONS2\f[R] specify the image reduction options we describe
|
|
later.
|
|
\f[C]MODE\f[R] is either \f[C]output\f[R] or \f[C]executable\f[R].
|
|
.SH Description
|
|
.PP
|
|
\f[C]ros\-dump\f[R] creates a dumped lisp image of the state after
|
|
processing all options \f[C]OPTIONS1\f[R].
|
|
.PP
|
|
It has two modes \f[C]output\f[R] and \f[C]executable\f[R].
|
|
In both modes, the global environment (e.g.\ global binding to special
|
|
variables such as \f[C]*package*\f[R]) of the state just after the
|
|
restart is the environment which was effective when the script was
|
|
dumped.
|
|
.PP
|
|
The dumped image is generally not compatible between the different
|
|
implementations, and also between the versions.
|
|
.SH Dump modes
|
|
.SS output [\-f] [\-o OUTPUT] NAME
|
|
.PP
|
|
It loads the roswell script \f[C]NAME\f[R] and saves the current lisp
|
|
state to an image.
|
|
.PP
|
|
The image file is by default written to an internal directory of roswell
|
|
in an organized manner, i.e., somewhere under
|
|
\f[C]$ROSWELL_INSTALL_DIR\f[R] deduced by the current implementation,
|
|
its version and the given NAME.
|
|
.PP
|
|
When the output file already exists, the command fails with an error
|
|
code.
|
|
.PP
|
|
The image can be loaded by \f[C]ros \-m IMAGE\f[R].
|
|
When restarting from the image, standard roswell subcommands and
|
|
additional arguments to the script are also available, for example
|
|
\f[C]ros run\f[R] to resume with a repl, or \f[C]\-\-restart FUNC\f[R]
|
|
to call a specific function, leaving some flexibility.
|
|
.TP
|
|
.B \f[C]\-o OUTPUT\f[R]
|
|
The image is written to \f[C]OUTPUT\f[R] instead of the default
|
|
location.
|
|
.TP
|
|
.B \f[C]\-f\f[R]
|
|
Force output when the output already exists.
|
|
.SS executable NAME [\-o OUTPUT]
|
|
.PP
|
|
When a script is dumped with \f[C]executable\f[R], the dumped image
|
|
becomes an self\-contained executable binary which implies
|
|
\f[C]\-\-restart main\f[R].
|
|
.PP
|
|
If \f[C]OUTPUT\f[R] is given, the resulting binary is written to this
|
|
file.
|
|
Otherwise, the output filename is deduced from \f[C]NAME\f[R] and is
|
|
written in the same directory.
|
|
On Windows and if \f[C]SCRIPT\f[R] has \f[C].ros\f[R] extension, the
|
|
filename will be \f[C]SCRIPT.exe\f[R].
|
|
On the other systems, the result will be \f[C]SCRIPT\f[R] (without
|
|
extension).
|
|
.PP
|
|
This feature is supported on SBCL, CCL, CMUCL, CLISP, ECL.
|
|
.SH Image Reduction Options
|
|
.PP
|
|
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.
|
|
.PP
|
|
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 \f[C]READ\f[R] after the restart.
|
|
.PP
|
|
Reduction options are processed in the left\-to\-right manner.
|
|
.TP
|
|
.B \[en]disable\-compression, \[en]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.
|
|
.TP
|
|
.B \[en]remove\-docstrings
|
|
This option removes all docstrings from all symbols in the entire lisp
|
|
image.
|
|
.TP
|
|
.B \[en]delete\-package PKG
|
|
This option can be specified multiple times.
|
|
It uninterns the symbols in PACKAGE, calls \f[C]makeunbound\f[R] and
|
|
\f[C]fmakeunbound\f[R] on each symbol and deletes the package.
|
|
Package names are automatically string\-upcase\[cq]d.
|
|
.TP
|
|
.B \[en]delete\-all\-packages
|
|
This option applies \[en]delete\-package PKG on all packages, except
|
|
some blacklisted packages (keyword, roswell, ROS.SCRIPT.DUMP, and the
|
|
package of the main function symbol).
|
|
.TP
|
|
.B \[en]delete\-packages\-except PACKAGE
|
|
This option can be specified multiple times.
|
|
It is identical to \[en]delete\-all\-packages except that it adds
|
|
PACKAGE to the blacklist.
|
|
Package names are automatically string\-upcase\[cq]d.
|
|
.TP
|
|
.B \[en]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 \[en]delete\-all\-packages and
|
|
\[en]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).
|
|
.TP
|
|
.B \[en]purify, \[en]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.
|
|
.TP
|
|
.B \[en]impurify, \[en]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\[cq]ed.
|
|
When purification is enabled, it impurifies all objects before running
|
|
the purifying GC.
|
|
.TP
|
|
.B \[en]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).
|
|
.TP
|
|
.B \[en]delete\-macro\-definitions, \[en]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 \[ti]2MB reduction on SBCL.
|
|
.TP
|
|
.B \[en]delete\-compiler\-information\-sbcl
|
|
This is an SBCL\-specific option which is more aggressive than the above
|
|
methods (\[ti]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).
|
|
.SH SEE ALSO
|
|
.PP
|
|
\f[I]sbcl\f[R](1) \f[I]ros\f[R](1) \f[I]ros\-init\f[R](1)
|
|
.SH AUTHORS
|
|
Roswell Project Team.
|