ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0

# 4. Projects

This chapter contains the following sections:

> 4.1 Configuration options
> 4.2 A project example
> 4.3 The Project Manager dialog
> 4.4 The project .lpr file
> 4.5 Types of modules in a project
> 4.6 More on adding modules to a project
> 4.6.1 Subprojects
> 4.7 How files are displayed in the Modules tab of the Project manager
> 4.8 Changing the order of files in a project
> 4.9 Opening a new project
> 4.10 Opening an existing project
> 4.11 Compiling a project
> 4.12 Project before and after functions
> 4.13 Saving a project
> 4.14 Running a project
> 4.15 The main form
> 4.15.1 Does a project need a main form?
> 4.15.2 The Project package
> 4.15.3 The Project name
> 4.15.4 The Project init function
> 4.15.5 Running secondary form windows programmatically
> 4.16 The Project Manager Build tab
> 4.17 The Project Manager Include and Advanced tab
> 4.18 The Project Manager Version Info tab
> 4.19 Building the application
> 4.20 Modifying the .lpr file

This is chapter 4 of the User Guide for the Allegro CL 11.0 Integrated Development Environment (IDE).

The chapters of the IDE User Guide are:

> Chapter 1: Introduction to the IDE
> Chapter 2: The Allegro CL Development Environment (IDE)
> Chapter 3: An example
> Chapter 4: Projects (this chapter)
> Chapter 5: Components
> Chapter 6: Designing a user interface using forms
> Chapter 7: Menus
> Chapter 8: Events

A project is a collection of modules used to build an application. Allegro CL provides tools for managing projects. In this chapter, we describe how to create and manage projects, how to add modules to the project, and how to convert the project into an application ready for delivery.

In the Allegro CL Development Environment, there can only be one project open at a time, which is the current project. The project window, with the menu bar, displays the name of the current project in its title:

In the illustration, the current project is Project20.

### 4.1 Configuration options

As with many things in Allegro CL, behavior dealing with projects is configurable. Bring up the Options dialog by clicking Tools | Options and select the Project tab:

The initial option values are displayed in the illustration. The options are:

New Project Action: when a new project is created, the Project Manager and an editor workbook are (Show Project Manager and Show Editor checked) or are not (unchecked) displayed, and a new form is (Create a Form checked) or is not (unchecked) created.

Open Project Action: upon opening an existing project, only files that have no compiled counterpart or whose compiled counterpart is out of date are compiled (Compile As Needed is chosen, as in the illustration) or all files are compiled (Full Compile is chosen). If No Compile or Load is chosen, no compilation will be done and no files will be loaded. (That option is useful when compilation or loading causes an error.) You can also choose to have the Project Manager displayed and the project source files opened in the editor.

Run Project Action: just before running the current project, its files will be or will not be saved and/or compiled based on this option's setting. In the illustration, when a form is run, the files will be saved and incrementally compiled (Save and Compile as Needed is chosen).

> A check box near the bottom right allows you to have project files opened in the editor closed when the project is closed.

In this chapter, we describe the default configuration. We usually note where a configuration option may change behavior in the text but if you are seeing behavior different from what is described, check your project options as that may explain the difference.

### 4.2 A project example

The tutorial supplied with Allegro CL creates a project called :interface-builder-tutorial (producing the doodler application). It draws cycloidal curves in a window and allows you to set the background and line colors and to modify the curve being drawn. We will use this project as an example. You can bring up that project by clicking on Open Project in the File menu and then opening the file interface-builder-tutorial.lpr in <Allegro directory>\gui-builder-tutorial\final folder.

### 4.3 The Project Manager dialog

Information about a project is displayed in the Project Manager dialog, displayed by clicking Project Manager on the View menu. The current project displayed is the :interface-builder-tutorial project associated with the Tutorial.

This dialog lists the form, libraries, other projects and source files associated with the current project. We will describe the things listed below. Most information about a project is displayed in the various tabs of the Project Manager dialog and tools on the dialog allow modifying projects as desired.

### 4.4 The project .lpr file

