build-project

Generic Function

Package: common-graphics

Arguments: project &key distribution-directory replace-if-exists exe-only autoload-warning completion-dialog

Calls either build-lisp-image or generate-application, passing various properties of the project as arguments in order to build a standalone executable for the project. This is the programmatic equivalent of the File | Build Project Distribution and the File | Build Project Exe menu commands. This function also emulates certain other functionality of these IDE commands that is not provided by build-lisp-image or generate-application, such as imbedding the project's icon file in the generated executable, and recompiling it with :runtime-system in the *features* list if the property's full-recompile-for-runtime-conditionalizations property is turned on. This function may be useful for automating the building of standalone executables for a project.

The arguments are:

project: The project for which to build a standalone executable or complete distribution. The project may be either the project that is currently open for editing (the value returned by current-project) or any project that has been loaded into the current IDE session by calling load-project.
distribution-directory: The pathname or path namestring of a directory in which to place the generated distribution. Used only if exe-only is nil, in which case it must be passed. Should be either a new directory or an existing distribution directory to be replaced by passing replace-if-exists as true.
replace-if-exists: Used only if exe-only is nil and the specified distribution-directory already exists. In this situation, if replace-if-exists is true then the distribution-directory and all of its subdirectories and the files contained in those directories are all deleted, and then the new distribution is created in a new directory at the same path. (Note that no warning is given.) If replace-if-exists is nil (the default), then an error is signaled.
exe-only: If true, then build-lisp-image is called to create a standalone executable for the specified project. If nil (the default), then generate-application is called to create a standalone executable and place it with other files to be distributed into a new directory; this directory must be specified as the value of the distribution-directory argument.
autoload-warning: This argument is passed straight through to either build-lisp-image or generate-application, to create an autoloads.out file to report on autoloadable functions. The IDE menu commands pass true for this argument, but nil (the default) may be more appropriate for an automated build in order to avoid an interactive modal dialog that mentions the autoloads.out file.
completion-dialog: If true, a modal dialog with beep is presented to inform you that the process has completed. The modal dialog is a "topmost" window so that it will appear in front of other applications to which you may have shifted your attention while waiting for the build to complete. The IDE menu commands pass true for this argument, but nil (the default) may be more appropriate for an automated build in order to avoid the interactive dialog.

Here's a technique to automate starting up an IDE, loading a project, generating a standalone distribution, and exiting: Place code similar to the following at the top of your startup.cl file. (If this file does not exist, simply create one. startup.cl is used here because it is loaded only after the IDE has finished coming up.) This particular example will make a distribution for the IDE's form-building tutorial.

(in-package :cg-user)

(when (member "build-tutorial" (sys:command-line-arguments
                                :application t)
              :test #'string-equal)
  (let* ((project (load-project
                   (merge-pathnames
                    "tutorial/final/interface-builder-tutorial.lpr"
                    (translate-logical-pathname "sys:"))
                   :compile nil))
         (destination "c:/tutdist/"))
    (build-project project
                   :distribution-directory destination
                   :replace-if-exists t))
  (exit))

The above code will run whenever "build-tutorial" is passed as an "application argument" in the command line that is used to start up lisp. ("Application arguments" are all those following a "--" in the command line.) Such a command line, which could either be placed in a .bat batch file to be double-clicked or be used in a Windows Start Menu command, could be as simple as this:

c:\acl6\allegro.exe -- build-tutorial

To build your own projects this way, simply replace the pathnames and command-line argument name in the sample code above, or customize it further as desired. Multiple application arguments could even be used to build the distributions for a set of projects automatically.

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.