generate-executable

Arguments: name input-files &rest rest

Please note that this function is only available in images licensed for creating runtime images. All Enterprise and above customers are so licensed.

This function is a wrapper for generate-application, producing an application directory containing an application executable/image and other necessary files.

name should be a string naming the application. A directory will be created with that name (with path merged with *default-pathname-defaults*) for the application files (that directory must not already exist). The image file and the executable will have filename name.

input-files should be a list of files to be loaded into the application. input-files corresponds to the input-files (third required) argument to generate-application. Modules can be specified with keywords which are suitable as arguments to require. (Thus, placing :sock on the list causes the Socket module sock.fasl to be loaded; placing :foreign-functions on the list causes the Foreign Functions module, foreign-functions.fasl, to be loaded, and so on.)

One of the input-files should define a function named by the symbol user::main. This function should accept any number of arguments (that is, its argument list should be (&rest rest)) and initiate whatever computation is to be done by the application.

When the application starts up, all the command-line arguments (including the executable name but not the -I or the image name) are collected (as a list of strings) and user::main is called with those strings as arguments, as with the form

(apply 'user::main [list of command-line argument strings])

The rest arguments should be keyword/value pairs where the keyword names a keyword argument to generate-application.

generate-executable processes its arguments and calls generate-application with a bunch or keyword arguments specified. See the source for the function in the file [allegro cl dir]/src/genexe.cl for information on what keyword arguments are specified and what values are given to them. We discuss some keyword arguments in the notes below.

A note about modules

Allegro CL images do not contain all modules by default. Instead, modules (for functionality like foreign functions, contained in the :foreign-functions module, and sockets, contained in the :sock module) are loaded when needed. The loading may be automatic (see Autoloading in implementation.htm) or may need an explict call to require.

But the important fact to consider when building an application is that modules will not be available in an application unless the module is loaded during the application build or the :runtime-bundle keyword argument is specified true in the call to generate-application and thus in the call to generate-executable.

See Including all desired modules in delivery.htm. Also, generate-executable generates a file autoloads.out which tells you what modules might be autoloaded in your application (that is, which autoloadable modules are associated with functions in your application) and you can decide whether it is necessary to include the module.

Command-line arguments

The ignore-command-line-arguments keyword argument to generate-application is specified true in the call to generate-executable unless you specify :ignore-command-line-arguments nil in the rest. (ignore-command-line-arguments is actually an argument to dumplisp. generate-application accepts it (and all dumplisp arguments) and simply passes it through.)

The command-line arguments that are ignored are the ones prefaced by a - (i.e., a dash) specified in Command line arguments in startup.htm. Arguments prefaced by a + (which are for Windows only) are never ignored. Note: if you specify :ignore-command-line-arguments nil, then the - prefaced command-line arguments specified to the executable will not be passed to the main function as described. Instead, your main function must access the arguments itself using functions like command-line-arguments.

Calling generate-executable when the directory name exists

generate-executable passes nil as the value of the allow-existing-directory keyword argument to generate-application. This means if generate-executable is called with name naming a directory that exists (as would happen, for example, if generate-executable is called twice with the same name without removing the application directory between the calls), a continuable error will be signaled because the directory exists. One restart instructs the system to remove the directory and continue. Aborting and removing or renaming the directory and changing the name so it does not name an existing directory are other options.

Example

Here is an example using generate-executable:

;; If foo.cl contains:

(in-package :user)

(defun main (&rest args)
  (format t "args: ~s~%" args)
  (force output)
  ;; we sleep for a bit so the args can be seen when
  ;; a window which disappears is used.
  (sleep 5)
  (format t "slept 5 seconds.~%")
  (when (string= "foo" (second args))
    (error "foo!")))

;; and then the application can be built with this:

cl-user(7): :cf foo.cl
;;; Compiling file foo.cl
;;; Writing fasl file foo.fasl
;;; Fasl write complete
cl-user(8): (generate-executable "foo" '("foo.fasl"))
;;; Compiling file /net/killer/tmp/fooa52fe1e.cl
;;; Writing fasl file /net/killer/tmp/fooa52fe1e.fasl
;;; Fasl write complete
Initial generation spread = 1
Allocated 10492920 bytes for old space
Allocated 5242880 bytes for new space
...
cl-user(9): 

;; Example run:

% foo/foo 1 2 3
args: ("foo/foo" "1" "2" "3")
% echo $status
0
% foo/foo foo 1 2 3
args: ("foo/foo" "foo" "1" "2" "3")
foo!
% echo $status
1
% 

See generate-application, building-images.htm and delivery.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.