| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
This document contains the following sections:
1.0 Comparison with excl:dumplispThere are many links to excl:build-lisp-image in this document. In fact, essentially all relevant information about build-lisp-image is contained in this document.
The function build-lisp-image can be used to create a new image (dxl) file. This will be a fresh image, fresh in the sense that it inherits little from the running image (only values of certain global variables used as argument defaults). Typical reasons for building images with build-lisp-image include:
- Building a new image that includes patches.
- Building a custom image which includes local functionality or with locally-desired initializations.
build-lisp-image is a lisp function, so it is called from a running Lisp. We distinguish between the image which calls build-lisp-image, the running image, from the image being created, the new image.
build-lisp-image spawns a separate process. On Windows, a "Create image" window displays information about the build process (you may have to expose this window). On Unix, information is printed to the listener. You will see many prompts: do not attempt to type to them.
Images can also be created with dumplisp, as described in the documentation for that function and in the document dumplisp.htm. An image created by excl:dumplisp is essentially a copy of the currently running image, with all loaded functionality included and all values of variables preserved. In contrast, build-lisp-image spawns a separate process which builds a new image out of constituent parts. The currently running image supplies only default values for certain arguments. The new image does not capture loaded or newly-defined functionality of the running image (thus, if the function user::foo is defined in the currently running image, it will not be defined in the new image created by build-lisp-image).
This is why build-lisp-image can be used to create a new image with new patches. Patches in the currently running image are not captured by the newly created image. Instead (as described below), patch files are built into the newly created image but the patches in the current image are not involved.
Note that build-lisp-image calls dumplisp in the spawned process. All arguments accepted by dumplisp are also accepted by build-lisp-image except the name argument (which is accepted but ignored since the required argument to build-lisp-image specifies the new image name).
generate-application itself calls build-lisp-image. generate-application is designed to produce a directory of files suitable for shipping to another machine or site (note that you must be licensed to distribute software built in Allegro CL -- contact your Franz Inc. account manager if you are unsure of licensing terms). In contrast, build-lisp-image builds a single image file only. See the description of generate-application and the document delivery.htm.
The "BUILD" module must be loaded for build-lisp-image to work (that is,
"BUILD" should be on the *modules*
list). It will be loaded automatically
when build-lisp-image is
called. You can force loading of the module by evaluating
(require :build)
build-lisp-image takes one required and many keyword arguments. The required argument must be a string naming a file, with or without path information. If no path information is specified, the image file will be placed in the current directory (as returned by current-directory). If relative path information is supplied, it will be resolved relative to the current directory. The image file name must have an extension (type). If it does not, it will not be found when Lisp is started. The standard extension (type) of an image file is .dxl but any extension will do. Note that on Windows machines, .dxl is registered and associated with Allegro CL, so double-clicking on a dxl file (in the Windows Explorer, say) executes mlisp.exe with `-I [that file].dxl' as arguments. When mlisp.exe is called without an image specified with -I, it looks for an image (dxl) file with the same name (i.e. mlisp) and in the same directory. You can copy mlisp.exe to [anything else].exe if you want it to find a different image file named [anything else].dxl automatically.
Here is the template for a call to build-lisp-image:
(excl:build-lisp-image image-file ...keyword/value pairs... ...dumplisp-keyword/value pairs...)
Allegro CL supports two character sizes: 16-bit and 8-bit. Thus images and executables either use 16-bit characters or 8-bit characters. No image or executable supports characters of both sizes. See iacl.htm for information on character sizes in Allegro CL.
build-lisp-image creates a 16-bit character or an 8-bit character image as the new image is created using a 16-bit executable (mlisp and alisp on UNIX, mlisp.exe and alisp.exe on Windows) or an 8-bit executable (mlisp8 and alisp8 on UNIX, mlisp8.exe and alisp8.exe on Windows). The build-executable keyword argument to build-lisp-image specifies the executable that will be used to create the new image. The value of that argument defaults to the executable used to start the running image.
Therefore, if you want the character size of the new image to be the same as the character size in the running image, you need not specify a value for the build-executable keyword argument. If you want a different character size, specify an appropriate executable as the value of that argument.
For example, if you are running a 16-bit character size image and you want to build an 8-bit character size image, call build-lisp-image like this:
(build-lisp-image "my-image.dxl" :build-executable "mlisp8" ;; On Windows "mlisp8.exe" ;; < other keyword arguments and values > )
(That call also works if you are running an 8-bit executable already, of course.)
For example, if you are running an 8-bit character size image and you want to build a 16-bit character size image, call build-lisp-image like this:
(build-lisp-image "my-image.dxl" :build-executable "mlisp" ;; On Windows "mlisp.exe" ;; < other keyword arguments and values > )
(That call also works if you are running a 16-bit executable already, of course.)
Note: Unless you have created your own executable (which is uncommon, but see main.htm, all 16-bit character size executables are identical and all 8-bit character size executables are identical. Therefore, any executable of the correct character size may be specified.
Certain defaults for keyword arguments to build-lisp-image are inherited from the currently running image. It is important to understand that these inheritances are the only effect that values in the currently running image have on the new image being built.
Argument | Default | Description |
:case-mode |
*current-case-mode* |
Sets the case mode of the new Lisp image. The default is the case mode of the running image. The value can be one of.
|
:dst |
*daylight-saving-time-observed* |
Controls daylight savings time inclusion in time
computations. If t , United States Daylight Savings Time schedules are
used. If nil , daylight savings time is assumed to never be in force. There is
no direct support for non-United States schedules. Users outside the United States can
contact Franz Inc. technical support ([email protected])
for assistance in implementing a different schedule. |
:include-clim |
t if clim is in the currently
running image, nil if it is not. |
When true, include CLIM in the resulting image. |
:include-common-graphics |
This argument is no longer supported. | Windows only. If you are building a
development image, specify :include-ide true and Common Graphics and the IDE
will be in the image. If building an application image, use the project system in the IDE. |
:include-compiler |
When building a standard runtime
image (i.e. when the |
When true, include the compiler
as the resulting image is being built. Whether the compiler is in the built image
depends on the value of the When See the |
:include-composer |
t if Allegro Composer is in the
currently running image, nil if it is not. |
UNIX only. When true, include Composer in the resulting image. |
:include-debugger |
t |
(The default for this argument is not inherited
from the running image, so this argument belongs in the next table. It is repeated here to
be with the other When true, include the debugger in the resulting image. |
:include-devel-env |
t if the development environment is
in the currently running image (i.e. :develenv is on the *modules*
list), nil if it is not. |
When true, include the
non-graphical development environment in the resulting image. The file sys:;develenv.cl
(i.e. develenv.cl in the Allegro directory) lists the modules (as arguments to require)
that make up the development environment. This argument must be specified
nil when :runtime is true since
some modules are not allowed in a runtime image. |
:include-ide |
t if the IDE is in the currently
running image, nil if it is not. |
Windows only. When true, include the graphical development environment in the resulting image. |
:include-tpl |
t if the top level is in the
currently running image, nil if it is not. |
When true, include the normal
top-level in the resulting image. When nil a minimal top level, as
described in Section 10.0 Minimal top levels below, is
available. Also specify nil when supplying your own top level. |
:include-xcw |
t if Common Windows is in the
currently running image, nil if it is not. |
UNIX only. When true, include Common Windows in the resulting image. |
:init-file-names |
*init-file-names* |
The value should be a list of strings naming files without directory information, like (".clinit.cl" "clinit.cl") The directories to be searched for these files is determined at runtime (the current directory and the home directory -- see startup.htm). The default comes from the value of the indicated variable in the running image.
See also |
:load-local-names-info |
*load-local-names-info* |
The value of this argument serves as the default
value for *load-local-names-info*
in the image to be built. By default, the value is inherited from the value in the running
image. The value can be t or nil . |
:load-source-file-info |
*load-source-file-info* |
The value of this argument serves as the default
value for *load-source-file-info* in the image to be built. By default, the value is inherited from the value
in the running image. The value can be t or nil . |
:load-xref-info |
*load-xref-info* |
The value of this argument serves as the default
value for When building a runtime
(i.e. |
:pll-file |
(pll-file) | The value can be a string naming an existing pll
file or If the value has no directory information (i.e. is just a filename or a filename and a file type), the pll file will be looked for on startup as described in the pll-file entry. If directory information is included, that location (relative to the current directory if relative), will be looked in but nowhere else. The file type defaults to .pll if unspecified. Note that some pll files have type .epll. Note that build-lisp-image does not create a pll file so it is an error to specify a non-existent file as the value of this argument. Pll files are created by the program cvdcvt. See the definition of that program and also the discussion of pll files in miscellaneous.htm. See also generate-application and delivery.htm. |
:print-startup-message |
*print-startup-message* |
The value of
*print-startup-message*
is set to the value of this keyword argument in the new image being created. |
:read-init-files |
*read-init-files* |
Specifies the value of
The default is the value of See the document startup.htm for information on
initialization files and the meaning of the current and the home directories. See also |
:record-source-file-info |
*record-source-file-info* |
The value of this argument serves as the default
value for When building a runtime (i.e. |
:record-xref-info |
*record-xref-info* |
The value of this argument serves as the default
value for *record-xref-info*
in the image to be built. By default, the value is inherited from the value in the running
image. |
:require-search-list |
*require-search-list*
|
The value of this argument serves as the default value for *require-search-list* in the
image to be built. By default, the value is inherited from the value
in the running image.
|
:restart-app-function |
*restart-app-function* |
Causes *restart-app-function* to be
set to this value. The value must be a symbol (it cannot be a
function object). See startup.htm or
delivery.htm.
Warning 1: A function object is a legal value for
Note that in earlier versions, the value of this variable in images
that used the IDE (on Windows) was the function that started the
IDE. In current versions, that function is the value of the |
:restart-init-function |
*restart-init-function* |
Causes
Note that the value of this variable on Windows in an image that
starts the IDE, is cg:start-ide. That value is
likely not appropriate for an application and the build may fail if
that value is used but necessary parts of Common Graphics code are not
loaded into the image being built. Be sure to specify the value of
this variable to be
If no value is specified for this argument, the value will default to
the value of
Warning 1: In the IDE, the value of Warning 2: A function object is a legal value for
|
Most of the remaining keyword arguments are listed in the next table. The keyword arguments to dumplisp are also acceptable to build-lisp-image. None of these arguments inherit values from the currently running image.
Argument | Default value | Description/compatibility notes |
:aclmalloc-heap-size
|
nil
(the value can come from an
environment variable. See
Section 6.0 Arguments to build-lisp-image 3: defaults taken from environment variables.)
|
Allows specification of the total size of the ACLMALLOC heap. That is a heap separate from the Lisp heap (see the arguments :lisp-heap-start and :lisp-heap-size) used for aclmalloc areas and some static areas. See Table note 1: Finding available memory addresses immediately following this table for information on determining a suitable value for this argument. The value must identify a decimal integer. See Table Note 3 for information on how to specify a value for this argument (in short: as an integer or as a string which is an integer followed by k or m, so like 123456 or "100m"). (In earlier releases, the ACLMALLOC heap was called the C heap and this argument was named :c-heap-size. That name still works though using it signals a warning.) |
:aclmalloc-heap-start |
-+
nil (the value can come from an
environment variable. See
Section 6.0 Arguments to build-lisp-image 3: defaults taken from environment variables.)
|
Allows specification of the start of the ACLMALLOC heap. This value must be above the value of :lisp-heap-start. See Table note 1: Finding available memory addresses immediately following this table. The value must identify a decimal integer. See Table Note 3 for information on how to specify a value for this argument (in short: as an integer or as a string which is an integer followed by k or m, so like 123456 or "100m"). (In earlier releases, the ACLMALLOC heap was called the C heap and this argument was named :c-heap-start. That name still works though using it signals a warning.) |
:autoload-warning |
nil |
If true, then a report of autoloadable functions will be made to autoloads.out. If a string, it is interpreted as a filename which will be used in place of autoload.out for the report. An autoloadable function is one for which the function definition is in fact not present in the image. Instead, instructions to load a particular file, usually a fasl file out of the bundle in the Allegro directory are present. Once the file is loaded, the true function definition is used to evaluate the call to the function that triggered the autoload. The autoloading feature is designed to keep unneeded
functionality from unnecessarily increasing the size of the
running image, but to make use of functionality transparent to
users. If you are building an image for use locally (say, making
an image with patches) this report is likely of no interest since
autoloading is typically transparent, as we said. If however, you
are creating an application, you may want to know what
functionality might be autoloaded since you are not permitted to
distribute the files.bu bundle file from where most
autoloading is done. For this reason, generate-application changes the default
for this argument to The format of autoload.out is two columns, a fasl file name on the left and the function that triggers its loading on the right. Some files are loaded by many functions and so appear many times on the left. |
:build-debug |
t |
Value can be t
(meaning provide extra debug information, but not interactively),
:interactive (meaning allow interactive
debugging of the build),
and nil (meaning do not provide extra
debug information -- this option is intended for batch builds).
See Section 7.0 Debugging an image build problem or failure.
|
:build-input |
nil |
Allows specifying a file which
collects the input to the spawned process.
The value, if supplied, must be a
string naming a file or t (meaning use
the filename buildin.out or
nil (meaning do not write a file).
This argument was previously called
:internal-debug . |
:build-output |
nil |
Allows specifying a dribble file which
contains a
transcript of the entire process of building the image.
The value, if supplied, must be a
string naming a file. This argument was previously called
:dribble-file . |
:build-executable |
Defaults to running image executable. Value, if specified, should be a string. | this
argument specifies the name of the Lisp executable that will be
invoked when the process that builds the new image file is
spawned. Typically, you specify a value for this argument only when
(1) You want to use a custom executable built as described in main.htm (2) You want a character size in the new image that is different from the character size in the running image. See Section 3.1 The character size in the resulting image for more information and examples. Note: if build-lisp-image is being called by generate-application, the value of this argument is used by generate-application as well. The specified executable will be the one copied to the application directory. See delivery.htm. |
:c-heap-size
|
nil
|
This is the old name
for :aclmalloc-heap-size . Using this name
will work but is deprecated. We recommend you change code to use
:aclmalloc-heap-size . See
:aclmalloc-heap-size
for usage details.
|
:c-heap-start |
-+
nil
|
This is the old name
for :aclmalloc-heap-start . Using this name
will work but is deprecated. We recommend you change code to
use :aclmalloc-heap-start . See
:aclmalloc-heap-start
for usage details.
|
:close-oldspace |
nil |
If true, reorganizes oldspace and newspace sizes just before the new image is created. See Table note 2: :close-oldpace argument details immediately following this table for more information. |
:copy-shared-libraries |
See generate-application and delivery.htm. This argument is only relevant when used with generate-application. | |
:debug-on-error |
Unsupported, causes an error if specified | This argument is replaced by :build-debug. See Section 7.0 Debugging an image build problem or failure. |
:discard-arglists |
nil |
Value can be
|
:discard-compiler |
nil |
Allows the compiler to be discarded after the
input files are loaded. This might be necessary for some applications. :include-compiler
must be t if this argument is
t . |
:discard-local-name-info |
t |
Controls throwing away local name information
loaded from .fasl files as a result of the compiler switch
comp:save-local-names-switch .
If t , local name information is discarded. If nil , it is
maintained. |
:discard-source-file-info |
(null [value
of :load-source-file-info
argument]) |
Controls throwing away source file
information. A true value both discards source file info in the
image being created and causes the initial value of *record-source-file-info*
and *load-source-file-info*
to be nil . |
:discard-xref-info |
(null [value
of :load-xref-info
argument]) |
Controls throwing away of cross reference
information. A true value both discards cross reference info in the
image being created and causes the initial value of When
building a runtime (i.e. |
:dribble-file |
nil |
This argument has been renamed
:build-output although :dribble-file
is accepted for backwards compatibility. It is an error to specify
both :dribble-file and :build-output .
See the description of :build-output
for details. |
:exit-after-image-build |
Unsupported, causes an error if specified | This argument is replaced by build-debug. See Section 7.0 Debugging an image build problem or failure. |
:generate-fonts |
nil |
UNIX only. Generate (X) fonts from server specified by :server-name. |
ignore-command-line-arguments |
nil |
This is actually an argument to dumplisp which build-lisp-image accepts and passes to
dumplisp when dumplisp is
called at the end of the build process. When true, the resulting
image will ignore command-line arguments prefixed by a dash
(- ). Command-line
arguments prefixed by a + (used on Windows only)
are never ignored. See Command line arguments in
startup.htm for details of command-line
arguments. |
:include-* |
[See text at right] | All :include-* arguments except :include-debugger ,
documented just below, are documented in
Section 4.0 Arguments to build-lisp-image 1: defaults inherited from the running image
above since
their default values are inherited from the running image. |
:include-debugger |
t |
When true, include the debugger in the resulting image. |
:internal-debug |
nil |
This argument has been renamed
:build-input although
:internal-debug
is accepted for backwards compatibility. It is an error to specify
both :internal-debug and
:build-input .
See the description of :build-input
for details. |
:lisp-heap-size |
nil
(the value can come from an
environment variable. See
Section 6.0 Arguments to build-lisp-image 3: defaults taken from environment variables.)
|
Allows specification of the initial Lisp heap reserve size. This is
the amount initially allocated by the Operating System (and thus is
usually guaranteed to be available to the running image).
The value must identify a decimal integer. See
Table Note 3 for information on how
to specify a value for this argument (in short: as an integer or as a string
which is an integer followed by k or m, so like
123456 or "100m").
If more heap
is needed after Lisp has started, the OS will allocate it if it
can. If you find your Lisp heap is unable to grow because the OS will
not make additional space available, you might build an image with a
larger value for this argument so the OS will locate the image in a
larger block of space at startup. The value for an image is printed by
(room t) output (as resrve ). See
gc.htm for more general information on space
allocation. Also see Table note 1: Finding available
memory addresses. |
:lisp-heap-start |
nil
(the value can come from an
environment variable. See
Section 6.0 Arguments to build-lisp-image 3: defaults taken from environment variables.)
|
Allows specification of the start of the Lisp heap. The value must identify a decimal integer below the value of aclmalloc-heap-start. See Table Note 3 for information on how to specify a value for this argument (in short: as an integer or as a string which is an integer followed by k or m, so like 123456 or "100m"). Also see Table note 1: Finding available memory addresses. |
:lisp-files |
nil |
Allows Lisp files to be loaded
before the image
is created. The value of this argument is This argument is ignored by generate-application. Instead, files to load are specified by the required input-files argument. |
:newspace
|
See text at right. (the value can come from an environment variable. See Section 6.0 Arguments to build-lisp-image 3: defaults taken from environment variables.) | Specifies the size of the newspace in the new image. See the document gc.htm for information on newspace sizes. The value must identify a decimal integer. See Table Note 3 for information on how to specify a value for this argument (in short: as an integer or as a string which is an integer followed by k or m, so like 123456 or "100m"). The default depends on whether the image is 32-bit or 64-bit and is suitable for ordinary use. |
:oldspace |
See text at right. (the value can come from an environment variable. See Section 6.0 Arguments to build-lisp-image 3: defaults taken from environment variables.) | Specifies the amount of free oldspace in the new image. See the document gc.htm for information on oldspace sizes. The value must identify a decimal integer. See Table Note 3 for information on how to specify a value for this argument (in short: as an integer or as a string which is an integer followed by k or m, so like 123456 or "100m"). The default depends on whether the image is 32-bit or 64-bit and is suitable for ordinary use. |
:opt-debug |
2 | The initial value of the debug optimization quality in the new image. Value must be one of 0, 1, 2, 3. See Declarations and optimizations in compiling.htm for information on how these values are used. |
:opt-safety |
1 | The initial value of the safety optimization quality in the new image. Value must be one of 0, 1, 2, 3 but 0 is strongly discouraged. See Declarations and optimizations in compiling.htm for information on how these values are used. |
:opt-space |
1 | The initial value of the space optimization quality in the new image. Value must be one of 0, 1, 2, 3. See Declarations and optimizations in compiling.htm for information on how these values are used. |
:opt-speed |
1 | The initial value of the speed optimization quality in the new image. Value must be one of 0, 1, 2, 3. See Declarations and optimizations in compiling.htm for information on how these values are used. |
:opt-compilation-speed |
1 | The initial value of the compilation-speed optimization quality in the new image. Value must be one of 0, 1, 2, 3. See Declarations and optimizations in compiling.htm for information on how these values are used. |
:post-load-form |
nil |
A form to be evaluated just after the files given
by :lisp-files are loaded. |
:pre-load-form |
nil |
A form to be evaluated just before the files
given by :lisp-files are loaded. |
:preserve-documentation-strings |
t when
build-lisp-image is
called, nil when generate-application is called. |
This argument sets the value of the
*load-documentation* variable
in the resulting image. If the value of that variable is
true, then documentation strings are loaded
into and can be created in the new image being created. If the
value of that variable is nil , no
documentation strings are loaded and documentation strings
appearing in definitions are ignored.
Note that the default
value of this argument is different depending on whether build-lisp-image is called
directly (default |
:restart-app-function |
This argument is documented in Section 4.0 Arguments to build-lisp-image 1: defaults inherited from the running image above since its default value is inherited from the running image. | |
:restart-init-function |
This argument is documented in Section 4.0 Arguments to build-lisp-image 1: defaults inherited from the running image above since its default value is inherited from the running image. | |
:runtime |
nil |
When calling
build-lisp-image, the
value must be See runtime.htm for more information. See particularly the discussion in that document of what values other arguments (such as :include-compiler and :include-devel-env) must be. |
:server-name |
nil |
Specifies X server from which to get fonts.
Ignored if :generate-fonts is
nil . |
:show-window |
:showna |
Windows only.
The value of the :show-window keyword to
run-shell-command,
used to start
the process to build the image being created. See the page for
run-shell-command to
see the other allowable values for this argument. |
:splash-from-file |
nil |
Windows only. Allows specification of a splash bitmap file. If true, the value must be a string naming a bitmap file. |
:temporary-directory |
See text at right. | Default value is architecture dependent. Temporary files created during the build will be stored in this directory, either the default or the specified location. |
:us-government |
nil |
Must be specified t by any user
employed by or acting on behalf of the United States Government. The only effect is to
change the copyright banner to include language required by US copyright laws relating to
US Government use. All other users can specify nil or leave unspecified. Only
for the United States Federal Government. State and local governments in the United
States and all governmental entities outside the United States can specify nil
or leave unspecified. |
:user-shared-libraries |
nil |
Allows loading DLLs (Windows) or
shared objects (.so
or .sl, UNIX) files into the new application image. The value,
if not nil , should be a list of pathnames or strings
naming pathnames. These files are copied to the destination
directory and they are loaded upon application image startup. An error
will be signaled by generate-application if files
listed cannot be found in order to be copied to the
destination directory. |
:verbose |
nil |
Causes informative messages to be printed while the image is created. |
:wait |
Unsupported, causes an error if specified | This argument is replaced by build-debug. See Section 7.0 Debugging an image build problem or failure. |
To successfully allocate the heap, you will need to move the starting address of the Lisp heap to a location large enough to support a contiguous address range specified by the heap size you chose. If you evaluate the following forms in Allegro CL, a memory map of the current state of virtual memory on your machine will be printed to the file filename.ext (except on the IBM RS/6000 where the output file will say only that the information is not available). Note that you may use any filename and extension.
(ff:def-foreign-call memory_status_dump ((filename (* :char))) :arg-checking nil :strings-convert t) (memory_status_dump "filename.ext")
The output differs for different platforms, but in all (except the RS/6000) cases, a set of address ranges is provided showing what ranges are allocated.
The value of the filename may be 0, causing the information to be printed to the terminal (on Windows, if the filename argument is 0, then the Console is used as output). You may get a warning if you specify 0 as the filename argument. It can be ignored.
Permissions on Windows are shown in the last four characters in the output:
r
- read accessw
- write accessx
- execute accessc
- mapped copy on write (and has not been copied yet).You will need to locate a large chunk of free memory and specify to build-lisp-image a starting address that will support your heap size.
The default value of the close-oldspace keyword
arguments in nil
. If its value is specified
true, the following is evaluated just before the
image being built is created (newspace is the value of the
:newspace
keyword argument described above, oldspace is the value of the
:oldspace
keyword argument also described above):
(sys:resize-areas :old 0 :new (- (/ newspace 2) (* 1025 50)) :global-gc t :tenure t) (sys:resize-areas :old oldspace :sift-old-areas nil) (setf (sys:gsgc-parameter :open-old-area-fence) -1)
See:
:open-old-area-fence
gsgc parameter is described
and closed old areas are described.
The value -1 means close all old areas except the newest one.
As described in gc.htm, closed old areas are never gc'ed, so objects in them and objects they point to are never considered garbage. The idea is that the image being created is an application, and the application machinery is being loaded. That machinery will never become garbage, so it saves time if the garbage collector never looks at it. Data to be used by the application is loaded after the image is created. That data will be tenured to the open old areas, and thus will be garbage collected. This allows faster global gc's to clear out data sets when they are no longer needed.
The
arguments aclmalloc-heap-start,
aclmalloc-heap-size,
lisp-heap-start,
lisp-heap-size,
newspace, and
oldspace all take a
number of bytes as a value. You can express this number as a decimal
integer or as a string which is a decimal integer optionally followed
by the letter k
or m
,
(case does not
matter). k
means multiple the integer by
1024 (i.e. kilobytes) and m
by 1024*1024
(i.e. megabytes).
So "1024K" is the same as "1m", "1048576" and
1048576. We recommend using letter modifiers for large values as
sometimes very large integers can overflow when read.
build-lisp-image will take certain defaults from the values of environment variables if these are set when build-lisp-image is called. The following table shows the arguments and the name of the associated environment variable.
All these arguments do not inherit values from the running Lisp image (the one which calls build-lisp-image). See Section 5.0 Arguments to build-lisp-image 2: defaults not inherited from the running image above for more information on these argument and their default values.
(In releases prior to 8.2, the ACL_BUILD_ACLMALLOC_HEAP_START and ACL_BUILD_ACLMALLOC_HEAP_SIZE variables were named ACL_BUILD_C_HEAP_START and ACL_BUILD_C_HEAP_SIZE. The old names still work but cause an error to be signaled.)
Argument | Associated Environment Variable |
:aclmalloc-heap-size
|
ACL_BUILD_ACLMALLOC_HEAP_SIZE |
:aclmalloc-heap-start
|
ACL_BUILD_ACLMALLOC_HEAP_START |
:lisp-heap-size
|
ACL_BUILD_LISP_HEAP_SIZE |
:lisp-heap-start
|
ACL_BUILD_LISP_HEAP_START |
:newspace
|
ACL_BUILD_NEWSPACE |
:oldspace
|
ACL_BUILD_OLDSPACE |
Starting in Allegro CL 6.2, the method for debugging a failed or problematic image build has been simplified, and unified for all platforms. (In earlier releases, behavior was different for Windows and UNIX.) As part of the changes, the debug-on-error, exit-after-image-build, and wait keyword arguments to build-lisp-image (and therefore to generate-application) have been removed. An error is signaled if they are specified. In their place is a new keyword argument build-debug. In this section, we discuss that argument and the general issue of debugging builds.
build-lisp-image spawns another Lisp to build the desired image (that is one reason why the new image does not inherit from the calling image). If there is a problem, it is this spawned image that one wants to debug. Debugging the image in which you called build-lisp-image or generate-application is not useful because the problem is not manifested in that image.
The problem is usually caused by a Lisp error being signaled. If the
spawned image exits at that point, it will exit with a non-zero
status. As we describe just below, specifying the
build-debug keyword argument as
:interactive
causes the spawned image not to exit
and allows interactive debugging.
It is possible that a warning will be signaled during the
build. Warnings will not typically cause the build to fail, but are
legitimate causes for concern. If you want to debug a warning, call
build-lisp-image or generate-application specifying
:pre-load-form '(setf *break-on-signals* t)
. This
will cause an error when the warning is signaled.
The choices for debugging are:
:build-debug :interactive
(see :build-debug). In the event of an error, the
spawned process started to build the image does not exit, allowing the
problem to be debugged. When you find the cause of the problem,
correct the argument values or the input files and run build-lisp-image or generate-application again. Do not
try to continue the process you are debugging through to a new image
or distribution.
:build-debug t
or leave the
value unspecified, as t
is the default (see
:build-debug). The spawned process will exit
with a non-zero status at the end of the build, error or not, but will
print a backtrace at the point of error. On Windows, the default
behavior, with no + command-line arguments, is that
when Lisp exits with a non-zero status, the console requires manual
closing.
:build-debug
nil
(see :build-debug). The
spawned process is invoked with -batch command-line arguments. No
backtrace is provided. The console will close automatically regardless
of error status.
Here are examples using the various values of
build-debug. The file foo.cl
includes the form at the top-level (setq x y)
, but
y
does not have a value.
;;****************************************************************** ;; This call in the calling process spawns the process which ;; will attempt the build. Note that :build-debug is t, ;; so the spawned process will exit (its window will remain, however, ;; until you close it by clicking on the Close button). cl-user(3): (build-lisp-image "foo.dxl" :lisp-files '("foo.cl") :build-debug t) Initial generation spread = 1 Allocated 10492920 bytes for old space Allocated 5242880 bytes for new space ;;;;;;;;;;... ... #| (let ((*libfasl* nil) (*global-gc-behavior* nil)) (tenuring (load "foo.cl"))) |# ; Loading /stuff1/acl/acl70/src/foo.cl Error (from error): Script /tmp/genappa149d19b aborted due to error: Attempt to take the value of the unbound variable `y'. Evaluation stack: (excl::internal-invoke-debugger "Error" #<simple-error @ #x71f252aa> nil) (error "Script ~a aborted due to error: ~a" #1="/tmp/genappa149d19b" #<unbound-variable @ #x71f2507a>) (excl::process-script #1#) ->(tpl:start-interactive-top-level #<terminal-simple-stream [initial terminal io] fd 0/1 @ #x711751f2> #<Function top-level-read-eval-print-loop> nil) (excl::start-lisp-execution) ; Auto-exit ; Exiting Lisp [Perhaps a messsage about the exit status] ;; You may examine the window of the spawned Lisp. ;; When you have finished examining it, click the Close ;; button to close it, and then you will see back in the ;; calling process: Error: image creation failed [condition type: simple-error] Restart actions (select using :continue): 0: Return to Top Level (an "abort" restart). 1: Abort entirely from this process. [1] cl-user(4): ;;****************************************************************** ;; This call in the calling process spawns the process which ;; will attempt the build. Note that :build-debug is nil, ;; so the spawned process will exit. cl-user(5): (build-lisp-image "foo.dxl" :lisp-files '("foo.cl") :build-debug nil) Initial generation spread = 1 Allocated 10492920 bytes for old space Allocated 5242880 bytes for new space ;;;;;;;... ... #| (let ((*libfasl* nil) (*global-gc-behavior* nil)) (tenuring (load "foo.cl"))) |# ; Loading /stuff1/acl/acl70/src/foo.cl Error (from error): Script /tmp/genappa149d19c aborted due to error: Attempt to take the value of the unbound variable `y'. ; Auto-exit ; Exiting Lisp Error: image creation failed [condition type: simple-error] Restart actions (select using :continue): 0: Return to Top Level (an "abort" restart). 1: Abort entirely from this process. [1] cl-user(6): ;;****************************************************************** ;; This call in the calling process spawns the process which ;; will attempt the build. Note that :build-debug is :interactive, ;; so the spawned process will not exit. cl-user(1): (build-lisp-image "foo.dxl" :lisp-files '("foo.cl") :build-debug :interactive) ; Fast loading /stuff1/acl/acl70/src/code/build.fasl Initial generation spread = 1 Allocated 10492920 bytes for old space Allocated 5242880 bytes for new space ;;;;;;... ... #| (let ((*libfasl* nil) (*global-gc-behavior* nil)) (tenuring (load "foo.cl"))) |# ; Loading /stuff1/acl/acl70/src/foo.cl Error: Attempt to take the value of the unbound variable `y'. [condition type: unbound-variable] Restart actions (select using :continue): 0: Try evaluating y again. 1: Use :y instead. 2: Set the symbol-value of y and use its value. 3: Use a value without setting y. 4: retry the load of foo.cl 5: skip loading foo.cl 6: recompile /stuff1/acl/acl70/src/foo.cl 7: Abort entirely from this process. [Current process: Initial Lisp Listener] [1] cl-user(1): :zo :all t Evaluation stack: ... 4 more newer frames ... (excl::cer-general-error-handler-one 5 y) (sys::..context-saving-runtime-operation) (sys::..runtime-operation) (excl::%eval y) ->(setq x y) [... excl::%eval ] (eval (setq x y)) (excl::sloload #<file-simple-stream #p"/stuff1/acl/acl70/src/foo.cl" for input pos 32 @ #x71f237ba>) (excl::load-from-stream-or-bundle #<file-simple-stream #p"/stuff1/acl/acl70/src/foo.cl" for input pos 32 @ #x71f237ba> #p"/stuff1/acl/acl70/src/foo.cl" ...) (excl::load-2 "foo.cl" t ...) ... more older frames ... [Current process: Initial Lisp Listener] [1] cl-user(2): ;; You are still at a prompt in the spawned process.
It is possible that the spawned image will fail without signaling a Lisp error. In that case, it will also exit with a non-zero status, but interactive debugging is not, of course, possible. However, this is rare. If it happens, please save any messages that are printed and try the build again (to ensure that it was not a transient problem that caused the failure). If the retry fails, send a bug report to [email protected].
To get maximal information about the invocation of the spawned process caused by your call to build-lisp-image (or generate-application add the arguments:
:build-input "input.txt" :verbose t :build-output "output.txt"
"input.txt" and "output.txt" are filenames -- any filename with any valid path will do, of course. Here is what the build-lisp-image form looks like:
(excl:build-lisp-image <image-file> :build-input "input.txt" :verbose t :build-output "output.txt" <your arguments>)
This causes the actual command starting the Lisp that builds the new dxl (along with other stuff) to be printed to the listener where the build-lisp-image command was issued.
Generated (by the :build-input argument) is the file "input.txt" which contains the Lisp forms passed to the spawned Lisp. It looks roughly like:
(EXCL:SET-CASE-MODE :CASE-SENSITIVE-LOWER) (COMMON-LISP:FORCE-OUTPUT) (COMMON-LISP:PROGN (COMMON-LISP:SETQ EXCL::*STORE-DOCUMENTATION* COMMON-LISP:NIL) (COMMON-LISP:SETQ EXCL:*RECORD-SOURCE-FILE-INFO* COMMON-LISP:NIL) (COMMON-LISP:SETQ EXCL:*LOAD-LOCAL-NAMES-INFO* COMMON-LISP:NIL) [...]
Generated (by the :build-output argument) is the file "output.txt" which contains essentially a dribble output from the spawned process.
The file sys:custom.cl in the Allegro directory
is loaded into the new image at the end of the building process but
just before the files specified by :lisp-files
are
loaded. If you are running generate-application, sys:custom.cl
is loaded before the files specified by the (required)
input-files argument are loaded.
sys:custom.cl, as delivered, contains various
things, either commented out or marked with
#+ignore
. For example, certain forms setting values
to the defaults used in previous versions of Allegro CL are provided,
preceded by #+ignore
so they will not be read
unless the #+ignore
is removed. (See Features present or missing
from *features* in Allegro CL in
implementation.htm for information on
#+ignore
.)
During the build, all patch files in [Allegro Directory]/update relevant to the products included in the image (as coded by the filenames) are loaded into the image during the build.
When building a lisp image, specifying nil
for include-tpl will cause a greatly reduced top-level
functionality to be built into the lisp. The sole purpose of this
minimal top-level is to reduce the space used by the full top-level.
Applications which do not require a top-level or which provide their
own will often specify include-tpl nil
. The minimal top level described here will be
available in such images.
The entire text of the minimal top level functionality is given
below. Note that this code is loaded only if include-tpl is
nil
. The top-level code when
include-tpl is true is quite
different.
(defpackage :top-level (:nicknames :tpl) (:use :common-lisp :excl) (:size 20) (:import-from :excl excl::read-eval-print-loop) ;; These are the function handlers for the top-level commands. ;; They are user visible. (:export #:*read-eval-print-loop* ; user-defined read-eval-print-loop #:*read* ; the top-level reader #:*eval* ; the top-level evaler #:*print* ; the top-level printer )) (provide :tpl-user) (in-package :top-level) ;; simple default tpl handlers: (defvar *read-eval-print-loop* 'default-read-eval-print-loop) (setq *read* 'read) (setq *eval* 'eval) (setq *print* 'print) (declaim (special *break-level*)) (setq *break-level* 0) (defun start-interactive-top-level (*terminal-io* function args &key initial-bindings &aux vars vals) (declare (:discard-source-file-info)) (setf (getf (excl::stream-property-list *terminal-io*) 'initial-listener) sys::*current-process*) ;; Compute the list of special variables and bindings for progv. (dolist (b initial-bindings) (unless (member (car b) vars :test #'eq) (push (car b) vars) (push (eval (cdr b)) vals))) (progv vars vals (setq vars nil vals nil) ;free up space (apply function args))) (defun top-level-read-eval-print-loop () (declare (:discard-source-file-info)) (loop (setq *evalhook* nil *applyhook* nil) (catch ':top-level-reset (read-eval-print-loop :level 0)) )) (defun read-eval-print-loop (&key &allow-other-keys) (declare (:discard-source-file-info)) (let (pop-type cval1 cval2) (loop (multiple-value-setq (pop-type cval1 cval2) (catch 'top-level-break-loop (funcall *read-eval-print-loop*))) ;; If we get here and pop-type is not null, then a throw ;; to 'top-level-break-loop was done (by a different toplevel) (case pop-type ((:pop :debug-pop) (when (plusp cval1) (excl::funcall-in-package :debug-pop :debugger nil (1- cval1) (1- cval2)))) (error "user toplevel can't handle this pop type: ~s" pop-type))))) (defun default-read-eval-print-loop () (loop ;; print the prompt (fresh-line *terminal-io*) (princ "// " *terminal-io*) (force-output *terminal-io*) (let* ((exp (funcall *read*)) (res (funcall *eval* exp))) (funcall *print* res *terminal-io*))))
The minimal top-level is set up by default to issue a "//" prompt. It only accepts lisp evaluable expressions as "commands", and does not interpret any other top-level commands.
Example on a sparc:
% mlisp -I umsloadxcomp.dxl -qq Loading /release/duane/acl70/src/libacl70pf23.so. Mapping umsloadxcomp.dxl...done. Mapping umclxcomp.pll. Allegro CL 7.0 Copyright (C) 1985-2004, Franz Inc., Oakland, CA, USA. All Rights Reserved. // (room) area address(bytes) cons symbols other bytes 8 bytes each 24 bytes each (free:used) (free:used) (free:used) Top #x81dc000 New #x8180000(376832) 918:3158 254:0 246536:37944 New #x8124000(376832) ----- ----- ----- Old #x8000c40(1192896) 781:15523 135:5628 518896:397344 Root pages: 34 Lisp heap limit: 67108864 NIL // (exit) ; Exiting Lisp %
If the power of the normal top-level is needed after a
(non-runtime) minimal top-level lisp is built, :toplevel
can be required. However, simply requiring :toplevel
is
not enough to start the regular top-level listener; instead, the
listener must be invoked recursively, either by an error or by any
command (such as inspect) that
starts a new listener level. At that time, top-level commands (such as
:zoom, etc) can be invoked.
Note however that when :toplevel
is required, the
read-eval-print-loop is reset, and so a :reset command will make it appear as if
the Lisp had always had a normal top-level.
;; In this example, an error can be debugged after the fact by requiring ;; the normal top-level. % mlisp -I umsloadxcomp.dxl -qq Loading /release/duane/acl70/src/libacl70pf23.so. Mapping umsloadxcomp.dxl...done. Mapping umclxcomp.pll. Allegro CL 7.0 Copyright (C) 1985-2004, Franz Inc., Oakland, CA, USA. All Rights Reserved. // (require :toplevel) ; Fast loading /acl70/src/code/toplevel.fasl ; Fast loading /acl70/src/code/frame.fasl ; Fast loading /acl70/src/code/r/rframe.fasl T // a Error: Attempt to take the value of the unbound variable `A'. [condition type: UNBOUND-VARIABLE] Restart actions (select using :continue): 0: Try evaluating A again. 1: Use :A instead. 2: Set the symbol-value of A and use its value. 3: Use a value without setting A. [1] USER(1): :zo ; Autoloading for TOP-LEVEL::ZOOM-COMMAND: ; Fast loading /acl70/src/code/tpl-debug.fasl ; Autoloading for package "DEBUGGER": ; Fast loading /acl70/src/code/debug.fasl Evaluation stack: ->(EXCL::INTERNAL-INVOKE-DEBUGGER "Error" #<UNBOUND-VARIABLE @ #x81b9f8a> ...) (ERROR #<UNBOUND-VARIABLE @ #x81b9f8a>) (SYS::..CONTEXT-SAVING-RUNTIME-OPERATION) (EVAL A) (TPL:TOP-LEVEL-READ-EVAL-PRINT-LOOP) (TPL:START-INTERACTIVE-TOP-LEVEL #<BIDIRECTIONAL-TERMINAL-STREAM [initial terminal io] fd 0/1 @ #x80439ba> #<Function TOP-LEVEL-READ-EVAL-PRINT-LOOP @ #x804d22a> ...) (to see any ghost frames, the disassembler must be loaded) [1] USER(2): :res USER(1):
Example 2:
;; Note in this example a variable is inspected after setting it, ;; to indicate the state of the lisp before the new top-level is ;; pulled into the lisp. Note also that we wrap a progn which will ;; return a final nil value, so as not to see a huge printout due to ;; the lack of *print-level*/*print-length* controls. % mlisp -I umsloadxcomp.dxl -qq Loading /acl70/src/libacl70pf23.so. Mapping umsloadxcomp.dxl...done. Mapping umclxcomp.pll. Allegro CL 7.0 Copyright (C) 1985-2004, Franz Inc., Oakland, CA, USA. All Rights Reserved. // (progn (setq x (excl::get-objects 7)) nil) NIL // (require :toplevel) ; Fast loading /acl70/src/code/toplevel.fasl ; Fast loading /acl70/src/code/frame.fasl ; Fast loading /acl70/src/code/r/rframe.fasl T // (inspect x) ; Autoloading for INSPECT: ; Fast loading /acl70/src/code/inspect.fasl A simple T vector (5649) @ #x81a506a 0-> fixnum 5629 [#x000057f4] 1-> The symbol CL:NIL 2-> The symbol T 3-> The symbol EXCL::ER-WNAERR 4-> The symbol EXCL::ER-GENERAL-ERROR-HANDLER-ZERO 5-> The symbol EXCL::ER-GENERAL-ERROR-HANDLER-ONE 6-> The symbol EVAL 7-> The symbol EXCL::INTERPRETED-FUNCALL 8-> The symbol EXCL::+_2OP 9-> The symbol EXCL::GC-AFTER 10-> The symbol EXCL::*WITHOUT-INTERRUPTS* 11-> The symbol EQUAL 12-> The symbol *PACKAGE* 13-> The symbol *LISP-PACKAGE* 14-> The symbol *KEYWORD-PACKAGE* 15-> The symbol EXCL::INTERN* 16-> The symbol EXCL::FASL-FIND-PACKAGE 17-> The symbol EXCL::CONVERT-TO-INTERNAL-FSPEC 18-> The symbol *COMPILER-PACKAGE* 19-> The symbol *SYSTEM-PACKAGE* 20-> The symbol EXCL::CONVERT-TO-EXTERNAL-FSPEC 21-> The symbol SYS::LISP-BREAKPOINT 22-> The symbol EXCL::HANDLE-PENDING-SIGNAL 23-> The symbol EXCL::SET-FUNCTION 24-> The symbol EXCL::.INV-MACRO-FUNCTION ... 5648-> The symbol NIL [1i] USER(1):
The following variables are maintained or used by the minimal top-level:
Variable | Notes |
*read* |
Must be true - the function to be used to read top-level input. Initially set to read. |
*eval* |
Must be true - the function to be used to evaluate top-level input. Initially set to eval. |
*print* |
Must be true - the function to be used to print top-level input. Initially set to print. |
tpl:*read-eval-print-loop* |
Must be true - the function to be used as the
read-eval-print-loop. Initially set to the tpl::default-read-eval-print-loop
as shown in the code
above,
where tpl::default-read-eval-print-loop
is also defined. This variable only exists in minimal top-level lisps.
This variable does
not have a separate descriptions page. |
If *read-eval-print-loop*
is set to a value
other than tpl::default-read-eval-print-loop
, then the
three read/eval/print variables are not used. Normally, this variable
should not be set unless it is desired to remove all possible user
interaction with lisp. If a replacement top-level is supplied, it is
recommended that all possible errors be handled explicitly with
handlers.
The top-level variables in the table with links are also discussed in Top-level variables in top-level.htm.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |