generate-application

Function

Package: excl

ToC

DocOverview

CGDoc

RelNotes

Index

PermutedIndex

Allegro CL version 6.2
Minimally revised from 6.1

generate-application

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 icon-file demo image-only pure-files purify runtime-bundle... build-lisp-image keyword arguments...

See delivery.htm for a complete description of the issues and functionality associated with this function. Note that this function is only available in Enterprise versions of Allegro CL.

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 function 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 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-application. The section Use of custom.cl in building-images.htm has information on when sys:custom.cl is loaded when an image is built.

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 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. For a shortcut, the filename must have type "lnk" (the letter L, the letter N, the letter K). command line arguments are the arguments to application-name.exe. The filename argument should actually be 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 filename 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.lnk" "-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 an executable file named application-name.exe (on Windows) and application-name (on UNIX) is created.
If :dll, then the application will be used as a dll and no executable file is created. The dll used is the Allegro CL shared library, and the application itself will live in the newly created .dxl file. The Allegro CL shared library is used to initialize the Allegro CL runtime system, which loads the user's app in the .dxl file. See dll.htm.

If :ole-in-proc-server, a file is created in the destination directory called application-name.dll. See the OLE samples in ole/samples/sample05/ and ole/samples/sample06/.
autoload-warning: when true, the file autoloads.out is created that contains the functions, macros and methods that could possibly be autoloaded. Defaults to t.
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 mlisp on Unix or mlisp.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 true, 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 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 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-application. 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 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.
runtime-bundle: if specified t a bundle file named files.bu will be placed in the application directory. This file contains the modules allowable in a runtime image. This means that such modules need not be loading into the application image during the application build.
Further, locales and external formats will be available in the runtime bundle. If your application may need locales different from the locale current when the application image is built, or may load external formats not loaded into the image during the application build, they will be available for loading from the runtime bundle. See Retrieving Existing External-Formats and Locales in applications in iacl.htm.
runtime: the value defaults to :standard and must be either :standard, :dynamic or :partners. See runtime.htm.
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 specify files to be loaded. :lisp-files, even if specified, is ignored.

The function generate-executable is a wrapper for generate-application, producing an application whose input is the command-line arguments. It can be used either as a quick way to create an application, or as an example of using generate-application. The source for generate-executable can be found in the file [allegro cl dir]/src/genexe.cl.