Training

Visual LISP: Introduction to Projects

Beginner and veteran AutoLISP® programmers alike ask these same questions: What is a Visual LISP™ Project and what does it do for me? The answer in a nutshell is that a project is a mechanism for organizing the functions in an application. You can use a project to simply keep your source files in order and provide a quick way to navigate among them. Or you can use a project to produce a compiled file that contains everything in one convenient package for easy distribution to users. In this article we are going to look first at the concepts related to a project in Visual LISP and then describe how to start a new project.

First Impressions

In your first visit to the Visual LISP integrated development environment (VLIDE) you most likely stumbled onto the Projects drop-down menu. And if you probed the menu entries they may not have made much sense. They probably didn't seem all that helpful at first glance either. That is because projects in Visual LISP do not come into play until after you have some code completed and have reached the point where you need to integrate these modules for testing or need some help in organizing them.

That means you don't start the coding work by defining a project as you do in VBA and some other programming tools. Instead you start the coding work in VLIDE by creating a file with a function in it. For veteran AutoLISP programmers this situation has not changed. You open an Editor window and start coding. But beginners sometimes have trouble with this concept. They may have been hoping for a program generator that walks them through the process of getting started and writing the wrappers of a new program.

The fact is you don't need a wizard program generator to get started with Visual LISP programming. When you start AutoCAD® software, Visual LISP is ready to run. The wizard program generators found in other programming languages exist to establish an environment or connection to the host platform. Visual LISP is different in that regard because it runs completely inside its platform (AutoCAD) and nowhere else. It does not need to set up any sort of integration environment since it already is fully integrated into its runtime environment.

Why Use a Project?

You can write a Visual LISP macro into a file and then simply load and run it. You can manipulate and utilize even complex Visual LISP applications that are defined across multiple source files in this manner. So you may be wondering, "Why use a project at all?" since you don't need a wizard to start up, and you can write complete applications using just files. Here are two very compelling reasons: with a project, you have the ability to navigate the source files quickly, and you can eventually create a single, compiled program file for much easier, faster distribution to other users and customers. Let's take a closer look at each benefit.

Ease of navigation between files

How well this feature works for you pretty much depends on how you use functions and files. When writing complex programs that involve multiple functions, you can define source files in a couple of ways. You might decide to put a function in a file so that there is a one-to-one relationship between a function and a file. I don't recommend that practice for very large projects as the number of files quickly exceeds a reasonable number. Instead I recommend putting functions into files of common groups. For example, you might have a file that contains a set of functions for dealing with matrices.

Figure 1: Simple Project window.

Jumping between the various files that comprise a project is easy, just double-click the file name in a project window (see Figure 1). Only two files show up in the window. But as you add more files to the project, the size of the project window increases, and when you reach a certain number of files, a scroll bar is included. Double clicking on the file name to display that file in a text edit window is one way the use of projects makes navigating between multiple files easy.

With the toolbar icons on the project window, you can manipulate the list of files and project properties, allowing for the creation of a single, compiled program. We will discuss the creation of compiled programs in a bit, first we need to see how to get to the properties from the dialog box in Figure 1. When you click the first icon on the left, the Project properties dialog box for the project appears (see Figures 2 and 3). In this dialog box, you can add more files to the project, change the order in which files are loaded in the project, or change the way the project is built. The second and third icons from the left in the Project window toolbar have to do with loading the project into memory for execution. The last two icons deal with the creation of project FAS (compiled) files. We'll discuss FAS files later on, but first let's take a look at a how to set up a project.

Setting Up a Project

Before you can set up a project you need some source code files. Given a set of files, the first thing you must do is create a project to store them in. You do this by going to the Project drop-down menu available in the main window of the VLIDE and selecting the New Project option. When you select this option, you are asked to name the new project and indicate which directory you want it stored in. Make sure that name is intuitive and easy to remember. The project file, with extension PRJ, is an ASCII text file that contains the project build directions. The project build options are very easy to manipulate from within the Project Properties dialog box (see Figures 2 and 3). But just for your own knowledge, take a look at the PRJ file itself to see what options it contains that might not initially appear in the Project Properties dialog box.
View Larger
Figure 2: Project Files tab in Project Properties dialog box.

