Working with Projects

$Revision: 1.1.1.1.8.1 $

Project Basics
Project Manager
Creating, Opening, and Saving Projects
Adding, Removing, and Saving Files in Projects
Compiling and Running a Project
Building an Application
Configuration Options for Projects
Using define-project
Project on-initialization function

Project Basics

A project is a collection of files used to build an application. A project can have the following files:

One project file with an extension of lpr. You can edit the project file but usually you let the system generate it for you automatically.
For each form, there are three possible files.
1. There is the form.cl file for all the source code for the form.
2. There is the form.bil file which is generated to describe creating the form and its components.
  You can look at a form.bil file but it is not recommended that you edit it.
3. There is an optional form.bml file describing the bitmaps used in the form. If the form has no bitmap, there is no form.bml file.
  Like the bil file, it is not recommended that you edit the form.bml file.
You can add any number of source code files to a project. Their extension is usually .cl.
One project can load one or more other projects. You can have an hierarchical project structure but you can only edit one project at a time.
You can add any number of libraries to a project with an extension of .dll.

In addition to file information, projects track information about building an application. Your project can create an executable (exe).

While working in Allegro CL, the name of the current project is displayed in the title of the main window. You can only edit one project at a time, but you can change any file that you want. Also, you can share files between projects by adding one or more sub-projects to your project.

Project Manager

As you work with a project, Allegro CL tracks all changes in the Project Manager window. Use the View | Project Manager to view the window. The General tab of the Project Manager window shows you information about all of the files in the project.

The project in this illustration has a little of everything:

A single library called npacl.dll
A single sub-project call data
Two forms (neither has been saved yet)
A single source file called examples/dll/fact

The order of the files in the list is the load order:

All libraries are loaded first
Next, all sub-projects are loaded in a depth-first order
Then, all files and forms are loaded in the order that they are specified.

The icons displayed in the General tab of the Project Manager let you see the type of files associated with the module. For forms, a window or running window icon is displayed. The running window icon marks the main form of the project. The main form of a project is the first window that is created for your application. When you run a project, the Project Manager runs the main form. You can change the main form of a project by selecting a different main form on the Options tab of the Project Manager.

The paths shown on the General tab of the Project Manager window are relative to the location of the project file. Therefore, form1.cl is located in the same directory as the project file. Both, the acl50pb71 library and the devel project, are located on separate drives from the project file. That is why you see their complete path displayed. For files associated with forms, the name shown is the name of the function used to create the running window of the form. For sub-projects, the name shown is the name of the sub-project.

Several buttons on the Project Manager's toolbar are for viewing parts of your project. The View Selected Form button creates and selects the form associated with the selected file. As you are working with forms, closing a form does not destroy it or cause you to lose your changes. Instead the form is hidden, and you can view it again by using the View Selected Form button. If you do not have a form file selected when you click on the View Selected Form button, then the code for the file is displayed in the editor. The View Selected Code button opens the file in the editor. The View Project Source button lets you see the code for the current project. The Inspect Project button inspects the current project. Using the inspector, you can specify event handlers for your project. More about the event handlers of projects in a different section of this document.

As you work in Allegro CL, the Project Manager window is automatically updated whenever you:

Add a new form. The new form file is added to project and list of possible main forms (on the Options tab).

Save (or Save As) a file. Then, the path of the file is updated.

Save (or Save As) the project file. Then, all paths are updated relative to the saved project file's location.

Change the name of a form. Then, the name of the form's file is updated. Also, the list of possible main forms is updated (on the Options tab).

Change the name of a sub-project. Then, the name of the sub-project is updated.

Change the name of the project (on the Options tab). Then, the title of the main window is updated.

The Options Tab of the Project Manager window lets you change the name of the current project, specify a default package and main form.

The package of a project is the default package for all source code files of forms. When you are working on source code, you can change the package but this lets you specify a default package.

