Allegro CL FAQ 3.8: Building images

3.8: Building images

Q 3.8-1) I get an error when I try to build an image with excl:build-lisp-image (and also with excl:generate-application) but the build process simply quits. How can I debug this error?
Q 3.8-4) I notice that when I run generate-application, a license file is placed in the distribution directory. Is that license file tied to the image file?

Go to main FAQ page.

Q 3.8-1) I get an error when I try to build an image with excl:build-lisp-image (and also with excl:generate-application) but the build process simply quits. How can I debug this error?

A 3-8.1) Since generate-application calls build-lisp-image, the same answer applies to both functions.

excl: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). This new Lisp is started in a way that it will exit after an error without any user interaction. That is usually what is desired but sometimes being able to interact with the Lisp building the new image is desirable. You can do that by starting that image yourself. Here is how you do that:

1. Call build-lisp-image (or generate-application) with arguments (in addition to your own arguments)

:internal-debug "idout" :verbose t

"idout" is a filename -- any filename with any valid path will do. Here is what the build-lisp-image form looks like:

(excl:build-lisp-image <image-file> 
                       :internal-debug "idout" :verbose t <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. This example is from an SGI machine. For ease of reading, we have added linebreaks where indicated by [Added LB]:

USER(11): (build-lisp-image "foo.dxl" :internal-debug "idout" :verbose t)
; Fast loading from bundle code/build.fasl.
;; Running command: cat "idout" | "/tmp_mnt/net/spot/acl2/6.1.beta/bin/tru64/mlisp" [Added LB]
-build -lsfi -lxi -o 10m -Fa -llni [Added LB]
-B "/tmp_mnt/net/spot/acl2/6.1/bin/tru64/files.bu" -v [Added LB]
-c "/tmp_mnt/net/spot/acl2/6.1/bin/tru64/acli61.pll" [Added LB]
-FF...Initial generation spread = 1

The command is everything after the | through the -FF (so ...Initial generation spread = 1 is not part of the command). We did not put in an added linebreak at the end of the command to emphasize that printing after the command will likely not have a linebreak.

Also generated (by the :internal-debug argument) is the file "idout" which contains the Lisp forms passed to the spawned Lisp. The first few lines looks like:

(common-lisp:progn (common-lisp:format common-lisp:t "~% #|~% ~s~% |#~%"
                                       '(common-lisp:setq
                                         excl::*batch-mode*
                                         common-lisp:t))
                   (common-lisp:values)) 
(common-lisp:setq excl::*batch-mode* common-lisp:t) 
(common-lisp:progn (common-lisp:format common-lisp:t "~% #|~% ~s~% |#~%"
                                       '(common-lisp:setq
                                         excl::*break-hook*
                                         'excl::exit-on-error-hook))
                   (common-lisp:values)) 
(common-lisp:setq excl::*break-hook* 'excl::exit-on-error-hook) 
(common-lisp:progn (common-lisp:format common-lisp:t "~% #|~% ~s~% |#~%"
                                       '(excl:set-case-mode :case-sensitive-lower))
                   (common-lisp:values)) 
(excl:set-case-mode :case-sensitive-lower)

...

The first two setq lines (which should be displayed in bold) tell the Lisp to exit on errors. The remaining lines depend on the arguments passed and may be different when you run build-lisp-image (or generate-application).

You are now ready for the next step. Presumably, the failure you wished to debug has occurred but ignore that for now.

2. In a shell (or better, an emacs shell buffer) start the build image by executing the command line identified above (do not add the linebreaks which are here for ease of reading only):

MYMACHINE> /tmp_mnt/net/spot/acl2/6.1.beta/bin/tru64/mlisp" [Added LB]
-build -lsfi -lxi -o 10m -Fa -llni [Added LB]
-B "/tmp_mnt/net/spot/acl2/6.1/bin/tru64/files.bu" -v [Added LB]
-c "/tmp_mnt/net/spot/acl2/6.1/bin/tru64/acli61.pll" -FF

This will bring up a Lisp and you should get a prompt. Start evaluating the forms in idout skipping the first two setq forms. That is, do not evaluate these:

(COMMON-LISP:SETQ EXCL::*BATCH-MODE* COMMON-LISP:T)
(COMMON-LISP:SETQ EXCL::*BREAK-HOOK* #'EXCL::EXIT-ON-ERROR-HOOK)

but evaluate the later setq forms after those two, like:

user(4): (excl:set-case-mode :case-sensitive-lower)

(The progn forms with format calls need not be evaluated but evaluating them does no harm.)

When you get to the form that causes the problem, you should get a error prompt and can do a :zoom etc.

Q 3.8-2) [Question deleted because no longer relevant.]

Q 3.8-3) [Question deleted because no longer relevant.]

Q 3.8-4) I notice that when I run generate-application, a license file is placed in the distribution directory. Is that license file tied to the image file?

A 3.8-4) There is a license file created when generate-application is called. It is named <application-name>.lic and is placed in the distribution directory. It must be there to run the application and it is tied to the application image (dxl) file: it only works with that image file and that image file only works when the license file is present. If you have to update the image file (for example, to add new features to the application or to fix bugs), be sure to create the new image using generate-application (which will, of course, create a whole directory of files including the image and a new license file) and be sure to send at least both the image and the license file to the application users. (The more typical thing to do is to send the whole directory.)