Each project has an associated file with extension .lpr. This file is generated automatically when a project is saved. All information displayed visually in the Project Manager dialog is stored in the .lpr file. The file is updated whenever the project is saved. Projects are saved by clicking File | Save All at any time (all files associated with the project are saved, not just the .lpr file). Whenever you run a project or exit Allegro CL, you are prompted to save the project files as well.

Editing the .lpr files directly is discouraged except for several advanced capabilities that cannot be specified from the Project Manager dialog (particularly before and after functions – see 4.12 Project before and after functions below). Except for these advanced capabilities, projects should be managed using the Project Manager dialog.

You can view (and edit, if necessary) the current project .lpr file by clicking on the View Project Source button of the Project Manager toolbar.

In addition to storing information about a project in a file, you can include one project in another (as a sub-project) by including (adding) the sub-project's .lpr file to the modules of the current project.

### 4.5 Types of modules in a project

The modules associated with a project are displayed in the Modules tab of the Project Manager. Each module is a collection of one or more files. Modules can be added or deleted from a project by clicking on the + button on the Project Manager toolbar (to add) or selecting a file in the project and clicking on the x button (to delete).

The following list shows the types of modules which can be included in a project.

Form module. A form module has two or three files, all with the same name but different extensions. The Project Manager list shows the filename only. Following the filename is information on whether the module is saved and if so, the location of the .cl file relative to the current directory is displayed. The three types of files associated with a form module are:

> A source file (.cl)

> . This file has definitions of functions and other objects (classes, parameters, etc.) needed for the form. It is created automatically and can be modified by the editor workbook. The starting code for event handlers is automatically added to the source file of the form module. You can add any other code to the source file that you would like associated with the form. It is very common that you will define the class of the form in its source file.

> A builder file (.bil)

> . The bil file is automatically created when you save a form. The bil file contains information about the appearance of the form as well as its components. You must not edit the bil file because your changes could be lost the next time that you save your form. Instead, add your code to the source file. The bil file contains two function definitions based on the name of the form. It does this by defining two functions, one with the same name as the form (if the form is named myform, the function is named myform) and the other with the name of the form prepended with make- (make-myform).

> A bitmap (.bml) file

> . This file is automatically created when you save a form if any of the components in the form have bitmaps. For example, the bitmap providing the picture of a picture button would be included in this file. The bml file contains a description of the bitmaps used in the form (saving you from having to manage the bitmap files).

> A project may contain any number of forms. One is identified as the main form as described below.

> It is possible to add an existing form module to a project by clicking on + and specifying the form's .cl or .bil file but this is not recommended..

> To add a new, blank form, click on New Form on the File menu. A blank form named formn, where n is a number that makes the name unique, is created and added to the end of the list of modules in the project.

> Forms are displayed in the Project manager modules tab. Each is listed with an icon shown. The main form first (icon is a speeding window) followed by two source files and then two more forms (and more that are cut out of this illustration):

> A list of form and source modules in a project is returned by the modules function.

> `(modules (current-project))`

> returns a list of the form and source modules in the current project. The functions finder-function and maker-function may be called on a form module to find the names of the auto-generated functions in the .bil file for creating the module's running window.

> Other source (.cl) files

> . These files typically define additional functionality for the application. Add a new source file by clicking on + and specifying the .cl file you want to add. If a source file is already in the editor, it can be added quickly to the current project by right-clicking over its editor pane and selecting Add File to Project from the shortcut menu that is displayed. Note that both forms and source files can be specified with .cl file. The system knows you mean a form if there is a .bil file with the same name and in the same folder. If there is no corresponding .bil file, the system knows you mean a source file. Source files are displayed in the Project manager modules tab with an icon of a piece of paper with the upper right corner turned down (see util.cl, the second entry, in the illustration above).

> Other project (.lpr) files

> . The ability to include one project within another allows modularity. Add a subproject by clicking on + and specifying the subproject’s .lpr file.

> A list of project modules in a project is returned by the projects function.

> `(projects (current-project))`

> returns a list of the projects in the current project.

> Library files (.dll files)

> . These are foreign libraries that will be loaded into the application. See the description of the foreign function interface foreign-functions.html for information on using foreign code in an application.