The main form can be any one of the forms in a project. The main form of a project is the first window that is created for your application. When you run a project, the Project Manager runs the main form. By default, the main form is the first form in the project.

Creating, Opening and Saving Projects

There are five commands on the File menu for working with projects: Open Project, New Project, Save All, Build Project exe, and Build Project Distribution.

When you first start Allegro CL, a new project is automatically created for you. You can use Open Project to open any previously saved project by opening the project file, which has the .lpr extension. When you open a project, all files in the project are loaded and any open forms are displayed that were open when the project was saved. Depending on Open options set by the Tools | Option | Project tab, opening the project will either compile the changed files or compile every file in the project.

Use File | New Project to create a new project.

If the current project has any unsaved modifications, then you are prompted to save them before the new project is created. When you create a new project, you are prompted for the resulting type of application.

The Standard EXE option creates an executable that can be run by double-clicking on the exe file.

Use File | Save All to save the project file and all files associated with a project. Save All also saves any other files outside of the project that may have unsaved modifications. There is no Save Project because Save All is a superset of Save Project.

If you exit Allegro CL and you have any unsaved modifications, then you will be prompted to save them. Select or deselect anything that you do not want saved. For this figure, the current project needs to be saved as well as one other file named startup.cl and one named form8.

Adding, Removing and Saving Files in Projects

There are two approaches to adding a file to a project. The first approach uses the New Form command on the File menu.

When creating a new form, you are prompted for the type of window that you want. By default, dialog is selected. As you add your own window classes, they will automatically appear in this list if they are a subclass of one of the classes shown. The new form is automatically added to the current project.

proj3-60.bmp (207054 bytes)

The second approach uses the Project Manager. You must explicitly add source code files to your project using the Project Manager window. Therefore, you can edit any file that you choose without affecting your current project. In the Project Manager window, use the Add button on the Project Manager's toolbar to add files to your project. The Project Manager determines whether the file is a library, project, form or source code file based on its extension.

If the file extension is .dll, then a library is added.

If the file extension is .lpr, then a sub-project is added.

If the file extension is .bil, then a form file is added.

Otherwise, a source code or form file is added. If you select a file with a Lisp extension, then the Project Manager checks if there is a bil file with the name. If so, then a form file is added. Otherwise, a source file is added.

The only place that you can remove files from your project is in the Project Manager dialog. Closing a form or editor pane does not remove it from your project. In the Project Manager window, just select the file, and click on the Remove Selection button, which is labelled with an X on the Project Manager toolbar..

Use the up and down arrows on the Project Manager's toolbar for rearranging the files in your project.

Use the File | Save All menu command to save all files in your project. If you want to save an individual form or file, then use File | Save or File | Save As.

Compiling and Running a Project

There are two commands on the Tools menu for compiling a project: Compile Project and Full Compile. You will frequently use the Compile Project command because it will compile only the changed files. Full Compile compiles every file in the project. The process of compiling a project goes through the following steps.

Execute all before functions of the project.
Load all libraries of the project.
Compile all sub-projects of the current project in a depth first order.
For each file (or form file) of the project, compile it if necessary and load its fasl file(s).
Execute all after functions of the project.

There are two commands on the Run menu for running a project: Run Project and Run Form (both on the Run menu). Usually, you will use the Run Project command, which runs the initialization function of your project. By default, the initialization function of your project runs the main form of the project. If you specify an on-initialization event handler for your project, then on-initialization event handler will execute and do whatever you specify.

Run an individual form of a project by setting focus on the form and selecting Run | Run Form. Stop a running window by closing it or by using Run | Stop. If you run a form that already has a running window, then the running window is stopped and restarted. While running a window, you can continue to change its form but changes such as adding a button or changing its title will not take effect until the next time you run the form.

Before running a form or project, Allegro CL will try to save all your changes and compile the project. Control this behavior by changing the Configuration Options for Projects.

Building an Application

When development is complete, use the File | Build Project exe or File | Build Project Distribution commands to create an executable. The build process automatically creates other required files (such as the dxl). After a build, you can use your exe.

Create an executable file (exe). After making, double-click on the exe file that is created to run your new application.

Use File | Build Project exe whenever you want to test your executable on your machine. When you are ready to distribute your executable, use File | Build Project Distribution. Building a distribution creates your executable and copies all dependent files into a directory that you specify. The resulting directory provides the basis for installing your application on another user's machine.

If the build is not successful, you are told about errors. There is an alert in the Development Environment describing the error. At this point, you must correct the error and try to build your application again.

Use the Project Manager window to specify options to the build procedure. The Build tab of the Project Manager window lets you specify common options and the Advanced tab lets you specify more complicated options.

The following options are on the Build tab of the Project Manager window:

proj4-60.bmp (439014 bytes)

Allow Debug of Build Error. If checked, the Creating Image... window will remain if there is an error during the image build. (Otherwise, it goes away after reporting the error.)
Help File (grayed out): not supported.
Splash Bitmap (splash screen file). Default is none. Used to specify a startup splash bitmap file.
Icon (application icon) File. There is no default.
Check box to display Allegro CL Icon in the System Tray at application runtime. When checked, an icon appears in the System Tray.
Double-clicking on this icon brings up the Allegro CL console which can be useful to check for application runtime errors. If this check box is unchecked, the Allegro CL icon does not appear when the resulting application is being run.
Full Recompile for Runtime Conditionalization: when compiled in the IDE, :runtime is not on the *features* list, but the applictaion will contain that feature. If this box is checked, the project code will be recompiled with that feature enabled, so that conditionalized code will be handled appropriately.
Runtime Options: standard, dynamic, or partners. Select the one you are licensed for (standard is an image basically without the compiler, dynamic includes the compiler, and partners is based on a special, custom license). If you choose a type you are not licensed for, the build will fail with a message exaplining why.

The Advanced tab also controls build options.

Warning: These options are more advanced and should only be changed if you understand the consequences.

proj5-60.bmp (439014 bytes)

Build Includes is a list of modules to be included in the resulting executable. Most of these modules are related to Common Graphics. By default, everything in Common Graphics is included in your executable. You can remove modules if you do not need the capabilities. Note: For the cg module must always be included.
One large module is the aclwin302 module. The aclwin302 module provides all the backward compatibility code for V3.0.2 and is not necessary if you have new code or completely upgrade your V3.0.2 code.

There are various build modules related to Lisp, including: top-level, source-file-info, xref-info, and compiler.

Option to specify whether use is with the US Government. Default is no. Specify yes if the work is for (being paid for by) the United States Government. This choice have no effect on performance or included code. It only affects certain copyright notices, required because of special features of US copyright laws. You need not check this box if the work is being done for State governments in the United States, or for governments of any country other than teh United States.

Option to use presto mode. Default is no.

Purify: create a pll file to be included with the distribution.

Include Runtime Bundle. Create a bundle file which includes licensed modules not loaded into the system.

Option to specify old space size.

Option to specify new space size.

Configuration Options for Projects

You can control basic behavior of projects by selecting different options on the Project tab in Tools | Options window.

Options in the New group box control the behavior of the new projects. This includes the behavior of the new project that is created automatically during the startup process for Allegro CL.

proj6-60.bmp (532154 bytes)

By default, a new project has a single form and an empty editor buffer is created.

The Open group box determines what happens when you open a previously saved project. By default, the project is compiled which means that only changed files in the projects are compiled and all files in the project are loaded. If you want every file to be compiled, then select the Full Compile option.

The Run group box determines what happens before you run your project. By default, everything is saved and the project is compiled. Usually, you want to compile your changes before running a project, so that you can see the effect of your most recent work in the running window.

The Ask Before Auto-Saving box controls whether you are asked if you want to save project file (before running a project, e. g.).

