generate-application

$Revision: 5.0.2.7 $

Function

Package: EXCL

Arguments: (application-name destination-directory input-files &rest rest &key allow-existing-directory application-files application-administration application-type copy-shared-libraries copy-file-function debug image-only pure-files purify ... <excl:build-lisp-image keyword arguments> ...)

See delivery.htm for a complete description of the issues and functionality associated with this function.

This function writes a collection of files to destination-directory. In theory, all the files needed to deliver an application will be in that directory when generate-application completes (but you should test that carefully).

Note that this function calls build-lisp-image and like build-lisp-image, this functions does not inherit from the currently running image (except for the defaults for certain arguments).

The required arguments:

application-name: the name of the application (i.e., "myapp"). When coerced to a pathname, this name should not have a directory or type. It is used to create the name of the executable or .dll or .so or .sl (whichever is appropriate for the platform) and ancillary files.
destination-directory: the name of a non-existent directory. It is the directory used to create the output files. See image-only keyword argument below.
input-files: the list of Lisp (.fasl or .cl) files to be loaded, strings or pathnames. Symbols are allowed and signify modules to be loaded with cl:require. These files are loaded after sys:custom.cl is loaded. Note that this argument supersedes the build-lisp-image argument :lisp-files. That argument is ignored even if specified to generate-applciation.

The keyword arguments:

allow-existing-directory: allow destination-directory to exist. If the value of this keyword argument is nil and the directory exists, then an error is signaled.
application-files: files which should merely be copied to the destination directory.

application-administration: allows the specification of various application administrative tasks. The form of the value of this keyword is

(type-keyword ...)

((type-keyword ...) (type-keyword ...) ...)

(type-keyword ...) can be:

(:resource-command-line "...command line arguments...") [UNIX only]

This creates a lisprc in the destination directory which sets the default command line arguments to ...command line arguments.... See the 4.1 Resources section in delivery.htm for more information.

([:shortcut | :batch-file] filename ...command line arguments...) [Windows only]

This creates either a batch file or a shortcut named filename that will initialize the application. command line arguments are the arguments to application-name.exe. filename is actually a format control string given one argument, the name of the application. It is used like this: (format nil filename application-name). This allows the customization of the generated file name based on information generate-application has already been given.

One use of this is for OLE registration. For example:
'(:shortcut "One-time registration of ~a" "-register")
If the given application-name was "foo" this would create a shortcut named One-time registration of foo with the following command line:
foo.exe -- -register

An error is signaled if application-type is not :exe.

application-type: valid values: :exe, :ole-in-proc-server, or :dll. If :exe is used, then application-name.exe is created. If :ole-in-proc-server or :dll is used application-name.dll is created.
autoload-warning: when non-nil, the file autoloads.out is created that contains the functions, macros and methods that could possibly be autoloaded.
build-executable: this is a build-lisp-image keyword argument but is also used by generate-application if a value is supplied. The value must name a Lisp executable file (such as lisp on Unix or lisp.exe on Windows -- those are the defaults). It is used by build-lisp-image to start the Lisp process that builds the image. Unless image-only is true, generate-application copies a Lisp executable to the application directory. The executable specified as the value of this argument is the one copied.

copy-shared-libraries: if non-nil, then copy shared objects/libraries that have been loaded with the Common Lisp function load by the time the image is dumped. The value of this keyword argument can also be a lambda expression (you cannot use the function special form, the value must be a list), accepting one argument, that is a predicate which determines if the loaded shared objects should be copied. The one argument is the pathname of the shared object file (the original pathname given to load). The predicate should return t if the shared object is to be copied, and nil if it is to be ignored by shared-library copying process. The predicate can also return a relative pathname, which will be used as the name of the copied shared library relative to the destination-directory. Note: shared libraries may be specified without a directory path and found using Operating System tools (such as LD_LIBRARY_PATH or PATH), as described in section 1.4 Load foreign code with cl:load in the foreign_functions.htm document. However, the shared library copying functionality will not use Operating System tools to find shared libraries. If a shared library is specified without a directory path and is not in the current directory, it will not be found.

For shared objects that are copied, the image that is created will load them from the destination directory upon startup. That is, in the image built by generate-application, the name of the shared libraries loaded on startup will be sys:<name>, for each <name> copied by generate-application.

copy-file-function: This function will be used to copy files to the destination directory. The default value is sys:copy-file and that function is likely sufficient for most purposes. However, another function can be used if that is insufficient. This function will be called by the image that calls generate-application (not the image that builds the image).
debug: more information will be printed about progress as an aid to debugging.
image-only: just build for the image, and possibly the .pll file.
lisp-files: this build-lisp-image keyword argument is ignored by generate-applciation. The list of files specified as the value of the required input-files argument is used instead.
pure-files: a list of .cvs and .str files to be put into the application's .pll file. See 4.0 Creating and using pll files in miscellaneous.htm.
purify: do automatic purification of Lisp and the application. This means all the strings and code vectors will be put into a .pll file. If you choose this option, do not also specify a value for pure-files.
build-lisp-image keyword args: generate-application accepts and passes through to build-lisp-image all of build-lisp-image's keyword arguments except for :lisp-files. The require input-files argument is used to specifiy files to be loaded. :lisp-files, even if specified, is ignored.

See delivery.htm for a complete description of this function.

The general documentation description is in introduction.htm. The index is in index.htm.