> A list of library modules in a project is returned by the libraries function.

> `(libraries (current-project))`

> returns a list of the libraries in the current project.

> Distributed files (any type). A distributed file is one which will be included with the project distribution but will not be compiled or loaded into the image. Such files might include a data file needed for the application, license files particular to the application, etc. See distributed-files.

> Distributed directories. A distributed directory will have its entire contents copied to the distribution directory for the standalone application of the project. This is similar to a set of distributed files, but is easier to select interactively as a single directory, and it avoids cluttering up the main directory of your distribution. The paths for distributed directories are stored in the project's distributed-files property along with individual distributed files.

> Editable files. These are files that are neither compiled & loaded nor distributed, but are still accessible in the Project Manager. See editable-files.

### 4.6 More on adding modules to a project

Files can be added to a project when a new form is created using New Form on the File menu or when a previously unsaved editror buffer is saved (you are asked if the file should be added to the current project). Files can also be added to a project by clicking the + button on the Project Manager toolbar. Clicking that button causes the following dialog to appear, which asks what sort of file you wish to add:

You select the type of file, and click OK. These files are neither compiled nor loaded into the application image, but they can have any extension, so the extension alone does not determine the type of file.

Adding an existing form. As stated earlier, raw form descriptions in the Allegro CL Integrated Development Environment are stored as .bil files (ie, files whose names have 'bil' extension). A complete form description consists of two or three files with the same name but with extensions .cl, .bil, and (if present) .bml. For example, myform.cl, myform.bil, and perhaps myform.bml. Normally, a user does not directly handle .bil files as they are associated with corresponding .cl files. When you choose FORM from the list in the dialog above, you are asked for the .bil file.

Adding an existing project. When you choose PROJECT from the list in the dialog above, you are asked for the project .lpr file (see 4.6.1 Subprojects for more information on subprojects). Note that if a particular form already belongs to a project, we do not recommend adding it directly to a different project. Instead, you can include the project containing the form as a subproject.

Adding a code, library, distributed file or directory, or editable file. When you choose CODE, you are asked for a Common Lisp source file (with extension typically .cl). When you choose LIBRARY, you are asked for a .dll file. When you choose DISTRIBUTED FILE, no specific extension is specified in the file choice dialog that appears. DISTRBUTED DIRECTORY asks for a directory. EDITABLE-FILE asks for an editable file.

Adding a new form. New forms can be added to a project by clicking New Form on the File menu while a project is open. You will be prompted for the type of window associated with the form (that is, the type of window that will be created when the application is run). The usual choice is dialog but see chapter 6 for more information of the type of window to choose. Once the type of window is chosen, a new form is opened and added to the list of modules in the current project.

Where modules are added

. Form modules and code modules are processed together as are subproject modules and library modules, so it is only the position of a module with respect to other modules processed with it that is important. However, the ordering of modules that are processed together can make a difference. In general, you want definitions (of functions, macros, variables, etc.) to precede use. You can change the order by selecting a module and clicking on the up or down arrows, which will move the module up or down within the list of modules.

### 4.6.1 Subprojects

A subproject (or child project) of project foo is a project that is automatically loaded whenever you open project foo for editing in the IDE. The subproject's code will also be included in the standalone application that you generate for project foo. A subproject typically contains utilities that are used by one or more other projects, and are useful for dividing a project into smaller modules for manageability.

If you haven't used subprojects before and would like to try them, you can make an existing project foo load another existing project bar as a subproject as follows:

1. Open foo as the current project.
2. Press the Add File button on the left end of the Project Manager's toolbar (its icon is a plus sign) to add a new module to project foo.
3. Select the PROJECT option when a dialog appears asking which type of module to add. You will then be prompted to select the .lpr project definition file of another project, and here is where you would select project bar.