Now that you've created the project, you must put the files you've previously designated into it. Open the Project Properties dialog box (by clicking on the first icon on left in Figure 1, or select Project Properties from the main VLIDE window pull down menu) and begin to fill in the needed file data on the Project Files tab. In the Look in field enter the location of the files. The available files display in the box below the Look in field. To select the files you want in the project, simply highlight each file from the list and then press the > button to move the file into the screen area to the right of the Look in field.

If for some reason, all the source files you need are not displayed below the Look in field, use the ellipsis (...) button to the right of that field to launch file explorer with which you can locate the desired folders and files for your project.

View Larger
Figure 3: Build Options tab, Project Properties dialog box.

Now that you've added files to the project, let's see what you can do with the Build Options tab in the Project properties dialog box (see Figure 3). With the options on this tab, you can define how your programs are to be built. Building a program converts the LSP source code files you work with into a format that loads and runs faster in Visual LISP. You can even tell Visual LISP to optimize the code in your LSP files while it is converting them. (Optimization is a subject unto itself and we won't explore it now.)

If you want to create a single module for all your build files—which may prove helpful—select the Single module for all radio button on the Merge files mode pane on this tab. With this option selected, you'll end up with a single file for all your program builds, which can then be loaded all at once. That way you don't end up searching through multiple directories for the build files and you ensure that other users can't change them. When the project is loaded, it is loaded in its entirety. There is nothing else you need to load.

You can further compile your project into an application using the Make Application option under the Files menu located in the main VLIDE window. Applications are yet another file type in Visual LISP. They also allow for the inclusion of different files in your project (such as DCL files). Before this gets too complicated, let's turn our attention to the file types and extensions we've talked about thus far.

FAS and VLX File Extensions

It helps to understand the file extensions that Visual LISP supports. If you have been programming in AutoLISP for some time you are already familiar with the LSP and DCL file extensions. They are the source code files manipulated with the text editor for the LISP and Dialog Control Language respectively. Prior to Visual LISP, these were the only two file types used unless your application created or manipulated a file of some other type.

Visual LISP introduces a host of new file types to the programmer. Most of the new files are to support your programming efforts and you will not directly manipulate them. I've mentioned the PRJ file already as part of the project setup information. Although this file is an ASCII text file, don't try to edit it except with the tools provided in Visual LISP. I've also briefly mentioned the FAS file. Let's take a look at what these files are about.

A FAS file is an encrypted LSP file with some optimization included. You should not (and in most cases, cannot) edit a FAS file directly, which prevents other users from messing with your source code.

FAS files load much faster into AutoCAD than LSP files because in FAS files all the comments have already been stripped out and all the excess white spaces removed. Additionally, if you have taken advantage of the optimization features when building your program FAS files, you may discover that the program runs several times faster as a result of the conversion.

Because a FAS file has the white spaces and comments removed, it is considered packed or compressed. That makes it much easier to distribute to others over the Internet or an Intranet. You can also put all the modules for your programs into a single FAS file, making it easy to send your programs to others.

FAS files are great, but they fall short in some areas. Visual LISP developers may need additional files in the application package (such as dialog box source code). That means they need a way to support multiple document mode that doesn't interfere with other applications and does not get lost as the user switches from one drawing to another. In these instances, developers should use another file format in the Visual LISP program, the VLX file.

A VLX file is built from FAS and DCL files (along with others you may wish to add) and is the best way to distribute your applications as a third-party developer. To create a VLX file use the options from the Make Application menu under the Files options. The primary advantage of a VLX file is that you can protect your variables and functions and better integrate them into an MDI environment coexisting with other applications. VLX files also load and execute code faster, can package dialog box files so that the application does not have to search for them, and support Active X automation. Unfortunately, we don't have the room to cover those topics in this article.

Wrapping Up

Projects are most useful when you are developing complex applications using Visual LISP. As such they may not be for everyone. If you only type in a few lines of code and save it to an LSP that is loaded into a menu then you may not need a project. But as that few lines of code grows and becomes a lot of lines of code, you will find projects to be extremely handy. Navigation through the code and packaging in a single, encrypted format are just two of the many cool VLIDE features. There's more, but that will have to await a later article or your own explorations. Until next time, keep on programmin'.