Using define-project

You can let Allegro CL automatically create a project definition for you, and you can also write your own. Projects are defined using the define-project function. The following code shows the project definition for the example.

(in-package :common-graphics-user)


(define-project :name :project1
  :application-type (intern "Standard EXE" (find-package :keyword))
  :modules (list (make-instance 'form-module :name "form1"
                                :finder-function 'form1
                                :has-pixmap-file nil :create-on-open t)
                 (make-instance 'form-module :name "form2"
                                :finder-function 'form2
                                :has-pixmap-file nil :create-on-open t)
                 (make-instance 'module :name
                                "c:\\program files\\acl60\\examples\\dll\\fact"))
  :projects (list (make-instance 'project-module :name
                                 "c:\\program files\\acl60\\data"))
  :libraries (list (make-instance 'library-module :name
                                  "c:\\program files\\acl60\\npacl.dll"))
  :package-name :common-graphics-user
  :main-form 'form1
  :compilation-unit t
  :verbose nil
  :program-name "Allegro.Program"
  :readable-program-name "Allegro Program"
  :runtime-modules '(:cg :drag-and-drop :lisp-widget
                     :multi-picture-button :common-control
                     :edit-in-place :outline :grid :lisp-group-box
                     :header-control :progress-indicator-control
                     :common-status-bar :tab-control :trackbar-control
                     :up-down-control :dde :mci :carets :hotspots
                     :menu-selection :choose-list :directory-list
                     :color-dialog :find-dialog :font-dialog
                     :string-dialog :yes-no-list-dialog
                     :list-view-control :rich-edit :drawable :ole
                     :ole-server :www :aclwin302)
  :help-file-module (make-instance 'build-module :name "")
  :splash-file-module (make-instance 'build-module :name "")
  :icon-file-module (make-instance 'build-module :name "")
  :include-flags '(:compiler :top-level)
  :build-flags '(:exit-after-build :allow-debug :purify)
  :full-recompile-for-runtime-conditionalizations nil
  :old-space-size 256000
  :new-space-size 6144
  :runtime-build-option :standard
  :on-initialization 'default-init-function)




;; End of Project Definition

Most of the arguments have already been discussed and will be self-explanatory. The most advanced options are:

`verbose`	A `true` or `false` value. By default, it is `false`. When `true`, compiling a project writes compilation and loading messages to the Debug window.
`compilation-unit`	A `true` or `false` value. By default, it is `true`. When `false`, undefined functions warnings are determined and written after every file in the project is loaded.
`before-functions`	A list of functions that are called before a project is compiled. `before-function`s for a project do not take any arguments.
`after-functions`	A list of functions that are called after a project is compiled. `after-function`s for a project do not take any arguments.

There are several exported functions related to projects. More information about these functions is available in the on-line help via Help | Help on Selected Symbol.

current-project - a zero argument function that returns the current project.
find-project - takes the name or path of the project's file and returns the project.
compile-project - takes a project as an argument and compiles it.
full-compile-project - takes a project as an argument and compiles every file in that project.

Project on-initialization function

Follow the link to see the more complete documentation on on-initialization.

The on-initialization event handler is called whenever the project is "run" in the Development Environment. If specified, this function becomes the initialization-function of the app object during runtime. The initialization-function is executed by the default restart function during runtime.

During runtime, the initialization-function of the app object is invoked by the do-initialization function. The do-initialization function does different things depending on what type of application that you are running.

For Standard EXEs, the do-initialization function does the following:

If you specify an on-initialization event handler, then this function is invoked.
Otherwise, the do-default-initialization function is run passing the make function of the main form of the project if it exists. The do-default-initialization function does the following:

If there was a make function passed, then the make function is invoked to create the main window.
If there is a main-window and it is shrunk, then the main window is selected. This brings the main window to the front and gives it focus.
Returns the main window if it exists.