After selecting the subproject, it will appear near the top of the list of modules for the open project. (Subprojects are always loaded before the open project's own code so subprojects appear above any form or source code modules.) Here is the Modules tab for project foo after project bar has been added:

If you click on the blue arrow (or double-click the subproject item anywhere, or select the item and press the right arrow key), then the subproject's own modules will be listed just below the subproject in the module list, and indented to show the hierarchy, as illustrated:

Not only can you now see what modules are in the subproject, but you may now access any module of the subproject just as you could modules of the current project previously. So you could, for example, double-click a code module that's in a subproject to edit its source code, or double-click a form module to show its form window, and then edit the form. Or right-click any module to invoke those and other commands from the pop-up menu.

A subproject may itself have further subprojects, and the entire hierarchy of project modules may be accessed from the project manager.

Whenever you use the File | Save All command, the project system will save any files that need to be saved for the current project and any descendent projects in the hierarchy. This includes regenerating the .bil file for any form that you've modified in any subproject, and regenerating the .lpr project definition file for any subproject whose contents have changed.

One thing that may be confusing is adding a new module to a project. You can add a new module to a subproject, but first you need to select either the subproject itself in the list of modules, or select one of the (non-subproject) modules that are in that subproject. Then when you click the Add File button, a dialog will first ask whether you want to add a module to the current (top-level) project or to the selected subproject. Otherwise it wouldn't be obvious where the new module would end up. If you press the button for the selected subproject, you can then proceed to select the module to add to the subproject. This could even be another project to add as a subsubproject.

An auxilliary feature is that you can right-click a subproject in the list of modules and select Open Selected Project from the pop-up menu to make that project be the current project, though there's actually less need to do that now. One time you may need to open a subproject is to add a new form to it, because at this time you still can't create a new form directly into a subproject of the current project.

### 4.7 How files are displayed in the Modules tab of the Project manager

The illustration shows the Modules Tab of a Project Manager listing a number of modules. We have added a library (dll file), a subproject (lpr file), and a distributed file to the :gui-builder-tutorial project for this illustration only:

The project has a single library called linkacl.dll, a single sub-project called project1 and a single distributed file (c:\temp\sort-test.cl, indicated with a gray circle) along with the forms and source files of the interface-builder-tutorial project.

Location of files: all modules are given paths relative to the project file if they are in the same folder or subfolders of the project file. All the forms and source files are in the same folder as the project file. The library and the subproject are specified with absolute paths because they are not located in the project folder or one of its sub-folders (when you add them, you are asked if you want them moved or copied; in this case, they were neither moved or copied to the project directory).

The order in which modules are listed: libraries (.dll files on Windows), sub-projects (.lpr files) and other files (source files and forms) are treated separately, so order within those types of modules is what is important. All library modules are loaded first, and all sub-project modules next, both in a depth-first order. Then all source and form modules are loaded in the order that they are specified. In this example, the load order is:

lnkacl project2 doodler util cycloid curve-dialog coefficient-dialog colorx background-palette

The appointment file is not loaded. It is a distributed file, so it is included in the project directory but not loaded as part of the project. (Examples files, test files, template files, etc. are all examples of distributed files. The documentation for users of the application typically describes distributed files and their purpose.)

Compilation of form and source files follows the same order as loading, with each compiled file being loaded before the next is compiled.

### 4.8 Changing the order of files in a project

As said just above, library (.dll) modules, sub-project (.lpr) modules, and source and form modules (.cl) are all handled separately, so order only matters within those file types. Files can be reordered (among other modules processed together) by selecting a module (so it is highlighted) and moving it up or down with the up- and down-arrow buttons on the tool bar.

### 4.9 Opening a new project

Choose New Project from the File menu. The current project will be closed (only one project can be worked on at a time) – you will be prompted to save files associated with the project being closed if necessary. You are then asked to specify a project directory with a dialog like this:

Once the directory is decided, the new project will be created.

### 4.10 Opening an existing project

Choose Open Project from the File menu. The open dialog will appear. Specify the .lpr file associated with the desired project.

### 4.11 Compiling a project

If you click Tools | Compile Project, all source files (.cl and .bil) that have been modified since the last compile are compiled and loaded and the project file is compiled and loaded.

If you click Tools | Full Compile, all source files and the project file are compiled and loaded (each file is loaded after it is compiled and before the next file is compiled).

Incremental compilation (with Tools | Compile Project) is usually satisfactory when working on a project and is faster because only a few files (typically) need be compiled. Full compilation is necessary when changes to one file result in changes to another file even though that file is not modified. For example, suppose in the project illustrated above, a macro is defined in utils.cl which is used in doodler. If you change the macro definition in utils, doodler should be recompiled even though it has not been touched because uses of the macro in doodler must be re-expanded. (Recompilation is not necessary when a function defined in util.cl and used in a later file or form is redefined since changes in function definitions are automatically tracked even in compiled code.)

Compilation of a source (.cl) file results in a .fasl file, of the same name.

Whenever a project is compiled, before functions are called before the compilation and after functions are called after.

### 4.12 Project before and after functions

Before and after functions are zero-argument functions which are called before any loading within the project (before functions) and after all loading is complete (after functions). When you compile a project, all files are loaded even if they are not compiled. Before and after functions are useful, for example, for modifying the environment appropriately for the compilation (before functions) and restoring the environment after the compilation. Before and after functions are accessed with before-functions and after-functions but are not specified on the Project Manager dialog. Before and after functions are added with setf and before-functions and after-functions.

### 4.13 Saving a project

All modified and unsaved files associated with a project are saved when Save All is chosen from the File menu.

Note that certain other actions, such as opening a new project or exiting Allegro CL, causes you to be prompted to save all files associated with the current project.

### 4.14 Running a project

Click on Run | Run Project. The Init Function of the project will be run in a separate thread. The default Init Function creates and displays the window associated with the main form and the function returns the window object (a stream). If you have not arranged to display other windows in the project programmatically, you can run forms other than the main form by selecting the form of interest and clicking Run | Run Form. Clicking Run | Stop hides the running window and displays the form. Running a project executes the initialization function of the project.

As we said above, by default, the initialization function of a project calls the maker-function for the project’s main form which creates and displays the window associated with the main form only. Any other windows (associated with forms other than the main form) are not displayed by default and must be displayed programmatically. How they are displayed is part of your application. Looking at the interface-builder-tutorial (doodler) project, for example, there are several windows some of which are displayed along with the main form window and others are displayed by user action.

### 4.15 The main form

One form associated with a project is identified as the main form. The main form is defined by the property that (assuming the default project init function is used) the window associated with it is the primary window of the application. That means that closing it (when the application associated with the project is run) exits the application. You can have many other windows in your application but only one primary window. Usually, the primary window is the first window displayed when your application is run and it is the only one displayed by default.

If there are many forms associated with a project, one must be identified as the main form.

The forms associated with a project are listed on the Options tab of the Project Manager dialog. In the illustration, the four forms associated with the project are listed. The selected form (in this case doodler) is the main form. This can be changed by simply selecting another form on the list.

### 4.15.1 Does a project need a main form?

A project can have no associated forms. The application built with the project will thus have no windows. Also, projects designed to be sub-projects of other projects may have no need of windows. For window-less projects, you must specify an initialization function. The initialization function can do whatever you want including writing to files, monitoring sockets, etc. The initialization function is specified in the Init Function box on the Options pane of the Project Manager and may be retrieved or set programmatically with on-initialization and its setf.

### 4.15.2 The Project package

A project has a project package associated with it. This package is specified on the Options tab of the Project Manager dialog, in the Package field. The value should be a symbol naming a package. The package of a project specifies the default package for all forms in the project. Individually you can specify the package of any form but the initial package of a form is determined by the package of the project. When a form is added to a project, the source file of a form has an in-package statement added.

### 4.15.3 The Project name

Projects are named with symbols. The symbol naming a project is specified in the Name field of the Options tab of the Project Manager. We recommend using a keyword for names, as we have done. The name can be used with find-project to programmatically find the project with the specified name.

### 4.15.4 The Project Init Function

The init function is called (with no arguments) when the project is run. It is also run when the application associated with the project is started. The initialization code looks like this, in part:

    (let (main-window (<project-init-function>))
        (loop
          (if (not (open-stream-p main-window)) (exit)
            (process-single-event)))

(We are showing the structure of the code, not the actual code.) We note from this code-like fragment:

1. The init function typically should return a window (which is a type of stream). The default init function returns the window associated with the main form and whatever window is returned, closing that window will cause the application to exit. On the other hand, the application will run until that window is closed unless exit is called by some other means.
2. Events are processed in each iteration of the loop. Therefore, actual work must be triggered by some event. One might have a button labeled Go or Do It and clicking that button could do the work of the application and display the results. In the tutorial (doodler) application, clicking the Draw All button causes the defined curves to be drawn in the doodler window.
3. An init function is free to do as much work as you want. Its only requirements are that it return a window and not need any arguments. You may want to create, display, and close a window in the init function. Such a window could take a password from the user (and exit if the password is invalid) or take configuration information from the user before displaying the main window. Note that you must call process-single-event, if necessary, in order to have events in the window handled.

If closing the main window is not an adequate technique for exiting an application, an alternative is to place the event-handling loop shown above directly in your own on-initialization function, and exit the event-handling loop when the application should exit. If you do that, make sure that the init function does not return a window.

### 4.15.5 Running secondary form windows programmatically

When you use the Run | Run Project command or start up a standalone application that was generated from a project, a window is created from the main form of the project automatically; you do not need to write any code to do this. But typically an application's main window will invoke other windows when the user clicks on certain widgets or otherwise requests particular windows to be shown.

If these windows were designed interactively as forms, then the application needs to know how to create these windows programmatically, such as in an on-change event handler function of a button widget.

The best way to create a window from a form programmatically is to call the finder-function or maker-function for the form. These functions are generated automatically whenever you save a form, and their names follow a simple rule so that you can know what function to call to create a window from the form.

Specifically, the finder-function name will be a symbol having the same name as the form, and the maker-function's name will be a symbol whose name consists of the string "make-" followed by the name of the form. So if the name of the form is `:form2`, then the finder-function will be `form2` and the maker-function will be `make-form2`. Both symbols will be in the form's package, as set via the form-package-name property of the form in the inspector. If you later change the name property (or the form-package-name property) of the form and save the form again, then the generated functions will have corresponding new names as well.

Here is an example of an on-change event-handler for a button widget that would create a second window from a form named `form2`, making it owned by the first window so that it will shrink and close along with the first window:

    (defun form1-button1-on-change
        (button new-value old-value)
      (declare (ignore new-value old-value))
      (select-window
       (make-form2 :owner (parent button)
                   :title "This is Form 2"))
      t)

The finder-function returns a window that has already been created from the form if one exists, otherwise creating and returning one, while the maker-function always creates a new window and returns it. The finder-function takes no arguments, and always creates the window (when it does create one) as a non-owned top-level window with the properties that were specified at design time. The maker-function, on the other hand, has a number of keyword arguments that allow creation of the window as an owned or child window of any other window and with a custom position, size, name, title, and/or border. The names of the maker-function's keyword arguments are owner, child-p, exterior, name, title, and border, and have the same meanings as with the function make-window.

Since the names of the finder-function and maker-function are predictable, there is typically no need to look at the actual generated source code for them. But if you do wish to view it, it can be found in a source code file with the extension .bil at the path where you specified to save the form. For example, if you save a form to the file second-form.cl, then the file second-form.bil is created containing the auto-generated finder-function and maker-function for the form.

While it is possible to edit a .bil source code file directly, it is so dangerous that it is better never to do so. It is dangerous to do so because if you later save the form itself then your edited code will be overwritten by newly auto-generated code. Note that in addition to saving a form explicitly by invoking the File | Save command on it, the form could easily be saved inadvertantly if you have interactively made any changes to it (even by accidentally moving it a bit) if you sometime later use the File | Save All command in any window or if you say OK when a dialog asks if you want to save various current modifications. A warning dialog will appear for these reasons if you do in fact attempt to save a .bil file in the editor.

See also the help pages for finder-function and maker-function, which return the names of the generated functions programmatically.

### 4.16 The Project Manager Build tab

This tab of the Project manager allows specifying options for building the application associated with the project. The first check box allows you to specify whether debugging information is printed to a window during the build. You can associate other auxiliary files with your project in the next set of controls. The auxiliary files are a splash bitmap (displayed as your application starts up) and an icon file (used as the icon for the application by Windows). By default, your application will not have a splash screen unless you specify a bitmap. The Allegro CL head of Franz Liszt icon is used as the icon if no icon file is specified.

Additional choices allow displaying the icon in the system tray (when the application is running) allowing access to the Console and a way to interrupt the application; full recompilation when building the project distribution with the `:runtime` feature; and specification of the runtime type (standard – no compiler, dynamic – with compiler, partners – custom license). Note you may only choose the runtime options you are licensed to use (see runtime.html).

### 4.17 The Project Manager Include and Advanced tabs

The include and advanced tabs allows further specification of options when building the application associated with the project. On the include tab, you can add and remove Allegro CL build modules. You can have these modules included or left out of the build by selecting or deselecting (so it is unhighlighted) modules. If a build module is not selected, its functionality will not be available in the application. If the functionality is truly unused, leaving it out is desirable since the resulting application will be smaller. But, if the module is in fact needed, the application may fail when the application executes and needs to use the needed but missing functionality (an error in the Console window may indicate this problem). There are various modules left out by default (none are illustrated). Simply click on a module to toggle its inclusion or exclusion. You are also asked whether you want to include the the top level (so there can be a Lisp listener -- some applications use that as the user interface). the debugger, or the compiler (you must be licensed to include the compiler). You can specify that local names in functions be saved. (Saving local names helps debugging, since debugger frames show actual local variable names rather than simple identifiers, but takes up space; it has no affect on the application absent a failure of some sort. See *load-local-names-info*.)

On the Advanced tab, various controls affect other aspects of the application.

Deliver a Runtime Bundle: a bundle file appropriate for the application (and containing only things allowable in runtime) will be included in the distribution. This allows for a smaller image size and code which may not be needed is not included in the image but is available for loading.

Purify: various constants (code vectors, strings, and others) will be placed in a .pll file included with the distribution.

Autoload Warning: if checked, a dialog will be displayed indicating the functions (if any) which will trigger an autoload of a module if called. If the necessary module is not available when the application is run, an error will be signaled if such a function is called. However, displaying a dialog means that a human must monitor the build process.

For US Government: if checked, an addition to the standard copyright notice is added which, complying with US regulations of software used by the US Government, indicates (as a simple copyright notice does not) that the US Government does not have free use of the software. Adding to the copyright notice is the only effect of checking this box.

Command Line Arguments: specifies default command line arguments that will be passed to the generated executable automatically. See default-command-line-arguments.

Old and New Space. The size (in bytes) of the initial old and new spaces in the application. See gc.html for definitions of old and new spaces. The default values are typically adequate, at least early in development.

Additional Build-Lisp-Image Arguments: build-lisp-image is the function that builds the application. It accepts many keyword arguments. Some common ones are specified by other controls on this tab. You can specify additional ones in this area.

See building-images.html and delivery.html for more information about these values (the oldspace, newspace, runtime-bundle, purify, and us-government keyword arguments to build-lisp-image).

### 4.18 The Project Manager Version Info tab

This tab is for use on Windows only (it is ignored on other platforms). It allows you to provide information which will be made the version info of your application is Windows tools the file manager.

### 4.19 Building the application

Two choices on the File menu, Build Project exe and Build Project Distribution, build your application.

Build Project exe is for simple testing. It builds your application in the project folder (where the .lpr file resides), resulting in a .exe file named <projectname>.exe (where <projectname> is the name specified on the Options tab). After using this command, you may need to copy DLL files from the Allegro Directory to the test directory to allow the standalone to run. (On the same machine, some of the DLL files may be in system-visible locations so copying may not be required.)

Build Project Distribution prompts you for a folder and copies all necessary files to that folder, including the application .exe file. The contents of this folder can be sent to users of your application (note: you are distributing copyrighted Allegro CL material along with your own files so you must be licensed to distribute).

### 4.20 Modifying the .lpr file

Since the .lpr file is automatically generated, you should not modify it. Modifications may be lost if the file is generated again.

Go to chapter 5. Go to the beginning of this chapter.

Copyright (c) Franz Inc. Lafayette, CA., USA. All rights reserved.

ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0